diff --git a/.agents/docs/2026-08-13-module-impl-split-report.md b/.agents/docs/2026-08-13-module-impl-split-report.md
new file mode 100644
index 00000000..e90eccfe
--- /dev/null
+++ b/.agents/docs/2026-08-13-module-impl-split-report.md
@@ -0,0 +1,483 @@
+# Module interface / implementation separation — report
+
+**Branch:** `refactor/module-impl-separation` (PR #545) vs `main` @ `b1563fe`
+**Date:** 2026-08-13
+**Machine:** Linux 6.8, 32 cores, gcc@16.1.0 via mcpp 2026.8.11.3
+
+## 1. What changed
+
+Every `.cppm` in `src/` carried both the module interface and its own
+implementation. Each is now a standard-conforming pair:
+
+| | file | module declaration | produces a BMI? |
+|---|---|---|---|
+| interface unit | `X.cppm` | `export module M;` | yes |
+| implementation unit | `X.cpp` | `module M;` | **no** |
+
+No directories moved. A partition's implementation goes into an implementation
+unit of the *primary* module (`module M;`), because `module M:part;` would be
+another partition and would still produce a BMI — and a module may have any
+number of implementation units.
+
+**What did change beyond moving text**, stated plainly rather than filed under
+"no behaviour changed":
+
+- **11 call sites in product code** now name their stream —
+  `std::println(stdout, ...)` instead of `std::println(...)`. `[print.fun]`
+  defines the short form *as* the long one, so the meaning is identical, but it
+  is an edit to product code and not a move (§8b explains why it was necessary).
+- **The musl release target moved from `gcc@15.1.0-musl` to `gcc@16.1.0-musl`**
+  (§8a). A different compiler major generates different code; this changes what
+  ships, even though no source changed to cause it.
+- **Namespace-scope `static` lost the keyword** on the entities that split, taking
+  them from internal to module linkage. Same single definition either way, and
+  module linkage still keeps the name module-private.
+- **Moved bodies lost their implicit `inline`**, which costs cross-TU inlining
+  without LTO. Measured: +0.10% binary size at `-O0`; `-O2` runtime is not
+  measured.
+
+Behaviour is otherwise unchanged, and it is checked rather than asserted: 1,262
+function definitions conserved exactly, 961 exported identifiers with none lost
+or gained, 110 module names byte-identical, and the full unit suite plus the e2e
+block green on six CI workflows.
+
+Four things left the interface:
+
+1. **Namespace-scope implementations** — 81 files, 779 entities, 26,606 body lines.
+2. **Class member bodies** — 29 files, 286 members, 3,845 body lines. A body
+   defined inside a class is implicitly `inline`, so it stayed in the BMI.
+3. **Module-private declarations** — a non-exported helper's declaration stays in
+   the interface only if something still *there* names it (an exported template,
+   an `inline`/`constexpr` body, a class member body). Otherwise it belongs in
+   the implementation unit: in the interface it sits in the BMI, so changing its
+   signature would recompile every importer for nothing.
+4. **The imports the bodies took with them** — 153 of 554 interface import edges
+   (28%). `split.py` *copies* the import list into the implementation unit, which
+   is right for the implementation and wrong for the interface: it was left
+   importing modules only the moved bodies used, and every such edge makes the
+   interface's BMI depend on a module it does not name. Found by self-review, not
+   by a compiler — nothing about it fails to build.
+
+### Interface surface
+
+| | lines | share of original |
+|---|---|---|
+| interface before | 46,253 | 100% |
+| interface after phases 1–3 | **14,666** | **32%** |
+| implementation after | 35,655 | |
+
+110 interface units, 92 implementation units (90 generated + `main.cpp` +
+`windows_syslibs.cpp`). Only one implementation unit is trivial, and it is the
+pre-existing `windows_syslibs.cpp` — none of the 90 generated units is an empty
+translation unit added for nothing.
+
+The interface is what every importer reads through the BMI. That is the number
+the build speed follows.
+
+## 2. Why it should matter — the fan-out that was there before
+
+Measured over the 99 local modules:
+
+| module | direct importers | transitive downstream |
+|---|---|---|
+| `xlings.platform` | 44 | **66** |
+| `xlings.core.log` | 40 | 54 |
+| `xlings.core.utils` | 8 | 44 |
+| `xlings.core.config` | 35 | 41 |
+| `xlings.core.palette` | 8 | 53 |
+| `xlings.libs.json` | 31 | 52 |
+
+Average transitive downstream: **10.7 modules**. Before the split, editing one
+line of `platform.cppm`'s implementation invalidated its BMI and recompiled 66
+translation units. After it, that edit lands in `platform.cpp`, which produces
+no BMI.
+
+## 3. Method
+
+Both refs are measured **in one worktree**, checking each out in turn: same
+path, same filesystem, same toolchain fingerprint, same warm dependency cache.
+The only variable is the source content.
+
+Only `src/` is swapped — `mcpp.toml` is held at the branch's version for both
+sides. That is deliberate: the dev target is `gcc@16.1.0` either way, so holding
+the manifest constant keeps the comparison to the source content and keeps the
+release-toolchain bump (§8a) out of it.
+
+- **Cold build** — `rm -rf target && mcpp build`, repeated. The project's own
+  target directory is removed so every project TU recompiles; the global
+  dependency cache (`~/.mcpp/build-cache`) stays warm on purpose, because the
+  dependencies are not what changed.
+- **Incremental build** — one implementation edit, timed rebuild. The edit
+  inserts a statement into a function *body*: a plain `touch` would not do,
+  because mcpp preserves a BMI's timestamp when a recompile produces
+  byte-identical content, so touching a `.cppm` skips every downstream unit and
+  flatters the before-picture. Same function, same statement, on both refs — the
+  file it lands in is the only difference, which is exactly what is being
+  measured.
+- **`mcpp test`** — the whole unit suite, 38 binaries. Each test file is a
+  non-module TU that imports many modules, so this is where interface size shows
+  up most directly. It is also the gate a developer actually waits on.
+
+Probe functions span the fan-out range **and** the two kinds of body, because
+they are not equivalent. A non-`inline` free function's body need not be in the
+BMI at all, so main may already avoid downstream work for it; a body defined
+inside a class **is** implicitly inline and therefore certainly in the BMI. If
+the split only helped the second kind, the first kind's numbers would say so.
+
+| probe | module | transitive downstream | on `main` it is |
+|---|---|---|---|
+| `parse_sudo_env` | `xlings.platform` | 66 | namespace-scope fn |
+| `level_string` | `xlings.core.log` | 54 | namespace-scope fn |
+| `strip_ansi` | `xlings.core.utils` | 44 | namespace-scope fn |
+| `parse_index_repos_json` | `xlings.core.config` | 41 | namespace-scope fn |
+| `shim_filename_` | `xlings.core.xself.doctor` | 16 | namespace-scope fn |
+| `workspace_install_targets` | `xlings.core.config` | 41 | **class member** (in the BMI) |
+| `compare_segment` | `xlings.core.semver` | 23 | **control** — `inline`, unmoved |
+
+`compare_segment` is the control: it stays `inline` in `semver.cppm` on **both**
+refs, so an edit to it invalidates semver's BMI either way and the **same**
+downstream set rebuilds. It therefore separates two effects that would otherwise
+be confounded:
+
+- **rebuild set** — an implementation edit stops invalidating the BMI at all, so
+  nothing downstream rebuilds. Only the moved probes get this.
+- **rebuild cost** — whatever does rebuild downstream is now a small interface
+  instead of a large one. The control gets this too.
+
+The control is expected to improve, just much less. If it improved as much as the
+moved probes, the split would not be what the numbers are measuring.
+
+Harness: `.agents/tools/module-split/{cold.sh,incr.py}`, driver
+`.agents/tools/module-split/measure-side.sh`.
+
+## 4. Measurements
+
+### Cold build — every project TU recompiled
+
+| ref | runs (s) | median |
+|---|---|---|
+| `main` @ b1563fe | 67.17 / 55.27 / 56.40 | **56.40** |
+| branch, phases 1–2 | 36.97 / 27.28 / 26.85 | 27.28 |
+| **branch, phases 1–3** | 32.96 / 25.71 / 26.09 | **26.09** |
+
+**2.16× faster**, and the direction was not a given: translation units roughly
+doubled (110 interfaces → 110 interfaces + 92 implementation units). Smaller
+BMIs pay more than the extra TUs cost. The first run on each side is the high
+one — that is page cache for freshly written files, which is why the median is
+the figure quoted.
+
+### Binary size
+
+| ref | dev binary (`-O0 -g`) |
+|---|---|
+| `main` | 124,238,424 B |
+| this branch | 124,368,072 B (**+0.10%**) |
+
+Dropping implicit `inline` costs cross-TU inlining without LTO, so this was
+worth checking rather than assuming. At `-O0` the answer is "no change worth
+naming"; a release-mode (`-O2`) size and runtime comparison is **not** measured
+here.
+
+### One implementation edit
+
+Two runs per probe. Both are shown rather than a median: with n=2 a median *is*
+the mean, so one outlier would move it silently.
+
+| probe | downstream | `main` (s) | branch (s) | best-to-best |
+|---|---|---|---|---|
+| `parse_sudo_env` | 66 | 63.12 / 54.04 | 4.46 / 4.60 | **12.1×** |
+| `level_string` | 54 | 62.42 / 51.38 | 4.49 / 4.56 | **11.4×** |
+| `strip_ansi` | 44 | 62.63 / 50.01 | 4.64 / 4.71 | **10.8×** |
+| `workspace_install_targets` (class member) | 41 | 49.00 / 58.95 | 6.43 / 6.31 | **7.8×** |
+| `parse_index_repos_json` | 41 | 62.13 / 49.08 | 19.69 / 6.36 | **7.7×** |
+| `shim_filename_` | 16 | 45.55 / 35.89 | 7.86 / 7.78 | **4.6×** |
+| `compare_segment` — **control**, `inline` on both | 23 | 43.58 / 54.53 | 17.24 / 17.54 | 2.5× |
+
+Those branch figures are from phases 1–2. Spot-checked again after phase 3, both
+improved slightly and neither regressed: `parse_sudo_env` 4.39 / 4.35 (from
+4.46 / 4.60) and the control 15.31 / 15.24 (from 17.24 / 17.54) — the control gains
+because the downstream interfaces it still rebuilds now carry smaller import
+closures too. Best-to-best for `parse_sudo_env` becomes **12.4×**.
+
+**On `main`, editing one function body costs about as much as building the whole
+project from scratch** — 54–63s against a 56.40s cold build. That is the shape
+the fan-out predicted: a high-fan-out interface edit rebuilds nearly everything,
+and before the split every body edit *was* an interface edit.
+
+The control lands at 2.5× while the moved probes land at 4.6–12.1×. The control's
+gain is the interfaces downstream simply being smaller to recompile; the gap
+between the two is what moving the body out actually bought.
+
+Both columns are phases 1–2. On the final tree the control is 2.9×
+(43.58 → 15.24) and `parse_sudo_env` is 12.4× (54.04 → 4.35) — the ratio between
+them, which is the part that matters, is unchanged.
+
+The branch's `parse_index_repos_json` first run (19.69s against 6.36s on the
+second) is an outlier, not a pattern — the same probe measured 6.51 / 6.32 in an
+earlier run of the same harness.
+
+### `mcpp test` — and the finding that changed the conclusion
+
+| ref | wall clock | vs main | result |
+|---|---|---|---|
+| `main` | 953.81s | — | 38 passed, 0 failed |
+| branch, phases 1–2 | 1104.83s | **1.16× SLOWER** | 38 passed, 0 failed |
+| **branch, phases 1–3** | **921.73s** | **1.03× faster** | 38 passed, 0 failed |
+
+Before phase 3 this was the one measurement that went the wrong way, and the
+report said so. Per test binary:
+
+| ref | min | median | max | sum over 38 | vs main |
+|---|---|---|---|---|---|
+| `main` | 20.86 | 21.18 | 41.16 | 832.5 | — |
+| branch, phases 1–2 | 23.96 | 24.92 | 45.53 | 1011.7 | **+3.74s** |
+| branch, phases 1–3 | 20.88 | **21.07** | 41.30 | **831.0** | **−0.11s** |
+
+**I had the mechanism wrong, and the fix is what proved it.** The regression looked
+like link cost: the overhead was near-constant per binary regardless of the test
+file's own size, and each test binary now links ~202 object files instead of ~112.
+That reasoning does not distinguish the two candidates — **BMI loading is also
+near-constant per TU**, because it depends on the import closure and not on the
+file being compiled.
+
+Phase 3 settled it as a controlled experiment. It changes **only** interface
+import edges: the object count each test binary links is identical before and
+after. If linking were the cause the penalty would have survived. It vanished
+entirely — +3.74s per binary became −0.11s.
+
+So the cause was the stale imports: every test TU was loading the BMIs of modules
+that nothing in the interfaces named, 28% more import edges than needed. The
+split does **not** meaningfully trade link time for compile time; it was carrying
+a defect that looked like that trade.
+
+The phases 1–2 figure also carries a ~27s pessimism — `src/` was regenerated
+part-way through that run — but that is noise next to the 179s the trim removed.
+
+## 5. Two gcc@16.1.0 internal compiler errors
+
+Both are compiler crashes, not code errors, and both blame the wrong entity.
+Both are recorded with their evidence in `outline.py`'s `ICE_SKIP`, and the two
+members keep their bodies inline.
+
+**`Counts::issues()`** (`core/xself/doctor.cppm`) — a two-line accessor.
+Defining it out-of-line segfaults cc1plus at `DoctorState st;` in
+`doctor.cpp:55` — a different type, in a different function.
+
+**`Config::instance_()`** (`core/config.cppm`) —
+`static Config& instance_() { static Config inst; return inst; }`. Its
+function-local static is where the module-attached `Config` is first completed.
+Move that body and the first-instantiation point moves with it, after which
+cc1plus segfaults compiling an **unrelated translation unit** — `doctor.cpp`, on
+a different type, in a different module. Nothing in the message names anything
+that changed. Found by bisecting config.cppm's 85 movable members
+(`bisect-member.sh`): #34 is the boundary and the other 84 are fine.
+
+A crashed cc1plus leaves a truncated `.gcm`, after which unrelated targets fail
+with `Bad file data` on the next build. `target/*/gcm.cache` and `~/.mcpp/bmi`
+both need clearing after one, or the next run reports a failure that has nothing
+to do with what you changed.
+
+## 6. Deliberately not done
+
+**Vestigial `inline` is left alone. 1,953 lines still sit in `inline` bodies in
+the interface:**
+
+| lines | file |
+|---|---|
+| 315 | `core/semver.cppm` |
+| 315 | `core/elf_same_source.cppm` |
+| 259 | `ui/layout.cppm` |
+| 217 | `core/closure_check.cppm` |
+| 180 | `core/subos.cppm` |
+| 71 | `core/palette.cppm` (53 transitive downstream) |
+
+In a module interface, `inline` means "put this body in the BMI so importers can
+inline it". Removing it is a performance-visibility decision, not a move — the
+maintainer's call, not a mechanical migration's. Stripping it would take the
+interface down by roughly another 13% and is the largest remaining lever.
+
+Measured on `main`'s own tree, the figure is **1,953 lines** — identical. So these
+are not lines the split left behind or failed to move; they are exactly what was
+already `inline` before it started, carried over untouched.
+
+## 7. Invariants checked statically
+
+Three things this refactor must not change, checked against the pre-split tree
+rather than assumed:
+
+| invariant | before | after | tool |
+|---|---|---|---|
+| exported identifiers | 961 | **961** (0 lost, 0 gained) | `export-surface.py` |
+| module names | 110 | **110, byte-identical** | — |
+| comment lines | 10,316 | 10,612 | — |
+
+The export-surface check had to be made depth-aware to mean anything: a
+line-anchored regex over an `export namespace` body also matches the **local
+variables** inside the function bodies that live there, so the first version
+reported 914 "lost exports" with names like `1`, `a`, `acc`, `activeBin` — an
+artefact of the bodies moving, not a lost export.
+
+The comment surplus is the comment above an `#if`, emitted to both units along
+with the directive. Getting there took a fix: dropping a module-private
+declaration from the interface first deleted the comment above it, 230 lines
+explaining helpers whose bodies are still there. Counting comment lines is what
+found that; the compiler had nothing to say about it.
+
+## 8. Three toolchains, three failures the dev build could not see
+
+The dev loop is one compiler (`gcc@16.1.0`, x86_64-linux-gnu). This project ships
+three more, and each one rejected something the dev build accepted.
+
+### 8a. `gcc@15.1.0-musl` — a range pipeline in an implementation unit
+
+`x86_64-linux-musl` (then `gcc@15.1.0-musl`) rejected `catalog.cpp`:
+
+```
+use of 'constexpr auto std::ranges::views::__adaptor::operator|(...)'
+before deduction of 'auto'
+```
+
+The body is byte-identical to main's. The same `std::views::transform` pipeline
+compiles in an interface unit and not in an implementation unit — under that
+compiler. `mcpp build --target x86_64-linux-musl` reproduces it locally: one
+error, one file.
+
+**Fixed by moving the musl target to `gcc@16.1.0-musl`** rather than by keeping
+the function in the interface. The reverse has bitten this project before:
+`views::split | ranges::to` compiled under 15.1.0-musl and made a whole module
+fail with "Bad file data" under 16.1.0, blaming an unmodified TU
+(`.agents/docs/2026-08-06-subos-architecture-proposal.md` §590). Range adaptors
+in modules are fragile in **both** directions across those two versions, so the
+two targets now share one compiler major instead of trading one breakage for the
+other.
+
+A stale object file hid this on the dev toolchain too: several regeneration
+rounds cleared only `target/*/gcm.cache` and kept the `.o` files, so
+`catalog.o` was never recompiled. Before believing a green build: a cold
+`rm -rf target`.
+
+### 8b. `llvm@20.1.7` — the stream-less `std::print` in an interface template
+
+macOS failed on the phase-2 push having passed on phase 1. Every TU
+instantiating a zero-argument `log::` template died inside libc++'s `<print>`:
+
+```
+call to deleted constructor of
+  'formatter<basic_format_string<char, basic_string<char>>, char>'
+```
+
+That is `std::print` no longer picking its `FILE*` overload and deducing `stdout`
+**as** the format string. libc++ implements `print(fmt, args...)` as
+`print(stdout, fmt, args...)`, so the `FILE*` overload has to win overload
+resolution at the point of instantiation — and for a template that stays in the
+interface, that point is in the **importer**. Once enough bodies leave the
+interface, clang 20 stops picking it.
+
+Two rules fix it, and neither needs a per-entity exclusion:
+
+- **11 call sites across 4 interfaces name their stream** — `core/log.cppm` (8)
+  and one each in `platform/{linux,macos,windows}.cppm`. `[print.fun]` defines the
+  two-argument form *as* `print(stdout, ...)`, so behaviour is identical and the
+  deduction is gone. Bodies that move to an implementation unit are left alone:
+  nothing instantiates those from another TU. (The commit message says 23 sites
+  in 6 files; that was the count of stream-less prints in the *pre-split*
+  `.cppm` set, and 12 of them belong to bodies that then moved to a `.cpp` and
+  were never normalised. 11 in 4 is what the tree carries.)
+- **8 implementation units gained `<cstdio>`** — `config.cpp`, `cmdprocessor.cpp`,
+  `xim/downloader.cpp`, `platform.cpp` and the four platform partitions — because
+  a body that ends up there can name `stdout`/`stderr`/`FILE` while its interface
+  has no global module fragment at all. `config.cppm` has none, and
+  `Config::print_paths()` lands in `config.cpp`.
+
+**Two wrong fixes came first, and both are reverted rather than left in the
+tree.** The first restored three declarations to `log.cppm` on the theory that
+interface reachability drove it — macOS then failed again, identically, which
+disproved it. The second pinned in-class bodies containing a stream-less print
+as "instantiation anchors"; it worked, but it was treating the symptom, and once
+the streams were named it was unnecessary.
+
+**The real lesson is the loop, not the bug.** `llvm@20.1.7` on **Linux**
+reproduces the macOS failure exactly — main builds clean, the split does not — so
+this was diagnosable in 40 seconds all along, and three CI cycles were spent
+before trying it. A *minimal* probe of the same shape does **not** reproduce it;
+it needs the whole project, which is what made the failure look
+macOS-libc-specific. `.agents/tools/module-split/clang-variant.sh` builds any variant with clang
+in an isolated copy; `clang-bisect.sh` binary-searches one file's members.
+
+### 8c. My own bug, for the record
+
+`open(f, 'w').write(ensure_cstdio(open(f).read()))` truncates the file before the
+read runs, so every implementation unit taking that path came out **empty**. It
+surfaced as undefined symbols at link time — never as an error in the file that
+was emptied.
+
+## 9. The gate this work should have started with
+
+Four compilers, and each one caught something the others accepted. All four are
+now runnable locally, and the first three take under a minute each:
+
+```bash
+rm -rf target && mcpp build                        # gcc@16.1.0   (dev)
+mcpp build --target x86_64-linux-musl              # gcc@16.1.0-musl (release)
+bash .agents/tools/module-split/clang-variant.sh check --all      # llvm@20.1.7  (macOS family)
+python3 .agents/tools/module-split/export-surface.py
+```
+
+The cold `rm -rf target` matters as much as the extra compilers: a kept object
+file hid §8a on the dev toolchain.
+
+Windows (`llvm@20.1.7`, MSVC-flavoured) and real macOS remain CI-only.
+
+## 10. What this report does not verify
+
+- **728 lines of the moved code are never compiled by a Linux build** —
+  `platform/windows.cpp` (326), `platform/macos.cpp` (151), `platform.cpp` (65),
+  `xself/uninstall.cpp` (50) and a long tail. The macOS and Windows CI jobs are
+  the gate for those, and both pass.
+
+  An earlier draft of this report said 1,228. That counter flagged any block whose
+  condition merely *mentioned* `_WIN32` or `__APPLE__`, which wrongly included
+  `#if !defined(_WIN32)` — true on Linux, and 208 of the miscounted lines were
+  `platform/unix.cpp`'s POSIX code that Linux does compile. The figure above comes
+  from evaluating the conditions with `__linux__` defined and the others not.
+- Runtime behaviour beyond the unit suite: the e2e block needs a release tarball
+  and network access, and runs in CI (green).
+- Release-mode (`-O2`) runtime performance. Dropping implicit `inline` costs
+  cross-TU inlining without LTO; binary size is reported, a runtime comparison is
+  not.
+
+## 11. An mcpp observation
+
+`mcpp` warns `module ':part' imported but not provided in this build` for a
+partition import inside an implementation unit. The warning is cosmetic — the
+generated dyndep edges are correct (`obj/part.o: dyndep | p4.m-part.gcm
+p4.m.gcm`), verified on a throwaway project — but its check pass does not expand
+the bare `:part` the way its dependency scanner does. The generated
+implementation units avoid the warning by relying on the primary interface's
+`export import :part;` rather than importing the partition directly.
+
+## 12. What self-review caught that no compiler would
+
+Everything below built green before it was found. That is the point: a green
+build is not evidence that a refactor is complete or that a report is true.
+
+| finding | how it surfaced |
+|---|---|
+| **153 of 554 interface import edges (28%) named nothing in the interface** — split.py copied the import list instead of moving it, so the interface kept depending on modules only the moved bodies used | reading the diff and asking what the interface still needs |
+| **`cold.sh` never ran from where it was committed** — its root was `dirname/../..`, right in `build/bench` and pointing at `.agents/` from `.agents/tools/module-split/`. Broken since this branch's first commit, and cited by this report | running the documented command |
+| **This report cited two scripts that are not in the repo** — `clang_variant.sh` and `measure_side.sh` lived under `build/`, which is gitignored, so the local gate could not be run by anyone reading it | checking that every path in the report exists |
+| **The unverified surface was overstated by 69%** — 1,228 lines "behind platform guards" is really 728; the counter flagged any block mentioning `_WIN32`/`__APPLE__`, including `#if !defined(_WIN32)`, true on Linux | re-deriving a number instead of trusting the first script that produced it |
+| **The control-probe claim was backwards** — the report said it "must show no improvement". It improves 2.5× on the phase-1–2 tree and 2.9× on the final one, because the interfaces it still rebuilds are smaller | comparing the claim against the measurement |
+| **A closure bug in the new tool** — `names \|= …` makes `names` local to the nested function | smoke-testing the tool against `main`, where it correctly finds only 4% to drop |
+| **Tool files were 644 while every other tool in `.agents/tools` is 755** | listing the mode bits |
+
+Four things the review checked and found clean, each stated as a number rather
+than an impression:
+
+| invariant | result |
+|---|---|
+| function definitions | **1,262 → 1,262**, none lost, none duplicated |
+| exported identifiers | **961 → 961**, 0 lost, 0 gained |
+| module names | 110, byte-identical |
+| dynamic-initialisation order | one module has globals on both sides of the split, and the one that stayed is `std::atomic<bool>{false}` — constant-initialised, so there is no order to preserve |
+| reconstructed `#if` guards | both verified against their originals; macOS and Windows CI confirm |
diff --git a/.agents/docs/2026-08-13-release-2026.8.13.1-notes.md b/.agents/docs/2026-08-13-release-2026.8.13.1-notes.md
new file mode 100644
index 00000000..01429f3b
--- /dev/null
+++ b/.agents/docs/2026-08-13-release-2026.8.13.1-notes.md
@@ -0,0 +1,104 @@
+# 2026.8.13.1 —— 「接口和实现分开」
+
+> 配套:PR #545。报告:`.agents/docs/2026-08-13-module-impl-split-report.md`
+> 工具:`.agents/tools/module-split/`(`regen.sh` 可逐字节复现本次提交树)
+
+## 1. 一句话
+
+110 个 `.cppm` 同时装着模块接口和它自己的实现,于是**任何函数体的改动都会改变 BMI,
+所有 importer 全部重编**。这一版把它们分成标准的一对:`X.cppm`(`export module M;`,
+产出 BMI)+ `X.cpp`(`module M;`,**不产出 BMI**)。
+
+接口从 46,253 行降到 14,666 行。但这次真正值钱的不是那个 2.16×,而是**唯一一个
+测回来是"变慢"的数,以及它最后被证明不是我说的那个原因。**
+
+## 2. 先说三条被自己推翻的前提
+
+都是我写下来之后被测量或编译器否掉的,记在这里而不是悄悄改掉。
+
+### 2.1 「TU 翻倍,冷构建会变慢」→ **反了,快 2.16×**
+
+110 个接口变成 110 接口 + 92 实现单元,TU 数量差不多翻倍,所以我在计划里写的是
+"冷构建方向不确定,可能变慢"。实测 56.40s → 26.09s。**更小的 BMI 带来的收益超过
+更多 TU 的成本**,而这只有测了才知道。
+
+### 2.2 「`mcpp test` 变慢是链接成本」→ **被 phase 3 证伪**
+
+单测套件一开始**慢 1.16×**(953.81s → 1104.83s),是唯一朝错方向走的数。
+我的论证是:每个测试二进制的开销近乎恒定(+3.74s)、与测试文件自身大小无关,
+而每个二进制现在要链接约 202 个目标文件而不是 112 个 —— 所以是链接。
+
+**这个论证站不住。** BMI 加载**同样**是"每 TU 近乎恒定",因为它取决于导入闭包
+而不是被编译的那个文件。我的证据无法区分两个候选原因。
+
+phase 3(裁剪残留 import)成了对照实验:它**只**改接口的 import 边,每个二进制
+链接的目标文件数前后完全一样。如果病因是链接,惩罚会留下来。它消失了 ——
+**每二进制 +3.74s 变成 −0.11s**,套件反过来比 main 快 1.03×。
+
+真因是:每个测试 TU 都在加载接口里根本没提到的模块的 BMI。
+
+### 2.3 「对照探针必须不改善」→ **改善 2.9×,而这才是它有用的地方**
+
+`compare_segment` 在两个分支上都是 `semver.cppm` 里的 `inline`,所以我写"它必须
+不变"。它变快了。原因是:编辑接口时两侧重编的**模块集合**相同,但分支上那些下游
+**接口本身小得多**。
+
+正确的表述是它分离了两件事 —— **重编集合**(实现改动不再让 BMI 失效,只有搬移过的
+探针拿到这个)和**重编成本**(仍要重编的东西现在更小,对照组也拿到)。对照组
+2.9×,搬移过的探针 4.6–12.4×,**差距才是搬移的贡献**。
+
+## 3. 数字
+
+| | main | 本版 | |
+|---|---|---|---|
+| 接口行数 | 46,253 | **14,666** | 32% |
+| 冷构建(3 次中位) | 56.40s | **26.09s** | **2.16×** |
+| 改一个实现(66 下游) | 54.04s | **4.35s** | **12.4×** |
+| 改一个类成员(41 下游) | 49.00s | **6.31s** | 7.8× |
+| 对照(两侧都 `inline`) | 43.58s | 15.24s | 2.9× |
+| `mcpp test`(38 个二进制) | 953.81s | **921.73s** | 1.03× |
+| dev 二进制 `-O0` | 124,238,424 B | +0.10% | |
+
+同一 worktree 内切换,只换 `src/`,路径/文件系统/工具链/依赖缓存全同。
+
+**main 上改一个函数体的代价约等于一次完整冷构建** —— 因为分离之前,每次改函数体
+其实都是在改接口。
+
+## 4. 四套工具链,四个 dev 构建看不见的失败
+
+`mcpp build`(`gcc@16.1.0`)是本项目四个编译器之一,另外三个各否掉了它接受的东西。
+
+| 工具链 | 否掉了什么 |
+|---|---|
+| `gcc@15.1.0-musl` | 搬进实现单元的 `std::views::transform` 管道。**修法是把 musl 目标升到 `gcc@16.1.0-musl`** —— 反方向的同类问题此前咬过本项目(`views::split \| ranges::to` 在 15 上过、在 16 上让整个模块以 "Bad file data" 失败),所以两个目标现在共用一个编译器主版本,而不是用一个破口换另一个 |
+| `llvm@20.1.7` | 接口 template 里**不带流参数的 `std::print`**。libc++ 把 `print(fmt,…)` 实现为 `print(stdout, fmt, …)`,所以 `FILE*` 重载必须在**实例化点**赢得重载决议 —— 而对接口 template 来说那个点在 importer 里。修法:4 个接口的 11 处显式写出流,外加 8 个实现单元补 `<cstdio>` |
+| `gcc@16.1.0` | 两个 ICE,各自报在**另一个模块的另一个类型**上。`Config::instance_()` 是二分 config.cppm 的 85 个成员到 #34 才定位的 |
+| 一个残留的 `.o` | 把第一个问题也藏过了 dev 工具链:清 `target/*/gcm.cache` 会留下 `.o`,该失败的 TU 根本没重编。**只有 `rm -rf target` 才算证明构建过** |
+
+`llvm@20.1.7` 在 **Linux** 上就能逐字复现 macOS 的失败,所以那本是一个 40 秒的回路,
+而我在此之前用掉了三轮 CI 去猜。**最小复现不行** —— 它需要整个项目,这正是那个
+clang 可见的 bug 一开始看起来像 macOS libc 特有问题的原因。
+
+## 5. 不变量:验过,不是断言
+
+| 不变量 | 结果 |
+|---|---|
+| 函数定义 | **1,262 → 1,262**,零丢失零重复 |
+| 导出标识符 | **961 → 961**,0 丢失 0 新增 |
+| 模块名 | 110 个逐字节一致 |
+| 动态初始化顺序 | 唯一跨单元分裂的模块里留下的是 `std::atomic<bool>{false}`(常量初始化),没有顺序可破坏 |
+| 重建的 `#if` 守卫 | 两处与原文核对一致;macOS / Windows CI 实证 |
+
+## 6. 刻意没做
+
+**残留的 `inline` 一行未动 —— 接口里仍有 1,953 行在 `inline` 函数体内。**
+在 main 的树上量到的是**同一个数字**,所以它们不是本次漏搬的,而是本来就 `inline`
+的原样带过来。在模块接口里 `inline` 的含义是"把函数体放进 BMI 供 importer 内联",
+去掉它是性能可见性决策,该由维护者定,不该由一次机械迁移悄悄做。这也是剩下最大的
+一根杠杆(约再压 13%)。
+
+## 7. 顺手记一笔(与本版无关)
+
+`mcpp.toml` 里 `ftxui = "6.1.9"` 在 `[dependencies]` 下,走的是**已废弃的裸名回退**,
+每次构建都会 warn,而该回退**在 mcpp 2026.9 移除**。一行的事(移到
+`[dependencies.compat]`),也是 `mcpp.lock` 反复变动的原因。本轮没动,留给维护者定。
diff --git a/.agents/plans/2026-08-13-module-interface-impl-separation.md b/.agents/plans/2026-08-13-module-interface-impl-separation.md
new file mode 100644
index 00000000..1bc12acc
--- /dev/null
+++ b/.agents/plans/2026-08-13-module-interface-impl-separation.md
@@ -0,0 +1,136 @@
+# Module interface / implementation separation
+
+**Branch:** `refactor/module-impl-separation`
+**Date:** 2026-08-13
+
+## Goal
+
+Split every C++23 module in `src/` into a standard-conforming pair:
+
+- `X.cppm` — **module interface unit** (`export module M;`): types, declarations,
+  templates, `constexpr`. Produces the BMI.
+- `X.cpp` — **module implementation unit** (`module M;`): the function bodies.
+  Produces **no BMI**.
+
+No directory moves, no behaviour changes, no new product code.
+
+## Why: the BMI is the recompile trigger
+
+Today every function body lives in the interface unit, so **every body edit
+changes the BMI**, and everything that imports the module recompiles.
+
+Measured fan-out over the 99 local modules (`build/bench/analyze.py` +
+import-graph scan):
+
+| module | direct importers | transitive downstream |
+|---|---|---|
+| `xlings.platform` | 45 | **63** |
+| `xlings.core.palette` | 8 | 53 |
+| `xlings.libs.json` | 31 | 52 |
+| `xlings.core.log` | 39 | 47 |
+| `xlings.core.config` | 34 | 35 |
+
+Average transitive downstream: **10.7 modules**. Editing one line in
+`platform.cppm`'s implementation rebuilds 64 translation units. After the
+split it rebuilds one.
+
+## Mechanism verified before writing any code
+
+`build/bench/probe2` (a throwaway 3-file mcpp project) established that mcpp
+and gcc@16.1.0 support the standard shape, and that the four rules the
+migration depends on actually hold:
+
+1. mcpp scans `.cpp` implementation units with P1689 dyndep and orders them
+   after their interface's BMI. `thing.cppm` → `thing.m.o` + `p2.thing.gcm`;
+   `thing.cpp` → `thing.o` and **no `.gcm`**.
+2. A **non-exported** helper declared in the interface and defined in the
+   implementation unit is callable from an **exported template** that gets
+   instantiated in a downstream TU. It links and runs.
+3. An `extern` module-linkage global declared in the interface and defined in
+   the implementation unit is readable from such a template.
+4. The `export` keyword must be omitted in the implementation unit; a default
+   argument must appear only in the interface; `constexpr` + `static_assert`
+   stay in the interface.
+
+Incremental behaviour on that probe:
+
+| edit | recompiled | time |
+|---|---|---|
+| implementation body (`thing.cpp`) | `thing.cpp` only | 0.29s |
+| interface (`thing.cppm`) | `.cppm` + `.cpp` + every importer | 0.79s |
+
+mcpp additionally preserves a BMI's mtime when a recompile produces
+byte-identical content, so an interface edit that does not change the BMI
+already avoids downstream work. That is why the bodies are the thing to move.
+
+## Classification rules
+
+Applied per namespace-scope (or class-scope) entity.
+
+**STAY in the interface — whole:**
+- type definitions (`struct` / `class` / `union` / `enum`), `using`, `typedef`,
+  namespace aliases, `concept`, `static_assert`
+- anything `template<...>` (11 sites, all variadic log/format wrappers)
+- `constexpr` / `consteval` functions and variables, `inline` variables
+- preprocessor conditionals that select declarations
+
+**SPLIT — declaration in the interface, definition in the implementation unit:**
+- non-template, non-`constexpr` function definitions at namespace scope,
+  exported or not (a non-exported helper still needs its declaration in the
+  interface when a template or another staying entity calls it)
+- out-of-line-able member functions of non-template classes, including
+  `static` member functions (defined as `T C::f(...)`, no `static` keyword)
+- namespace-scope variable definitions with dynamic initialisation
+
+**MOVE WHOLE to the implementation unit:**
+- anonymous-namespace blocks (4 files, all under `src/core/mirror/`)
+- namespace-scope `static` free functions **not** referenced by a staying
+  entity (internal linkage cannot span two units)
+
+## Ordering invariant
+
+All namespace-scope variable *definitions* of a module move to the same unit
+(the implementation unit), so their relative dynamic-initialisation order is
+preserved. Never split a module's globals across the two units.
+
+## Scope sizing
+
+| | lines | share |
+|---|---|---|
+| outside class bodies (free functions) | 39,258 | 84.9% |
+| inside class/struct bodies (need out-of-line members) | 6,995 | 15.1% |
+| total across 110 `.cppm` | 46,253 | |
+
+71 `static ... (...) {` definitions; indent 0 = namespace-scope internal
+linkage, indent 4 = static member functions (ordinary out-of-line definitions).
+
+Both groups are in scope. The class-heavy files are the high-fan-out ones
+(`config.cppm` is 93% class body **and** has 34 direct importers), so
+skipping them would forfeit much of the benefit.
+
+## Known trade-off, to be measured not assumed
+
+Moving a body out of the interface drops its implicit `inline`. Without LTO
+the release build loses those cross-TU inlining opportunities. The dev build
+is `-O0`; release is `-O2`. The report must carry binary size and, where
+cheap, a runtime check — not a claim that this is free.
+
+Cold-build direction is genuinely uncertain: TU count roughly doubles
+(110 → ~220), which costs, while every BMI gets smaller, which pays. Measure
+both cold and incremental.
+
+## Verification
+
+1. `mcpp build` succeeds.
+2. `mcpp test` — full unit suite green (must run `mcpp build` first;
+   `test_interface_protocol` drives the real binary).
+3. e2e suite via `tests/e2e/run_all.sh`.
+4. Benchmark main vs branch in this one worktree by switching branches, so
+   path, filesystem and toolchain fingerprint are identical and only source
+   content differs.
+
+## Baseline captured (main, this worktree)
+
+Cold `mcpp build` after `rm -rf target`, warm global dependency cache, 32 cores:
+**68.85s / 55.14s / 64.12s**. Variance is ~25%, so the comparison needs
+repeats and a median, not a single pair of numbers.
diff --git a/.agents/tools/module-split/analyze.py b/.agents/tools/module-split/analyze.py
new file mode 100755
index 00000000..6cc4fab7
--- /dev/null
+++ b/.agents/tools/module-split/analyze.py
@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Size the interface/implementation split: how much of each .cppm is a
+namespace-scope function body (movable) vs inside a class body (needs
+out-of-line member syntax) vs must-stay (template/constexpr/type)."""
+import re, glob, sys, collections
+
+def strip_for_scan(s):
+    """Blank out string/char literals and comments so brace matching is sane.
+    Keeps byte offsets identical."""
+    out = list(s)
+    i, n = 0, len(s)
+    while i < n:
+        c = s[i]
+        if c == '/' and i + 1 < n and s[i+1] == '/':
+            j = s.find('\n', i)
+            j = n if j < 0 else j
+            for k in range(i, j): out[k] = ' '
+            i = j
+        elif c == '/' and i + 1 < n and s[i+1] == '*':
+            j = s.find('*/', i + 2)
+            j = n if j < 0 else j + 2
+            for k in range(i, j):
+                if s[k] != '\n': out[k] = ' '
+            i = j
+        elif c in '"\'':
+            q = c; j = i + 1
+            # raw strings R"(...)"
+            if q == '"' and i > 0 and s[i-1] == 'R':
+                m = re.match(r'"([^(]*)\(', s[i:])
+                if m:
+                    delim = m.group(1)
+                    end = s.find(')' + delim + '"', i)
+                    j = n if end < 0 else end + len(delim) + 2
+                    for k in range(i, j):
+                        if s[k] != '\n': out[k] = ' '
+                    i = j; continue
+            while j < n:
+                if s[j] == '\\': j += 2; continue
+                if s[j] == q: j += 1; break
+                if s[j] == '\n': break
+                j += 1
+            for k in range(i, j):
+                if s[k] != '\n': out[k] = ' '
+            i = j
+        else:
+            i += 1
+    return ''.join(out)
+
+tot = collections.Counter()
+per_file = []
+for f in sorted(glob.glob('src/**/*.cppm', recursive=True)):
+    src = open(f).read()
+    scan = strip_for_scan(src)
+    lines = src.count('\n')
+    # find class/struct/union bodies at any depth: `struct X ... {` ... matching `}`
+    cls_lines = 0
+    for m in re.finditer(r'\b(?:struct|class|union)\s+(\w+)[^;{]*\{', scan):
+        # skip forward declarations (handled by the `{` requirement)
+        start = scan.index('{', m.start())
+        depth, i = 0, start
+        while i < len(scan):
+            if scan[i] == '{': depth += 1
+            elif scan[i] == '}':
+                depth -= 1
+                if depth == 0: break
+            i += 1
+        cls_lines += src.count('\n', start, i)
+    tot['lines'] += lines
+    tot['class_body_lines'] += cls_lines
+    per_file.append((lines, cls_lines, f))
+
+print(f"total .cppm lines      : {tot['lines']}")
+print(f"inside class/struct    : {tot['class_body_lines']}  "
+      f"({100*tot['class_body_lines']/tot['lines']:.1f}%)")
+print(f"outside class/struct   : {tot['lines']-tot['class_body_lines']}  "
+      f"({100*(tot['lines']-tot['class_body_lines'])/tot['lines']:.1f}%)")
+print()
+print("files with the most class-body code:")
+per_file.sort(key=lambda r: -r[1])
+for lines, cls, f in per_file[:12]:
+    print(f"  {cls:5}/{lines:5} ({100*cls/max(lines,1):4.0f}%)  {f}")
+
+# namespace-scope `static` free functions (internal linkage -> cannot be
+# declared in one unit and defined in another)
+print()
+stat_fns = []
+for f in sorted(glob.glob('src/**/*.cppm', recursive=True)):
+    scan = strip_for_scan(open(f).read())
+    for m in re.finditer(r'^([ \t]*)static\s+(?!.*\b(?:constexpr|inline)\b)([\w:<>,& *]+?)\s+(\w+)\s*\([^;]*?\)\s*(?:const\s*)?\{', scan, re.M):
+        stat_fns.append((f, m.group(3), len(m.group(1))))
+print(f"namespace/class-scope `static ... (...) {{` definitions: {len(stat_fns)}")
+for f, name, ind in stat_fns[:15]:
+    print(f"  indent={ind:2} {name:28} {f}")
diff --git a/.agents/tools/module-split/bisect-member.sh b/.agents/tools/module-split/bisect-member.sh
new file mode 100755
index 00000000..3e913504
--- /dev/null
+++ b/.agents/tools/module-split/bisect-member.sh
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Binary-search the smallest number of outlined members of ONE file that makes
+# the build ICE.  Prints the boundary; member N (1-based) is the trigger.
+#
+# Usage: bisect_member.sh <file.cppm> <hi>
+set -u
+FILE="${1:?file}"; HI="${2:?upper bound}"
+lo=0            # known good
+hi=$HI          # known bad
+while [ $((hi - lo)) -gt 1 ]; do
+  mid=$(( (lo + hi) / 2 ))
+  git checkout b1563fe -- src/
+  git clean -fq src/
+  python3 .agents/tools/module-split/split.py --all --write >/dev/null
+  python3 .agents/tools/module-split/outline.py --write --limit "$mid" "$FILE" >/dev/null
+  rm -rf target/x86_64-linux-gnu/*/gcm.cache
+  mcpp build >build/bench/bm.log 2>&1
+  ice=$(grep -ac 'internal compiler error' build/bench/bm.log)
+  err=$(grep -ac ' error: ' build/bench/bm.log)
+  if [ "$ice" -gt 0 ]; then
+    echo "  limit=$mid  ICE      -> bad"
+    hi=$mid
+  elif [ "$err" -gt 0 ]; then
+    echo "  limit=$mid  errors=$err (not an ICE) -> treating as bad"
+    grep -a ' error: ' build/bench/bm.log | head -2
+    hi=$mid
+  else
+    echo "  limit=$mid  clean    -> good"
+    lo=$mid
+  fi
+done
+echo "BOUNDARY: $lo good, $hi bad -> member #$hi is the trigger"
diff --git a/.agents/tools/module-split/clang-bisect.sh b/.agents/tools/module-split/clang-bisect.sh
new file mode 100755
index 00000000..1a142eb8
--- /dev/null
+++ b/.agents/tools/module-split/clang-bisect.sh
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Binary-search the smallest number of outlined members of ONE file that makes
+# the clang build fail.  Member N (1-based, in outline order) is the trigger.
+#
+#   clang_bisect.sh <file.cppm> <hi>
+set -u
+FILE="${1:?file}"; HI="${2:?upper bound}"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$HERE/../../.." && pwd)"
+cd "$ROOT" || exit 1
+lo=0
+hi=$HI
+while [ $((hi - lo)) -gt 1 ]; do
+  mid=$(( (lo + hi) / 2 ))
+  out=$(LIMIT=$mid bash "$HERE/clang-variant.sh" "b$mid" "$FILE" 2>&1 | tail -1)
+  if echo "$out" | grep -q 'rc=0 errors=0'; then
+    echo "  limit=$mid  clean -> good"
+    lo=$mid
+  else
+    echo "  limit=$mid  FAIL  -> bad   ${out#*errors=}"
+    hi=$mid
+  fi
+done
+echo "BOUNDARY: $lo good, $hi bad -> member #$hi is the trigger"
diff --git a/.agents/tools/module-split/clang-variant.sh b/.agents/tools/module-split/clang-variant.sh
new file mode 100755
index 00000000..15277235
--- /dev/null
+++ b/.agents/tools/module-split/clang-variant.sh
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Build one split variant with clang 20.1.7 (the macOS toolchain family) in an
+# isolated copy under build/ (gitignored), so the diagnosis loop is ~40s instead of
+# a 13-minute CI cycle.  main builds clean under this toolchain, so any failure
+# here belongs to the split.
+#
+#   clang_variant.sh <label> [outline-file.cppm ...]     # phase 1 + phase 2 on those files
+#   clang_variant.sh <label> --all                        # phase 1 + phase 2 everywhere
+#   clang_variant.sh <label>                              # phase 1 only
+#
+# main + clang builds clean, so any failure here is the split's.
+set -u
+LABEL="${1:?label}"; shift
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+P="$ROOT/build/cv"
+cd "$ROOT" || exit 1
+
+rm -rf "$P"; mkdir -p "$P"
+python3 - <<'PY'
+import subprocess, os
+P = 'build/cv'
+for f in subprocess.run(['git','ls-tree','-r','--name-only','b1563fe','src/'],
+                        capture_output=True, text=True).stdout.split():
+    t = subprocess.run(['git','show',f'b1563fe:{f}'], capture_output=True).stdout
+    os.makedirs(os.path.join(P, os.path.dirname(f)), exist_ok=True)
+    open(os.path.join(P, f), 'wb').write(t)
+toml = open('mcpp.toml').read().replace('default = "gcc@16.1.0"',
+                                        'default = "llvm@20.1.7"')
+open(P + '/mcpp.toml', 'w').write(toml)
+PY
+cp mcpp.lock "$P/mcpp.lock"
+
+cd "$P" || exit 1
+python3 "$ROOT/.agents/tools/module-split/split.py" --all --write >/dev/null
+if [ "$#" -gt 0 ]; then
+  python3 "$ROOT/.agents/tools/module-split/outline.py" --write ${LIMIT:+--limit $LIMIT} "$@" >/dev/null
+fi
+mcpp build >"clang.$LABEL.log" 2>&1
+rc=$?
+errs=$(grep -ac 'error: ' "clang.$LABEL.log")
+failed=$(grep -a -oE 'failed: obj/\S+' "clang.$LABEL.log" | sort -u | tr '\n' ' ')
+echo "CLANG $LABEL  rc=$rc errors=$errs  $failed  (n=$#)"
diff --git a/.agents/tools/module-split/cold.sh b/.agents/tools/module-split/cold.sh
new file mode 100755
index 00000000..e7de98ee
--- /dev/null
+++ b/.agents/tools/module-split/cold.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Cold full-build timing.  Usage: cold.sh <label> [runs]
+#
+# "Cold" = the project's own target/ is removed, so every project TU is
+# recompiled.  The GLOBAL dependency cache (~/.mcpp/build-cache) stays warm
+# on purpose: we are measuring xlings's own sources, not its dependencies.
+set -uo pipefail
+WT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+LABEL="${1:?usage: cold.sh <label> [runs]}"
+RUNS="${2:-1}"
+OUT="$WT/build/bench"
+mkdir -p "$OUT"
+cd "$WT" || exit 1
+for i in $(seq 1 "$RUNS"); do
+  rm -rf target
+  s=$(date +%s.%N)
+  mcpp build >"$OUT/cold.$LABEL.$i.log" 2>&1
+  rc=$?
+  e=$(date +%s.%N)
+  printf 'COLD %-22s run=%s rc=%s secs=%.2f\n' "$LABEL" "$i" "$rc" "$(echo "$e - $s" | bc)"
+  if [ "$rc" -ne 0 ]; then
+    echo "--- tail of $OUT/cold.$LABEL.$i.log ---"
+    tail -30 "$OUT/cold.$LABEL.$i.log"
+    exit "$rc"
+  fi
+done
diff --git a/.agents/tools/module-split/export-surface.py b/.agents/tools/module-split/export-surface.py
new file mode 100755
index 00000000..967b2f59
--- /dev/null
+++ b/.agents/tools/module-split/export-surface.py
@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Compare the exported-name surface of the interface units before and after the
+split.  Nothing about this refactor may add or remove an export -- that is the
+strongest invariant checkable without running the program.
+
+It has to be depth-aware.  A line-anchored regex over an `export namespace`
+body also matches the LOCAL VARIABLES inside the function bodies that live
+there, so before the split it "sees" 900 more names than after -- an artefact of
+the bodies moving, not a lost export.  So the namespace body is scanned with the
+same item scanner the splitter uses, and only top-level declarators count.
+"""
+import re, glob, subprocess, sys
+sys.path.insert(0, '.agents/tools/module-split')
+from split import scrub, scan_items, mask_operator, NS_HEAD
+
+KW = {'const', 'static', 'inline', 'constexpr', 'consteval', 'extern', 'virtual',
+      'explicit', 'friend', 'operator', 'noexcept', 'return', 'template',
+      'typedef', 'mutable', 'volatile', 'namespace', 'export'}
+
+
+def item_name(head: str) -> set[str]:
+    h = mask_operator(scrub(head)).strip().rstrip(';').strip()
+    if not h:
+        return set()
+    t = re.match(r'(?:export\s+)?(?:struct|class|union|enum(?:\s+class)?)\s+(\w+)', h)
+    if t:
+        return {t.group(1)}
+    a = re.match(r'(?:export\s+)?using\s+(\w+)\s*=', h)
+    if a:
+        return {a.group(1)}
+    u = re.match(r'(?:export\s+)?using\s+[\w:]*?::(\w+)\s*$', h)
+    if u:
+        return {u.group(1)}
+    if re.match(r'(?:export\s+)?(?:import|module)\b', h):
+        return set()
+    o = h.find('(')
+    region = h[:o] if o >= 0 else h
+    ids = [i for i in re.findall(r'\b([A-Za-z_]\w*)\b', region) if i not in KW]
+    if not ids:
+        return set()
+    # for a function the declarator-id is the identifier just before '('
+    if o >= 0:
+        m = list(re.finditer(r'([\w~]+)\s*$', region))
+        if m and m[-1].group(1) not in KW:
+            return {m[-1].group(1)}
+    return {ids[-1]}
+
+
+def collect(text: str, inherited_export=False) -> set[str]:
+    m = re.search(r'^export module [\w.]+(?::\w+)?;', text, re.M)
+    body = text[m.end():] if m else text
+    return walk(body, inherited_export)
+
+
+def walk(body: str, inherited: bool) -> set[str]:
+    names = set()
+    for it in scan_items(body):
+        if it.kind in ('preproc', 'blank', 'access'):
+            continue
+        exported = inherited or re.match(r'\s*export\b', it.head) is not None
+        if it.body and NS_HEAD.match(it.head):
+            names |= walk(it.body[1:-1], exported)
+            continue
+        if exported:
+            names |= item_name(it.head)
+    return names
+
+
+files = [f for f in subprocess.run(
+    ['git', 'ls-tree', '-r', '--name-only', 'b1563fe', 'src/'],
+    capture_output=True, text=True).stdout.split() if f.endswith('.cppm')]
+
+before, after = set(), set()
+for f in files:
+    t = subprocess.run(['git', 'show', f'b1563fe:{f}'],
+                       capture_output=True, text=True).stdout
+    before |= collect(t)
+for f in glob.glob('src/**/*.cppm', recursive=True):
+    after |= collect(open(f).read())
+
+print(f'exported identifiers  before={len(before)}  after={len(after)}')
+lost, gained = sorted(before - after), sorted(after - before)
+print(f'lost={len(lost)}  gained={len(gained)}')
+if lost:
+    print('  LOST  :', lost[:40])
+if gained:
+    print('  GAINED:', gained[:40])
diff --git a/.agents/tools/module-split/incr.py b/.agents/tools/module-split/incr.py
new file mode 100755
index 00000000..d70cb676
--- /dev/null
+++ b/.agents/tools/module-split/incr.py
@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Incremental-rebuild benchmark: how much does ONE implementation edit cost?
+
+The edit must change code generation, not just the mtime.  mcpp preserves a
+BMI's timestamp when a recompile produces byte-identical content, so a plain
+`touch` of a .cppm would skip every downstream unit and flatter the
+before-picture.  So we insert a statement into a function BODY:
+
+  * before the split the body lives in the .cppm, so the BMI changes and every
+    importer recompiles
+  * after the split it lives in the .cpp, so one TU recompiles
+
+Same function, same statement, on both branches — the file it lands in is the
+only difference, which is exactly the thing being measured.
+
+Usage:  incr.py <function-name> [<function-name> ...] [--runs N]
+"""
+from __future__ import annotations
+import argparse, glob, os, re, subprocess, sys, time
+
+MARK = 'volatile int _xl_bench_probe'
+
+
+def find_body(fn: str):
+    """Locate `fn`'s definition; return (path, insert_offset) just past its '{'."""
+    pat = re.compile(r'(?:^|\n)[ \t]*(?:export\s+)?[\w:<>,&*\[\]\s]*?\b'
+                     + re.escape(fn) + r'\s*\([^;{]*?\)[^;{]*?\{')
+    for path in sorted(glob.glob('src/**/*.cpp', recursive=True)) + \
+                sorted(glob.glob('src/**/*.cppm', recursive=True)):
+        src = open(path).read()
+        m = pat.search(src)
+        if m:
+            return path, m.end()
+    return None, None
+
+
+def timed_build():
+    t = time.time()
+    p = subprocess.run(['mcpp', 'build'], capture_output=True)
+    return time.time() - t, p.returncode, p.stdout.decode(errors='replace')
+
+
+def count_compiles(out: str) -> int:
+    return len(re.findall(r'\bg\+\+\b.*?-c\s', out))
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('fns', nargs='+')
+    ap.add_argument('--runs', type=int, default=2)
+    a = ap.parse_args()
+
+    branch = subprocess.run(['git', 'branch', '--show-current'],
+                            capture_output=True).stdout.decode().strip()
+    # make sure we start from an up-to-date tree
+    s, rc, _ = timed_build()
+    if rc != 0:
+        print('baseline build FAILED — aborting', file=sys.stderr)
+        return 1
+    print(f'# branch={branch}  warm-up build {s:.2f}s')
+
+    for fn in a.fns:
+        path, off = find_body(fn)
+        if not path:
+            print(f'INCR {branch:34} {fn:26} NOT FOUND')
+            continue
+        for i in range(a.runs):
+            src = open(path).read()
+            patched = src[:off] + f' {MARK}_{i} = {i};' + src[off:]
+            open(path, 'w').write(patched)
+            secs, rc, out = timed_build()
+            open(path, 'w').write(src)          # revert
+            kind = 'impl(.cpp)' if path.endswith('.cpp') else 'iface(.cppm)'
+            print(f'INCR {branch:34} {fn:26} run={i} rc={rc} '
+                  f'secs={secs:6.2f} in={kind:12} {path}')
+            if rc != 0:
+                print(out[-800:])
+                break
+        # leave the tree rebuilt so the next measurement starts warm
+        timed_build()
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())
diff --git a/.agents/tools/module-split/measure-side.sh b/.agents/tools/module-split/measure-side.sh
new file mode 100755
index 00000000..6ce94df1
--- /dev/null
+++ b/.agents/tools/module-split/measure-side.sh
@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Measure one side of the comparison end to end, unattended.
+#
+#   measure_side.sh <ref> <label> [cold-runs] [with-test]
+#
+# Checks out src/ from <ref> into this worktree (HEAD is untouched), then runs
+# cold builds, incremental-edit builds, and optionally the whole unit suite.
+set -u
+REF="${1:?ref}"; LABEL="${2:?label}"; RUNS="${3:-3}"; WITH_TEST="${4:-no}"
+TOOLS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$TOOLS/../../.." && pwd)"
+# logs and timings land in build/ (gitignored), never in the tools directory
+HERE="$ROOT/build/bench"
+mkdir -p "$HERE"
+cd "$ROOT" || exit 1
+OUT="$HERE/measure.$LABEL.txt"
+: >"$OUT"
+
+log() { echo "$@" | tee -a "$OUT"; }
+
+git checkout -q "$REF" -- src/ || { log "checkout failed"; exit 1; }
+python3 - "$REF" <<'PY' | tee -a "$OUT"
+import subprocess, sys, os, glob
+ref = sys.argv[1]
+keep = set(subprocess.run(['git', 'ls-tree', '-r', '--name-only', ref, 'src/'],
+                          capture_output=True, text=True).stdout.split())
+n = 0
+for f in glob.glob('src/**/*', recursive=True):
+    if os.path.isfile(f) and f not in keep:
+        os.remove(f); n += 1
+c = sum(open(f).read().count('\n') for f in glob.glob('src/**/*.cppm', recursive=True))
+p = sum(open(f).read().count('\n') for f in glob.glob('src/**/*.cpp', recursive=True))
+print(f'TREE removed={n} cppm_files={len(glob.glob("src/**/*.cppm", recursive=True))} '
+      f'cpp_files={len(glob.glob("src/**/*.cpp", recursive=True))} '
+      f'iface_lines={c} impl_lines={p}')
+PY
+
+for i in $(seq 1 "$RUNS"); do
+  rm -rf target
+  s=$(date +%s.%N)
+  mcpp build >"$HERE/m.$LABEL.cold.$i.log" 2>&1
+  rc=$?
+  e=$(date +%s.%N)
+  log "$(printf 'COLD %-8s run=%s rc=%s secs=%.2f' "$LABEL" "$i" "$rc" "$(echo "$e - $s" | bc)")"
+  [ "$rc" -ne 0 ] && { tail -25 "$HERE/m.$LABEL.cold.$i.log" | tee -a "$OUT"; exit 1; }
+done
+
+find target -path '*/bin/xlings' -type f -printf "SIZE $LABEL %s bytes\n" | tee -a "$OUT"
+
+# workspace_install_targets is a CLASS MEMBER on main (implicitly inline, so its
+# body is in the BMI) and an out-of-line definition on the branch -- the case the
+# split is supposed to fix.  compare_segment is the CONTROL: `inline` in
+# semver.cppm on both refs, so it must show no improvement; if it does, the
+# measurement is noise.
+python3 "$TOOLS/incr.py" --runs 2 \
+    parse_sudo_env level_string strip_ansi parse_index_repos_json shim_filename_ \
+    workspace_install_targets compare_segment \
+  2>&1 | sed "s/^/[$LABEL] /" | tee -a "$OUT"
+
+if [ "$WITH_TEST" = "with-test" ]; then
+  s=$(date +%s.%N)
+  mcpp test >"$HERE/m.$LABEL.test.log" 2>&1
+  rc=$?
+  e=$(date +%s.%N)
+  log "$(printf 'TEST %-8s rc=%s secs=%.2f' "$LABEL" "$rc" "$(echo "$e - $s" | bc)")"
+  grep -a 'test result' "$HERE/m.$LABEL.test.log" | tee -a "$OUT"
+fi
+log "DONE $LABEL"
diff --git a/.agents/tools/module-split/outline.py b/.agents/tools/module-split/outline.py
new file mode 100755
index 00000000..f18b08f4
--- /dev/null
+++ b/.agents/tools/module-split/outline.py
@@ -0,0 +1,434 @@
+#!/usr/bin/env python3
+"""Phase 2 of the interface/implementation split: move class member function
+BODIES out of the class definition in the .cppm into out-of-line definitions in
+the module's .cpp.
+
+Phase 1 (split.py) moved namespace-scope functions.  What is left in the
+interface is the 15% of the code that sits inside a class body, where a body is
+implicitly inline and therefore still part of the BMI — so editing it still
+recompiles every importer.  `Config` is the case that matters: 93% class body
+and 34 direct importers.
+
+Out-of-lining a member is more than moving text:
+
+  * the declarator-id becomes `C::name`, and everything AFTER it is looked up in
+    class scope — but the RETURN TYPE comes before it and is not, so a return
+    type naming a nested type has to be qualified
+  * `static` and `virtual` are declaration-only specifiers and must be dropped
+  * a default argument may appear only in the in-class declaration
+  * a constructor's member-init list travels with the definition, not the
+    declaration
+
+Usage:  outline.py --write src/core/config.cppm ...
+        outline.py --write --all
+"""
+from __future__ import annotations
+import argparse, glob, os, re, sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from split import (scan_items, scrub, mask_operator, head_norm, Item,
+                   strip_defaults, has_deduced_return, has_auto_parameter,
+                   ensure_cstdio, CONSTEXPR, TYPE_HEAD, NS_HEAD)
+
+CLASS_HEAD = re.compile(
+    r'^\s*(?:export\s+)?(?P<kw>struct|class)\s+(?P<name>\w+)'
+    r'(?P<rest>[^;{]*)$')
+
+# Members that must keep their body in the class because moving it makes
+# gcc@16.1.0 crash.  Each entry is (path suffix, class, member) and needs a
+# reason — an unexplained exclusion is indistinguishable from superstition.
+ICE_SKIP = {
+    # gcc 16.1.0 segfaults in cc1plus while compiling doctor.cpp once
+    # `Counts::issues()` is defined out-of-line.  The crash is reported against
+    # `DoctorState st;` at doctor.cpp:55 -- a different type, in a different
+    # function -- so the message names the wrong entity entirely.  It is a
+    # compiler bug, not a code error, and it leaves a truncated .gcm behind that
+    # makes unrelated targets fail next build, so this 2-line accessor stays
+    # inline.
+    ('core/xself/doctor.cppm', 'Counts', 'issues'),
+
+    # `static Config& instance_() { static Config inst; return inst; }` -- the
+    # singleton accessor.  Its function-local static is where the module-attached
+    # `Config` (std containers over module types inside) is first completed.
+    # Move that body to the implementation unit and the first-instantiation point
+    # moves with it, after which gcc 16.1.0 segfaults compiling an UNRELATED
+    # translation unit -- doctor.cpp, at `DoctorState st;`, a different type in a
+    # different module.  Found by bisecting config.cppm's 85 movable members;
+    # #34 is the boundary and the other 84 are fine.
+    ('core/config.cppm', 'Config', 'instance_'),
+}
+
+
+def ice_skipped(path: str, cls: str, member: str) -> bool:
+    return any(path.replace(os.sep, '/').endswith(p) and cls == c and member == m
+               for p, c, m in ICE_SKIP)
+
+
+def directive_condition(line: str):
+    """Normalise an #if-family directive to a boolean expression string, or
+    None if the line does not open a conditional."""
+    m = re.match(r'\s*#\s*(ifdef|ifndef|if|elif|else|endif)\b(.*)', line, re.S)
+    if not m:
+        return None
+    kw, rest = m.group(1), m.group(2).strip().rstrip('\\').strip()
+    if kw == 'ifdef':
+        return ('open', f'defined({rest})')
+    if kw == 'ifndef':
+        return ('open', f'!defined({rest})')
+    if kw == 'if':
+        return ('open', f'({rest})')
+    if kw == 'elif':
+        return ('elif', f'({rest})')
+    if kw == 'else':
+        return ('else', None)
+    return ('close', None)
+
+
+class GuardStack:
+    """Tracks the #if nesting so an outlined definition can be re-wrapped in
+    the same condition.  A class inside `#if defined(_WIN32)` whose members are
+    appended to the .cpp unguarded would compile its Windows bodies on Linux —
+    which is exactly what happened before this existed."""
+
+    def __init__(self):
+        self.stack = []          # list of [current_condition, seen_conditions]
+
+    def feed(self, line: str):
+        d = directive_condition(line)
+        if not d:
+            return
+        kind, cond = d
+        if kind == 'open':
+            self.stack.append([cond, [cond]])
+        elif kind == 'elif' and self.stack:
+            prev = self.stack[-1][1]
+            self.stack[-1][0] = ' && '.join(
+                [f'!({p})' for p in prev] + [cond])
+            self.stack[-1][1].append(cond)
+        elif kind == 'else' and self.stack:
+            prev = self.stack[-1][1]
+            self.stack[-1][0] = ' && '.join(f'!({p})' for p in prev)
+        elif kind == 'close' and self.stack:
+            self.stack.pop()
+
+    def current(self):
+        conds = [s[0] for s in self.stack if s[0]]
+        return ' && '.join(conds) if conds else None
+
+
+def nested_type_names(body: str) -> set[str]:
+    """Types declared inside this class body — a return type naming one of
+    them has to be qualified in an out-of-line definition."""
+    sc = scrub(body)
+    names = set(re.findall(r'\b(?:struct|class|enum(?:\s+class)?|union)\s+(\w+)',
+                           sc))
+    names |= set(re.findall(r'\busing\s+(\w+)\s*=', sc))
+    return names
+
+
+def split_member_init(head: str):
+    """Return (declarator_part, member_init_part).  The member-init list starts
+    at a ':' that is not '::' and sits after the closing ')' of the params."""
+    s = mask_operator(scrub(head))
+    o = s.find('(')
+    if o < 0:
+        return head, ''
+    depth, i = 0, o
+    while i < len(s):
+        if s[i] == '(':
+            depth += 1
+        elif s[i] == ')':
+            depth -= 1
+            if depth == 0:
+                break
+        i += 1
+    j = i
+    while j < len(s):
+        if s[j] == ':' and s[j:j+2] != '::' and (j == 0 or s[j-1] != ':'):
+            return head[:j], head[j:]
+        j += 1
+    return head, ''
+
+
+def strip_virt_specifiers(head: str) -> str:
+    """`override` and `final` are declaration-only: a virt-specifier outside a
+    class definition is an error.  They sit after the parameter list, so
+    strip_defaults never sees them."""
+    s = mask_operator(scrub(head))
+    o = s.find('(')
+    if o < 0:
+        return head
+    depth, i = 0, o
+    while i < len(s):
+        if s[i] == '(':
+            depth += 1
+        elif s[i] == ')':
+            depth -= 1
+            if depth == 0:
+                break
+        i += 1
+    return head[:i] + re.sub(r'\s*\b(?:override|final)\b', '', head[i:])
+
+
+def qualify(head: str, cls: str, nested: set[str], fn: str) -> str:
+    """`T name(args)` -> `C::T C::name(args)` (return type qualified only when
+    it names a nested type)."""
+    s = mask_operator(scrub(head))
+    # Locate the declarator-id: the identifier right before the parameter list.
+    # Search the MASKED text — `operator=` ends in '=' and would not match as an
+    # identifier — but slice the original, which mask_operator keeps the same
+    # length as.
+    o = s.find('(')
+    m = None
+    for m in re.finditer(r'[\w~]+\s*$', s[:o]):
+        pass
+    if not m:
+        return head
+    ret = head[:m.start()]
+    name = head[m.start():o]
+    # drop declaration-only specifiers
+    ret = re.sub(r'(^|\s)(?:static|virtual|explicit)\s+', r'\1', ret)
+    # `export` never appears on a member, but be safe
+    ret = re.sub(r'(^|\s)export\s+', r'\1', ret)
+    # qualify a nested return type
+    ret_stripped = ret.strip()
+    for t in nested:
+        ret_stripped = re.sub(r'(?<![\w:])' + re.escape(t) + r'(?![\w:])',
+                              f'{cls}::{t}', ret_stripped)
+    lead_ws = ret[:len(ret) - len(ret.lstrip())]
+    sep = ' ' if ret_stripped else ''
+    return f'{lead_ws}{ret_stripped}{sep}{cls}::{name.strip()}' + head[o:]
+
+
+def dedent(text: str, n: int) -> str:
+    """Shift every line but the first left by up to n spaces.  A member body
+    carries the class's indentation; left alone, 3,845 lines of out-of-line
+    definitions come out indented one level too deep with their closing brace
+    hanging in mid-air."""
+    if n <= 0:
+        return text
+    head, sep, rest = text.partition('\n')
+    if not sep:
+        return text
+    out = []
+    for line in rest.split('\n'):
+        k = 0
+        while k < n and k < len(line) and line[k] == ' ':
+            k += 1
+        out.append(line[k:])
+    return head + '\n' + '\n'.join(out)
+
+
+def indent_of(lead: str, head: str) -> int:
+    """How far the member declaration is indented inside the class."""
+    m = re.search(r'[ \t]*$', lead.split('\n')[-1])
+    base = len(m.group(0).expandtabs(4)) if m else 0
+    if base:
+        return base
+    m = re.match(r'[ \t]*', head)
+    return len(m.group(0).expandtabs(4))
+
+
+def member_name(decl: str) -> str:
+    """The declarator-id of a member function head."""
+    m = mask_operator(scrub(decl))
+    o = m.find('(')
+    hits = list(re.finditer(r'[\w~]+\s*$', m[:o] if o >= 0 else m))
+    return decl[hits[-1].start():o].strip() if hits else ''
+
+
+def outline_class(cls_item: Item, ns: str, outer: str, out_impl: list,
+                  stats: dict, guards: 'GuardStack', path: str) -> str:
+    """Rewrite one class body; append (namespace, definition) pairs to
+    out_impl.  Returns the rewritten class item text."""
+    m = CLASS_HEAD.match(cls_item.head.rstrip())
+    if not m:
+        return cls_item.raw
+    cname = m.group('name')
+    if 'template' in cls_item.head:
+        # a template class's members cannot be defined in another unit without
+        # explicit instantiation
+        return cls_item.raw
+    body = cls_item.body[1:-1]
+    nested = nested_type_names(body)
+    # The definitions are emitted INSIDE the enclosing namespace, so the
+    # declarator-id only needs the class path.  Qualifying it with the
+    # namespace instead would leave the RETURN TYPE unqualified at global
+    # scope, where the class's own name does not resolve.
+    qual = f'{outer}::{cname}' if outer else cname
+    pieces = []
+    for it in scan_items(body):
+        keep = True
+        if it.kind == 'preproc':
+            guards.feed(it.head)
+        if it.kind == 'def' and it.body and CLASS_HEAD.match(it.head.rstrip()):
+            pieces.append(outline_class(it, ns, qual, out_impl, stats,
+                                        guards, path))
+            continue
+        if it.kind == 'def' and it.body and not TYPE_HEAD.match(it.head) \
+                and not NS_HEAD.match(it.head):
+            h = head_norm(it.head)
+            decl, init = split_member_init(it.head)
+            movable = (
+                '(' in scrub(mask_operator(decl))
+                and not CONSTEXPR.search(h)
+                and 'template' not in h
+                and not re.search(r'=\s*(?:default|delete)\s*;?\s*$', h)
+                and not has_deduced_return(decl)
+                and not has_auto_parameter(decl)
+                and 'friend' not in h
+                and '::' not in scrub(mask_operator(decl)).split('(')[0].split()[-1]
+                and not ice_skipped(path, cname, member_name(decl))
+                and (LIMIT[0] is None or stats['members'] < LIMIT[0])
+            )
+            if movable:
+                # in-class: declaration only, default arguments kept
+                pieces.append(it.lead + decl.rstrip() + ';')
+                ind = indent_of(it.lead, it.head)
+                out_impl.append((ns, guards.current(),
+                    qualify(strip_virt_specifiers(strip_defaults(decl)),
+                            qual, nested, cname).strip() + ' '
+                    + dedent(init + it.body + it.tail, ind).lstrip(' ')))
+                stats['members'] += 1
+                stats['lines'] += it.body.count('\n')
+                keep = False
+        if keep:
+            pieces.append(it.raw)
+    return cls_item.lead + cls_item.head + '{' + ''.join(pieces) + '}' + cls_item.tail
+
+
+def walk(items: list[Item], ns: str, out_impl: list, stats: dict,
+         guards: 'GuardStack', path: str) -> str:
+    parts = []
+    for it in items:
+        if it.kind == 'preproc':
+            guards.feed(it.head)
+        if it.kind == 'def' and it.body and NS_HEAD.match(it.head):
+            nm = re.sub(r'^\s*(?:export\s+)?namespace\s*', '',
+                        it.head).strip().rstrip('{').strip()
+            sub = f'{ns}::{nm}' if ns and nm else (nm or ns)
+            inner = walk(scan_items(it.body[1:-1]), sub, out_impl, stats,
+                         guards, path)
+            parts.append(it.lead + it.head + '{' + inner + '}' + it.tail)
+        elif it.kind == 'def' and it.body and CLASS_HEAD.match(it.head.rstrip()):
+            parts.append(outline_class(it, ns, '', out_impl, stats, guards, path))
+        else:
+            parts.append(it.raw)
+    return ''.join(parts)
+
+
+def group_by_namespace(out_impl: list) -> str:
+    """Emit the definitions inside their own namespace block, in the order the
+    classes appeared, so an unqualified return type still resolves — and inside
+    the #if that guarded the class, so platform-only bodies stay
+    platform-only."""
+    chunks, key, buf = [], None, []
+    for ns, guard, text in out_impl:
+        if (ns, guard) != key:
+            if buf:
+                chunks.append((key, buf))
+            key, buf = (ns, guard), []
+        buf.append(text)
+    if buf:
+        chunks.append((key, buf))
+    parts = []
+    for (ns, guard), texts in chunks:
+        body = '\n\n'.join(x.strip('\n') for x in texts)
+        if ns:
+            body = f'namespace {ns} {{\n\n{body}\n\n}} // namespace {ns}'
+        if guard:
+            body = f'#if {guard}\n\n{body}\n\n#endif'
+        parts.append(body)
+    return '\n\n'.join(parts)
+
+
+BANNER = ('// \u2500\u2500 out-of-line class members '
+          '\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500'
+          '\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500'
+          '\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500'
+          '\u2500\u2500\u2500\u2500')
+
+LIMIT = [None]      # bisection aid: outline at most this many members per file
+
+
+def process(path: str, write: bool):
+    cpp = os.path.splitext(path)[0] + '.cpp'
+    src = open(path).read()
+    m = re.search(r'^export module (?P<mod>[\w.]+)(?P<part>:\w+)?;', src, re.M)
+    if not m:
+        return 0, 0, f'{path}: no `export module`'
+    head_end = m.end()
+    im = re.match(
+        r'\A((?:\s*(?:(?:export\s+)?import\s+[\w.:]+\s*;|//[^\n]*|/\*.*?\*/))*\s*)',
+        src[head_end:], re.S)
+    pre_len = head_end + (im.end(1) if im else 0)
+    preamble, body = src[:pre_len], src[pre_len:]
+
+    out_impl: list[str] = []
+    stats = {'members': 0, 'lines': 0}
+    new_body = walk(scan_items(body), '', out_impl, stats, GuardStack(), path)
+    if not stats['members']:
+        return 0, 0, f'{path}: no outlinable members'
+    if write:
+        open(path, 'w').write(preamble + new_body)
+        # Re-running must replace the generated section, not stack another copy
+        # on top of it.  Appending blind produced three definitions of
+        # `TaskManager::TaskManager` in task.cpp across three regenerations --
+        # and only in the files this tool creates itself, because those are the
+        # ones split.py does not rewrite from scratch.
+        if os.path.exists(cpp):
+            prev = open(cpp).read()
+            cut = prev.find(BANNER)
+            if cut >= 0:
+                open(cpp, 'w').write(prev[:cut].rstrip() + '\n')
+        if not os.path.exists(cpp):
+            # This module had nothing at namespace scope to move, so phase 1
+            # produced no implementation unit.  Build its preamble the same way
+            # split.py does: the global module fragment verbatim, `module M;`
+            # for the primary (a partition's implementation belongs to the
+            # primary module), and the interface's non-partition imports.
+            gmf = src[:src.index('export module')]
+            imports = [re.sub(r'^export\s+', '', x) for x in
+                       re.findall(r'^(?:export\s+)?import\s+[\w.:]+\s*;',
+                                  preamble, re.M)
+                       if not re.match(r'^(?:export\s+)?import\s+:', x)]
+            head = (gmf if gmf.strip() else '') + f'module {m.group("mod")};\n'
+            if imports:
+                head += '\n' + '\n'.join(imports) + '\n'
+            open(cpp, 'w').write(head)
+        with open(cpp, 'a') as fh:
+            fh.write('\n\n' + BANNER + '\n\n')
+            fh.write(group_by_namespace(out_impl) + '\n')
+        # An outlined body can be the first thing in this unit to name `stdout`.
+        # Read before opening for write: `open(w).write(open(r).read())` truncates
+        # the file before the read runs, and every unit that took this path came
+        # out empty -- which surfaces as undefined symbols at link time, not as a
+        # compile error in the file that was emptied.
+        text = open(cpp).read()
+        open(cpp, 'w').write(ensure_cstdio(text))
+    return stats['members'], stats['lines'], None
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('files', nargs='*')
+    ap.add_argument('--all', action='store_true')
+    ap.add_argument('--write', action='store_true')
+    ap.add_argument('--limit', type=int, default=None,
+                    help='outline at most N members per file (bisection aid)')
+    a = ap.parse_args()
+    LIMIT[0] = a.limit
+    files = sorted(glob.glob('src/**/*.cppm', recursive=True)) if a.all else a.files
+    tm = tl = tf = 0
+    for f in files:
+        n, ln, err = process(f, a.write)
+        if err:
+            print(f'SKIP {err}')
+            continue
+        tf += 1; tm += n; tl += ln
+        print(f'{f}: {n} members, {ln} body lines outlined')
+    print(f'\n{tf} files, {tm} members, {tl} body lines outlined')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/.agents/tools/module-split/regen.sh b/.agents/tools/module-split/regen.sh
new file mode 100755
index 00000000..3fef7bee
--- /dev/null
+++ b/.agents/tools/module-split/regen.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Regenerate the whole split from the pre-split source, deterministically.
+#
+#   regen.sh [base-ref]        (default: the commit before the split landed)
+#
+# `git clean` is NOT enough on its own: once the generated .cpp files are
+# committed they are tracked, so clean leaves them and outline.py -- which
+# appends -- would stack a second copy of every out-of-line definition on top of
+# the first.  So the generated files are removed by comparing the tree against
+# the base ref.
+set -u
+BASE="${1:-b1563fe}"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$HERE/../../.." && pwd)"
+cd "$ROOT" || exit 1
+
+git checkout "$BASE" -- src/ || exit 1
+git clean -fq src/
+python3 - "$BASE" <<'PY'
+import subprocess, sys, os, glob
+base = sys.argv[1]
+keep = set(subprocess.run(['git', 'ls-tree', '-r', '--name-only', base, 'src/'],
+                          capture_output=True, text=True).stdout.split())
+n = 0
+for f in glob.glob('src/**/*', recursive=True):
+    if os.path.isfile(f) and f not in keep:
+        os.remove(f); n += 1
+print(f'removed {n} generated file(s)')
+PY
+python3 "$HERE/split.py" --all --write | tail -2
+python3 "$HERE/outline.py" --all --write | tail -2
+# Phase 3 runs last: it needs every interface in its final form to know which
+# imports the interfaces still name.
+python3 "$HERE/trim-imports.py" --write | tail -1
+python3 - <<'PY'
+import glob
+c = sum(open(f).read().count('\n') for f in glob.glob('src/**/*.cppm', recursive=True))
+p = sum(open(f).read().count('\n') for f in glob.glob('src/**/*.cpp', recursive=True))
+print(f'interface {c} lines, implementation {p} lines')
+PY
diff --git a/.agents/tools/module-split/split.py b/.agents/tools/module-split/split.py
new file mode 100755
index 00000000..d1d6c6a4
--- /dev/null
+++ b/.agents/tools/module-split/split.py
@@ -0,0 +1,701 @@
+#!/usr/bin/env python3
+"""Split a C++23 module interface unit that carries its own implementation
+into a standard-conforming (.cppm interface, .cpp implementation) pair.
+
+Phase 1 scope: namespace-scope entities.  Class/struct bodies are left whole
+in the interface (phase 2 outlines their members).
+
+Usage:
+    split.py --dry-run  src/core/log.cppm ...
+    split.py --write    src/core/log.cppm ...
+    split.py --write --all
+"""
+from __future__ import annotations
+import argparse, glob, os, re, sys
+
+# ─────────────────────────── lexical scrubbing ───────────────────────────
+
+def scrub(s: str) -> str:
+    """Return s with comments and string/char literals blanked to spaces,
+    preserving length and newlines so offsets stay valid."""
+    out = list(s)
+    i, n = 0, len(s)
+    while i < n:
+        c = s[i]
+        if c == '/' and i + 1 < n and s[i+1] == '/':
+            j = s.find('\n', i)
+            j = n if j < 0 else j
+            for k in range(i, j): out[k] = ' '
+            i = j
+        elif c == '/' and i + 1 < n and s[i+1] == '*':
+            j = s.find('*/', i + 2)
+            j = n if j < 0 else j + 2
+            for k in range(i, j):
+                if s[k] != '\n': out[k] = ' '
+            i = j
+        elif c == '"' and i > 0 and s[i-1] == 'R':
+            m = re.match(r'"([^(\s\\]*)\(', s[i:])
+            if m:
+                delim = m.group(1)
+                end = s.find(')' + delim + '"', i)
+                j = n if end < 0 else end + len(delim) + 2
+                for k in range(i, j):
+                    if s[k] != '\n': out[k] = ' '
+                i = j
+                continue
+            i = _blank_quoted(s, out, i, '"', n)
+        elif c in '"\'':
+            i = _blank_quoted(s, out, i, c, n)
+        else:
+            i += 1
+    return ''.join(out)
+
+
+def _blank_quoted(s, out, i, q, n):
+    j = i + 1
+    while j < n:
+        if s[j] == '\\':
+            j += 2; continue
+        if s[j] == q:
+            j += 1; break
+        if s[j] == '\n':
+            break
+        j += 1
+    for k in range(i, j):
+        if s[k] != '\n': out[k] = ' '
+    return j
+
+
+# ─────────────────────────── item scanning ───────────────────────────
+
+class Item:
+    __slots__ = ('lead', 'head', 'body', 'tail', 'kind')
+
+    def __init__(self, lead, head, body, tail, kind):
+        self.lead = lead      # comments / blank lines preceding the item
+        self.head = head      # declarator text before the body brace
+        self.body = body      # '{...}' including braces, or None
+        self.tail = tail      # text between the body and its ';' (plus ';')
+        self.kind = kind      # 'preproc' | 'decl' | 'def' | 'blank'
+
+    @property
+    def raw(self):
+        return self.lead + self.head + (self.body or '') + self.tail
+
+
+def scan_items(text: str) -> list[Item]:
+    """Split one brace level into items.  Comments and blank lines immediately
+    preceding an item become its `lead`."""
+    sc = scrub(text)
+    items: list[Item] = []
+    i, n = 0, len(text)
+    lead_start = 0
+    while i < n:
+        # skip whitespace/comments -> they accumulate into `lead`
+        if sc[i].isspace():
+            i += 1
+            continue
+        # preprocessor directive: whole logical line, verbatim
+        if sc[i] == '#' and (i == 0 or text.rfind('\n', 0, i) == i - 1 - (i - 1 - text.rfind('\n', 0, i))
+                             or text[:i].rsplit('\n', 1)[-1].strip() == ''):
+            j = i
+            while j < n:
+                nl = sc.find('\n', j)
+                if nl < 0:
+                    j = n; break
+                if text[nl-1] != '\\':
+                    j = nl + 1; break
+                j = nl + 1
+            items.append(Item(text[lead_start:i], text[i:j], None, '', 'preproc'))
+            i = lead_start = j
+            continue
+        # an access specifier is its own item — it ends with ':' and would
+        # otherwise swallow everything up to the next ';'
+        am = re.match(r'(public|private|protected)\s*:', sc[i:])
+        if am:
+            j = i + am.end()
+            items.append(Item(text[lead_start:i], text[i:j], None, '', 'access'))
+            i = lead_start = j
+            continue
+        # an item: accumulate until ';' or '{' at paren depth 0
+        start = i
+        pdepth = 0
+        body = None
+        seen_params = False     # a ')' has closed at depth 0
+        in_init = False         # inside a constructor's member-init list
+        while i < n:
+            c = sc[i]
+            if c in '([':
+                pdepth += 1
+            elif c in ')]':
+                pdepth -= 1
+                if pdepth == 0 and c == ')':
+                    seen_params = True
+            elif (pdepth == 0 and c == ':' and seen_params
+                  and sc[i:i+2] != '::' and (i == 0 or sc[i-1] != ':')):
+                in_init = True
+            elif pdepth == 0 and c == ';':
+                i += 1
+                break
+            elif pdepth == 0 and c == '{':
+                # In a member-init list an initialiser's brace follows an
+                # IDENTIFIER (`: registry_ { registry }`) while the function
+                # body's brace follows ')' or '}'.  Without this the first
+                # initialiser gets mistaken for the body and the declaration
+                # comes out as `Ctor(args); {}`.
+                if in_init:
+                    k = i - 1
+                    while k >= 0 and sc[k].isspace():
+                        k -= 1
+                    if k >= 0 and (sc[k].isalnum() or sc[k] == '_'):
+                        d = 0
+                        while i < n:
+                            if sc[i] == '{':
+                                d += 1
+                            elif sc[i] == '}':
+                                d -= 1
+                                if d == 0:
+                                    i += 1
+                                    break
+                            i += 1
+                        continue
+                bstart = i
+                depth = 0
+                while i < n:
+                    if sc[i] == '{': depth += 1
+                    elif sc[i] == '}':
+                        depth -= 1
+                        if depth == 0:
+                            i += 1; break
+                    i += 1
+                body = text[bstart:i]
+                break
+            i += 1
+        if body is None:
+            head, tail = text[start:i], ''
+            kind = 'decl'
+        else:
+            head = text[start:bstart]
+            # A ';' may close the item — directly (`enum E { } ;`) or after a
+            # declarator (`struct X { } inst;`).  Consume through it, but never
+            # the whitespace beyond: that belongs to the NEXT item's lead,
+            # which is what carries the file's line structure.
+            j, tail = i, ''
+            while j < n and sc[j].isspace():
+                j += 1
+            if j < n and sc[j] == ';':
+                tail, i = text[i:j+1], j + 1
+            elif j < n and re.match(r'[\w*&]', sc[j]):
+                k = sc.find(';', j)
+                if k >= 0 and '\n' not in sc[i:k]:
+                    tail, i = text[i:k+1], k + 1
+            kind = 'def'
+        items.append(Item(text[lead_start:start], head, body, tail, kind))
+        lead_start = i
+    if lead_start < n:
+        items.append(Item(text[lead_start:], '', None, '', 'blank'))
+    return items
+
+
+# ─────────────────────────── classification ───────────────────────────
+
+STAY_HEAD = re.compile(
+    r'\b(?:template|concept|static_assert|using|typedef|namespace|extern|friend|'
+    r'requires|__attribute__)\b')
+TYPE_HEAD = re.compile(r'^\s*(?:export\s+)?(?:struct|class|union|enum)\b')
+NS_HEAD = re.compile(r'^\s*(?:export\s+)?namespace\b')
+CONSTEXPR = re.compile(r'\b(?:constexpr|consteval|constinit)\b')
+
+
+def head_norm(h: str) -> str:
+    return ' '.join(scrub(h).split())
+
+
+# `operator=`, `operator==`, `operator<=>`, `operator[]`, `operator()`, a
+# conversion operator...  The '=' and the parentheses in these are part of the
+# NAME, so they must not be read as an initialiser or a parameter list.
+OPERATOR_NAME = re.compile(
+    r'\boperator\s*(?:new\b|delete\b|""\s*\w+|\(\s*\)|\[\s*\]|'
+    r'[+\-*/%^&|~!<>=,]+)')
+
+
+def mask_operator(s: str) -> str:
+    return OPERATOR_NAME.sub(lambda m: 'operator_' + '_' * (len(m.group(0)) - 9), s)
+
+
+def is_function_head(h: str) -> bool:
+    """A function declarator: has a parameter list that is not part of an
+    initialiser (`=` before the '(' means it is a variable)."""
+    s = mask_operator(scrub(h))
+    p = s.find('(')
+    if p < 0:
+        return False
+    before = s[:p]
+    if '=' in before:
+        return False
+    # `foo bar[3]` style, or a cast expression -> not a function head
+    return re.search(r'[\w>~\]]\s*$', before) is not None
+
+
+def has_deduced_return(h: str) -> bool:
+    """`auto f(...) { ... }` with no trailing return type: the return type is
+    deduced FROM THE BODY, so a caller in another unit cannot see it.  With a
+    trailing `-> T` the declaration is complete and the body can move."""
+    s = mask_operator(scrub(h))
+    if '->' in s:
+        return False
+    return re.match(r'^\s*(?:export\s+)?(?:static\s+)?(?:\[\[[^\]]*\]\]\s*)*'
+                    r'(?:constexpr\s+|inline\s+)*'
+                    r'(?:auto|decltype\s*\(\s*auto\s*\))\b', s) is not None
+
+
+def has_auto_parameter(h: str) -> bool:
+    """`void f(auto x)` is an abbreviated function template."""
+    s = mask_operator(scrub(h))
+    o = s.find('(')
+    if o < 0:
+        return False
+    depth, i = 0, o
+    while i < len(s):
+        if s[i] == '(': depth += 1
+        elif s[i] == ')':
+            depth -= 1
+            if depth == 0: break
+        i += 1
+    return re.search(r'\bauto\b', s[o:i]) is not None
+
+
+def is_qualified_definition(h: str) -> bool:
+    """`T C::f(...)` or `T ns::f(...)` — a definition written with a qualified
+    name.  An out-of-line member cannot be *declared* at namespace scope, so
+    phase 1 leaves every qualified definition where it is."""
+    s = mask_operator(scrub(h))
+    p = s.find('(')
+    decl = s[:p] if p >= 0 else s
+    return '::' in decl.split()[-1] if decl.split() else False
+
+
+def classify(it: Item) -> str:
+    """Return one of:
+      'stay'       leave it whole in the interface
+      'namespace'  recurse into it, re-emitting the wrapper in both units
+      'both'       emit it verbatim to both units (a preprocessor conditional)
+      'move-impl'  move it whole to the implementation unit
+      'split-fn'   declaration in the interface, definition in the impl unit
+      'split-var'  `extern` in the interface, definition in the impl unit
+    """
+    if it.kind in ('blank', 'access'):
+        return 'stay'
+    if it.kind == 'preproc':
+        return 'both'                      # conditionals must bracket both units
+    h = head_norm(it.head)
+    if not h:
+        return 'stay'
+    # a module/import declaration that did not land in the preamble block
+    if re.match(r'^(?:export\s+)?(?:import|module)\b', h):
+        return 'stay'
+    if NS_HEAD.match(it.head):
+        if not it.body:
+            return 'stay'
+        # An ANONYMOUS namespace has internal linkage: its members cannot be
+        # declared in one unit and defined in another, and the implementation
+        # unit cannot see the interface's copy.  It moves whole.
+        return 'namespace' if head_norm(it.head).rstrip() != 'namespace' \
+            else 'move-impl'
+    if TYPE_HEAD.match(it.head):
+        return 'stay'                      # phase 1: types stay whole
+    if CONSTEXPR.search(h) or STAY_HEAD.search(h):
+        return 'stay'
+    if re.search(r'\binline\b', h):
+        return 'stay'
+    # Function or variable is decided FIRST: the rules below read the text
+    # before the parameter list, and in a variable that text is an initialiser
+    # expression, where a `const` or a `::` means nothing about the declaration.
+    if is_function_head(it.head):
+        if it.body is None:
+            return 'stay'                  # already only a declaration
+        if re.search(r'=\s*(?:default|delete)\s*;?\s*$', h):
+            return 'stay'
+        if is_qualified_definition(it.head):
+            return 'stay'                  # phase 1: no out-of-line members
+        if has_deduced_return(it.head) or has_auto_parameter(it.head):
+            return 'stay'
+        return 'split-fn'
+    # A variable definition — with an initialiser (`T x {..};`, `T x = ..;`)
+    # or default-constructed (`T x;`).  Both are definitions and both move.
+    # It needs a type AND a name: a lone identifier is a macro invocation
+    # (`NLOHMANN_JSON_NAMESPACE_END;`), not a declaration.
+    bare = h.rstrip(';').rstrip()
+    lhs = mask_operator(scrub(bare)).split('=')[0]
+    # `const` at namespace scope has internal linkage, so its definition cannot
+    # move to another unit without changing that linkage.
+    if re.search(r'\bconst\b', lhs):
+        return 'stay'
+    if re.match(r'^(?:export\s+)?(?:static\s+)?[\w:<>,\s*&\[\]]+\w\s*(?:$|=|\[)',
+                bare) and len(re.sub(r'\s*[*&]\s*', ' ', lhs).split()) >= 2:
+        return 'split-var'
+    return 'stay'
+
+
+# ─────────────────────────── head rewriting ───────────────────────────
+
+def strip_export(h: str) -> str:
+    return re.sub(r'(^|\s)export\s+', r'\1', h, count=1)
+
+
+def strip_static(h: str) -> str:
+    """Namespace-scope `static` becomes module linkage so the declaration and
+    the definition can live in different units of the same module."""
+    return re.sub(r'(^|\s)static\s+', r'\1', h, count=1)
+
+
+def split_params(params: str) -> list[str]:
+    out, depth, cur = [], 0, ''
+    for c in params:
+        if c in '([{<':
+            depth += 1
+        elif c in ')]}>':
+            depth -= 1
+        if c == ',' and depth == 0:
+            out.append(cur); cur = ''
+        else:
+            cur += c
+    if cur.strip():
+        out.append(cur)
+    return out
+
+
+def strip_defaults(h: str) -> str:
+    """Remove default arguments — they must appear only in the declaration."""
+    sc = scrub(h)
+    o = sc.find('(')
+    if o < 0:
+        return h
+    depth, i = 0, o
+    while i < len(sc):
+        if sc[i] == '(': depth += 1
+        elif sc[i] == ')':
+            depth -= 1
+            if depth == 0: break
+        i += 1
+    params_raw = h[o+1:i]
+    if '=' not in scrub(params_raw):
+        return h
+    parts = []
+    for p in split_params(params_raw):
+        eq = scrub(p).find('=')
+        parts.append(p[:eq].rstrip() if eq >= 0 else p)
+    return h[:o+1] + ', '.join(x.strip() for x in parts) + h[i:]
+
+
+def decl_from_def(h: str) -> str:
+    """The interface declaration for a definition head."""
+    return h.rstrip().rstrip() + ';'
+
+
+# ─────────────────────────── emission ───────────────────────────
+
+class Cand:
+    """A module-private entity whose declaration may or may not be needed in
+    the interface."""
+    __slots__ = ('ns', 'decl', 'name', 'lead',
+                 'impl_with_defaults', 'impl_no_defaults')
+
+    def __init__(self, ns, decl, name, lead, impl_with_defaults,
+                 impl_no_defaults):
+        self.ns = ns
+        self.decl = decl
+        self.name = name
+        # The doc comment. It travels with whichever side keeps the
+        # declaration: dropping it with the declaration would delete the
+        # explanation of a helper whose body is still there.
+        self.lead = lead
+        self.impl_with_defaults = impl_with_defaults
+        self.impl_no_defaults = impl_no_defaults
+
+
+class Split:
+    def __init__(self):
+        self.iface: list[str] = []
+        self.impl: list[str] = []
+        self.cands: list[Cand] = []
+        self.moved = 0
+        self.moved_lines = 0
+
+
+# A non-exported entity is wrapped in these while the two texts are assembled,
+# so one later pass can ask whether anything LEFT in the interface still names
+# it -- and fix up BOTH sides together.  These bytes cannot occur in C++ source.
+#
+# Both sides are needed because the decision changes the definition too: if the
+# interface keeps the declaration, the declaration carries the default arguments
+# and the definition must not repeat them; if the declaration is dropped, the
+# definition is the only declaration and must carry them itself.
+IFACE_MARK, IMPL_MARK, MARK_END = '\x01', '\x02', '\x03'
+
+
+def is_exported(head: str) -> bool:
+    return re.match(r'^\s*export\b', head) is not None
+
+
+def process_level(items: list[Item], out: Split, indent: str,
+                  ns: str = '', exported: bool = False):
+    for it in items:
+        cls = classify(it)
+        if cls == 'both':
+            out.iface.append(it.lead + it.head)
+            out.impl.append(it.lead + it.head)
+        elif cls == 'namespace':
+            inner = it.body[1:-1]
+            sub = Split()
+            # one shared candidate list per file, so the ids that pair an
+            # interface marker with its implementation marker stay unique across
+            # nesting levels
+            sub.cands = out.cands
+            nm = re.sub(r'^\s*(?:export\s+)?namespace\s*', '',
+                        it.head).strip().rstrip('{').strip()
+            sub_ns = f'{ns}::{nm}' if ns and nm else (nm or ns)
+            process_level(scan_items(inner), sub, indent, ns=sub_ns,
+                          exported=exported or is_exported(it.head))
+            out.iface.append(it.lead + it.head + '{' + ''.join(sub.iface)
+                             + '}' + it.tail)
+            if any(x.strip() for x in sub.impl):
+                body = '\n\n'.join(x.strip('\n') for x in sub.impl if x.strip())
+                out.impl.append(strip_export(it.head).lstrip() + '{\n\n'
+                                + body + '\n\n}' + it.tail)
+            out.moved += sub.moved
+            out.moved_lines += sub.moved_lines
+        elif cls == 'move-impl':
+            out.impl.append(it.lead.strip('\n') + '\n' + it.head + it.body + it.tail
+                            if it.lead.strip() else it.head + it.body + it.tail)
+            out.moved += 1
+            out.moved_lines += (it.body or '').count('\n')
+        elif cls == 'stay':
+            out.iface.append(it.raw)
+        elif cls == 'split-fn':
+            decl = it.lead + decl_from_def(it.head)
+            plain = strip_static(strip_export(it.head))
+            no_def = strip_defaults(plain).lstrip('\n') + it.body + it.tail
+            if exported or is_exported(it.head):
+                out.iface.append(decl)
+                out.impl.append(no_def)
+            else:
+                cid = str(len(out.cands))
+                out.cands.append(Cand(ns, decl, declared_name(it.head), it.lead,
+                                      plain.lstrip('\n') + it.body + it.tail,
+                                      no_def))
+                out.iface.append(IFACE_MARK + cid + MARK_END)
+                out.impl.append(IMPL_MARK + cid + MARK_END)
+            out.moved += 1
+            out.moved_lines += it.body.count('\n')
+        elif cls == 'split-var':
+            h = strip_static(strip_export(it.head))
+            bare = h.strip().rstrip(';').rstrip() if it.body is None \
+                else h.rstrip()
+            # the declaration carries the type and name, never the initialiser
+            eq = scrub(bare).find('=')
+            decl = (bare[:eq].rstrip() if eq >= 0 else bare).strip()
+            ext = it.lead + 'extern ' + decl + ';'
+            defn = bare + (it.body or '') + it.tail
+            defn = defn.strip() if defn.rstrip().endswith(';') \
+                else defn.strip() + ';'
+            if exported or is_exported(it.head):
+                out.iface.append(ext)
+                out.impl.append(defn)
+            else:
+                cid = str(len(out.cands))
+                out.cands.append(Cand(ns, ext, declared_name(bare), it.lead,
+                                      defn, defn))
+                out.iface.append(IFACE_MARK + cid + MARK_END)
+                out.impl.append(IMPL_MARK + cid + MARK_END)
+            out.moved += 1
+            out.moved_lines += (it.body or '').count('\n')
+        else:
+            out.iface.append(it.raw)
+
+
+IFACE_RE = re.compile(IFACE_MARK + r'(\d+)' + MARK_END)
+IMPL_RE = re.compile(IMPL_MARK + r'(\d+)' + MARK_END)
+
+
+def declared_name(decl: str) -> str:
+    """The name a declaration introduces."""
+    m = mask_operator(scrub(decl))
+    o = m.find('(')
+    region = m[:o] if o >= 0 else m.rstrip().rstrip(';')
+    hits = list(re.finditer(r'[\w~]+', region))
+    return region[hits[-1].start():hits[-1].end()] if hits else ''
+
+
+def resolve_candidates(iface: str, impl: str, cands: list):
+    """A NON-exported declaration belongs in the interface only if something
+    still IN the interface names it -- an exported template, an inline or
+    constexpr body, a class member body, a default argument.  Everything else is
+    a module-private helper: keeping its declaration in the interface would put
+    it in the BMI, so changing its signature would recompile every importer for
+    no reason.
+
+    Both texts are fixed up here because the two are coupled -- see the comment
+    on IFACE_MARK."""
+    if not cands:
+        return IFACE_RE.sub('', iface), IMPL_RE.sub('', impl)
+    # what the interface still says with every candidate declaration removed
+    residue = IFACE_RE.sub('', iface)
+    keep = set()
+    for i, c in enumerate(cands):
+        # `detail_::binding_error_(...)` is a reference to binding_error_.  A
+        # lookbehind that rejected ':' would miss every qualified call, which is
+        # the common form.  Over-counting only keeps a declaration that could
+        # have moved; under-counting breaks the build.
+        if c.name and re.search(r'(?<!\w)' + re.escape(c.name) + r'\b', residue):
+            keep.add(i)
+    iface = IFACE_RE.sub(
+        lambda m: cands[int(m.group(1))].decl if int(m.group(1)) in keep else '',
+        iface)
+    def impl_for(m):
+        c = cands[int(m.group(1))]
+        if int(m.group(1)) in keep:
+            return c.impl_no_defaults      # its comment stayed with the decl
+        lead = c.lead.strip('\n')
+        return (lead + '\n' + c.impl_with_defaults) if lead.strip() \
+            else c.impl_with_defaults
+
+    impl = IMPL_RE.sub(impl_for, impl)
+    return iface, impl
+
+
+PREAMBLE = re.compile(
+    r'\A(?P<gmf>.*?)^export module (?P<mod>[\w.]+)(?P<part>:\w+)?;',
+    re.S | re.M)
+
+# `import x.y;`, `import :part;`, `export import :part;`
+IMPORT_LINE = re.compile(r'^(?:export\s+)?import\s+[\w.:]+\s*;', re.M)
+
+
+# `std::print("...")` / `std::println("...")` -- the overload that takes no
+# stream.  libc++ implements it as `print(stdout, fmt, args...)`, so the FILE*
+# overload has to win overload resolution at the point of instantiation.  Inside
+# a template that stays in the INTERFACE, that point is in the importer, and once
+# enough bodies leave the interface clang 20 stops picking the FILE* overload:
+# `stdout` is deduced AS the format string and the error is a deleted
+# `formatter<basic_format_string<...>>` in a file that did not change
+# (xlings-ci-macos runs 31660163438 / 31660753235; reproduced locally with
+# llvm@20.1.7 on Linux, where main builds clean and the split does not).
+#
+# Naming the stream removes the deduction entirely.  It is the same call --
+# [print.fun] defines the two-argument form AS `print(stdout, ...)` -- so this
+# normalises 23 sites across 6 interfaces and changes no behaviour.  Bodies that
+# move to an implementation unit are left alone: nothing instantiates those from
+# another translation unit.
+STREAMLESS_PRINT_CALL = re.compile(r'\b(std::print(?:ln)?)\s*\(\s*(?=")')
+
+
+def name_the_stream(iface: str) -> str:
+    return STREAMLESS_PRINT_CALL.sub(r'\1(stdout, ', iface)
+
+
+# `stdout` / `stderr` / `FILE` come from <cstdio>.  A body that names one can end
+# up in an implementation unit whose interface had no global module fragment
+# (config.cppm has none, and `Config::print_paths()` moves there), so the unit
+# has to acquire the include itself -- otherwise clang says
+# "missing '#include <stdio.h>'; 'stdout' must be declared before it is used".
+CSTDIO_NAMES = re.compile(r'\b(?:stdout|stderr|stdin|FILE)\b')
+
+
+def ensure_cstdio(impl: str) -> str:
+    """Add <cstdio> to an implementation unit's global module fragment when its
+    text needs it and it does not already have it."""
+    if not CSTDIO_NAMES.search(scrub(impl)):
+        return impl
+    if re.search(r'^\s*#include\s*<cstdio>', impl, re.M) or \
+       re.search(r'^\s*#include\s*<stdio\.h>', impl, re.M):
+        return impl
+    m = re.search(r'^module [\w.]+;', impl, re.M)
+    if not m:
+        return impl
+    if re.match(r'\s*module;', impl):
+        # already has a fragment -- put the include at its end
+        return impl[:m.start()] + '#include <cstdio>\n\n' + impl[m.start():]
+    return 'module;\n#include <cstdio>\n\n' + impl
+
+
+def split_file(path: str, qualify_partition_import=False):
+    src = open(path).read()
+    m = PREAMBLE.search(src)
+    if not m:
+        return None, f'{path}: no `export module` declaration'
+    gmf, mod, part = m.group('gmf'), m.group('mod'), m.group('part') or ''
+    rest = src[m.end():]
+    # the import block that immediately follows the module declaration
+    im = re.match(
+        r'\A((?:\s*(?:(?:export\s+)?import\s+[\w.:]+\s*;|//[^\n]*|/\*.*?\*/))*\s*)',
+        rest, re.S)
+    imports_blk = im.group(1) if im else ''
+    body = rest[len(imports_blk):]
+    # An implementation unit cannot re-export, so `export import` becomes a
+    # plain import there.  Partition imports are dropped: the primary interface
+    # already does `export import :p;`, an implementation unit implicitly
+    # imports that primary, and the ordering edge reaches the partition BMI
+    # through it.  Keeping them would only add mcpp's cosmetic
+    # "module ':p' imported but not provided" warning on every build.
+    imports = [re.sub(r'^export\s+', '', x)
+               for x in IMPORT_LINE.findall(imports_blk)
+               if not re.match(r'^(?:export\s+)?import\s+:', x)]
+
+    out = Split()
+    process_level(scan_items(body), out, '')
+    if out.moved == 0:
+        return None, f'{path}: nothing to move'
+
+    iface = gmf + f'export module {mod}{part};' + imports_blk + ''.join(out.iface)
+    # The implementation of a PARTITION's declarations belongs to an
+    # implementation unit of the PRIMARY module (`module M;`) — `module M:p;`
+    # would be another partition and would still produce a BMI.  A module may
+    # have any number of implementation units.
+    impl = (gmf if gmf.strip() else '') + f'module {mod};\n'
+    if part and qualify_partition_import and f'import {part};' not in imports:
+        imports.insert(0, f'import {part};')
+    if imports:
+        impl += '\n' + '\n'.join(imports) + '\n'
+    # A dropped declaration is not re-emitted as a forward declaration: source
+    # order is preserved, so a definition still precedes its callers exactly as
+    # it did in the combined file -- and a namespace-scope declaration block is
+    # not free.  One mentioning `std::vector<xvm::SubosRef>` made gcc 16.1.0
+    # segfault in doctor.cpp, the known shape where a std container over a
+    # module-attached type is first instantiated from namespace scope.
+    impl += '\n' + '\n\n'.join(x.strip('\n') for x in out.impl if x.strip())
+    iface, impl = resolve_candidates(iface, impl, out.cands)
+    return (name_the_stream(iface), ensure_cstdio(impl.rstrip() + '\n'),
+            out.moved, out.moved_lines, mod + part), None
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('files', nargs='*')
+    ap.add_argument('--all', action='store_true')
+    ap.add_argument('--write', action='store_true')
+    ap.add_argument('--dry-run', action='store_true')
+    ap.add_argument('--partition-import', action='store_true',
+                    help="emit `import :part;` in a partition's implementation "
+                         "unit (needed only when it defines entities the "
+                         "partition does not export)")
+    a = ap.parse_args()
+    files = sorted(glob.glob('src/**/*.cppm', recursive=True)) if a.all else a.files
+    tot_fn = tot_lines = tot_files = 0
+    for f in files:
+        res, err = split_file(f, a.partition_import)
+        if err:
+            print(f'SKIP {err}')
+            continue
+        iface, impl, moved, mlines, mod = res
+        tot_fn += moved; tot_lines += mlines; tot_files += 1
+        print(f'{f}: {moved} entities, {mlines} body lines -> '
+              f'{os.path.splitext(f)[0]}.cpp')
+        if a.write:
+            open(f, 'w').write(iface)
+            open(os.path.splitext(f)[0] + '.cpp', 'w').write(impl)
+    print(f'\n{tot_files} files, {tot_fn} entities, {tot_lines} body lines moved')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/.agents/tools/module-split/trim-imports.py b/.agents/tools/module-split/trim-imports.py
new file mode 100755
index 00000000..19ce865d
--- /dev/null
+++ b/.agents/tools/module-split/trim-imports.py
@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""Phase 3 of the split: move the imports the bodies took with them.
+
+split.py COPIES the interface's import list into the implementation unit. That is
+correct for the implementation -- it needs them -- but it leaves the interface
+importing modules only the moved bodies used. 249 of 562 interface import edges
+(44%) ended up like that, and every one makes the interface's BMI depend on a
+module it does not name, so an edit to that module recompiles this interface for
+nothing. It caps the very benefit the split exists to deliver.
+
+An import is kept when the interface still NAMES something the imported module
+exports. That test needs the export sets, so this runs as a post-pass over the
+finished tree rather than inside split.py, which sees one file at a time.
+
+Never dropped:
+  * `export import X;` -- a deliberate re-export, an aggregator's whole purpose
+  * `import std;` and `import :partition;`
+  * anything whose module cannot be resolved locally (mcpplibs, compat, ...)
+
+Usage:  trim-imports.py [--write]
+"""
+from __future__ import annotations
+import argparse, glob, os, re, sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from split import scrub, scan_items, mask_operator, NS_HEAD
+
+KW = {'const', 'static', 'inline', 'constexpr', 'consteval', 'extern', 'virtual',
+      'explicit', 'friend', 'operator', 'noexcept', 'return', 'template',
+      'typedef', 'mutable', 'volatile', 'namespace', 'export', 'struct', 'class',
+      'union', 'enum', 'using', 'void', 'auto'}
+
+
+def item_names(head: str) -> set[str]:
+    h = mask_operator(scrub(head)).strip().rstrip(';').strip()
+    if not h:
+        return set()
+    t = re.match(r'(?:export\s+)?(?:struct|class|union|enum(?:\s+class)?)\s+(\w+)', h)
+    if t:
+        return {t.group(1)}
+    a = re.match(r'(?:export\s+)?using\s+(\w+)\s*=', h)
+    if a:
+        return {a.group(1)}
+    u = re.match(r'(?:export\s+)?using\s+[\w:]*?::(\w+)\s*$', h)
+    if u:
+        return {u.group(1)}
+    if re.match(r'(?:export\s+)?(?:import|module)\b', h):
+        return set()
+    o = h.find('(')
+    region = h[:o] if o >= 0 else h
+    if o >= 0:
+        m = list(re.finditer(r'([\w~]+)\s*$', region))
+        if m and m[-1].group(1) not in KW:
+            return {m[-1].group(1)}
+    ids = [i for i in re.findall(r'\b([A-Za-z_]\w*)\b', region) if i not in KW]
+    return {ids[-1]} if ids else set()
+
+
+def exported_names(text: str) -> set[str]:
+    """Every name this interface unit exports, at any namespace depth."""
+    names: set[str] = set()
+
+    def walk(body: str, inherited: bool):
+        for it in scan_items(body):
+            if it.kind in ('preproc', 'blank', 'access'):
+                continue
+            exported = inherited or re.match(r'\s*export\b', it.head) is not None
+            if it.body and NS_HEAD.match(it.head):
+                walk(it.body[1:-1], exported)
+                continue
+            if exported:
+                names.update(item_names(it.head))
+                # a class also exports its member names, which callers write
+                if it.body and re.match(r'\s*(?:export\s+)?(?:struct|class|union)\b',
+                                        it.head):
+                    for m in scan_items(it.body[1:-1]):
+                        if m.kind not in ('preproc', 'blank', 'access'):
+                            names.update(item_names(m.head))
+
+    m = re.search(r'^export module [\w.]+(?::\w+)?;', text, re.M)
+    walk(text[m.end():] if m else text, False)
+    return {n for n in names if n}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--write', action='store_true')
+    a = ap.parse_args()
+
+    files = sorted(glob.glob('src/**/*.cppm', recursive=True))
+    srcs = {f: open(f).read() for f in files}
+
+    # module (including partitions) -> exported names
+    exports: dict[str, set[str]] = {}
+    primary_of: dict[str, str] = {}
+    for f, s in srcs.items():
+        m = re.search(r'^export module ([\w.]+)(:\w+)?;', s, re.M)
+        if not m:
+            continue
+        full = m.group(1) + (m.group(2) or '')
+        exports[full] = exported_names(s)
+        primary_of[full] = m.group(1)
+    # A module offers everything it RE-EXPORTS as well as what it declares:
+    # its own partitions, and any `export import X;` of a whole module. Missing
+    # the second kind made every aggregator (`xlings.runtime` re-exports
+    # event/event_stream/capability and declares nothing itself) look like it
+    # exported no names at all, so importers of it were trimmed and
+    # `interface.cppm` lost `Event`, `EventStream` and `CancellationToken`.
+    for full, names in list(exports.items()):
+        p = primary_of[full]
+        if p != full:
+            exports.setdefault(p, set())
+            exports[p] |= names
+
+    reexports: dict[str, set[str]] = {}
+    for f, src in srcs.items():
+        m = re.search(r'^export module ([\w.]+)(:\w+)?;', src, re.M)
+        if not m:
+            continue
+        full = m.group(1) + (m.group(2) or '')
+        reexports[full] = set(re.findall(r'^export import\s+([\w.:]+)\s*;', src, re.M))
+
+    def closure(mod, seen=None):
+        seen = set() if seen is None else seen
+        if mod in seen:
+            return set()
+        seen.add(mod)
+        names = set(exports.get(mod, ()))
+        for r in reexports.get(mod, ()):
+            target = (primary_of.get(mod, mod) + r) if r.startswith(':') else r
+            names |= closure(target, seen)
+        return names
+
+    exports = {m: closure(m) for m in list(exports)}
+
+    total = dropped = 0
+    report = []
+    for f, s in srcs.items():
+        m = re.search(r'^export module [\w.]+(?::\w+)?;', s, re.M)
+        if not m:
+            continue
+        head, body = s[:m.end()], s[m.end():]
+        lines = body.split('\n')
+        # the text the interface actually is, minus its own import lines
+        text = scrub('\n'.join(
+            l for l in lines if not re.match(r'\s*(?:export\s+)?import\s', l)))
+        out, drops = [], []
+        for l in lines:
+            im = re.match(r'\s*import\s+([\w.:]+)\s*;\s*$', l)
+            if not im:
+                out.append(l)
+                continue
+            mod = im.group(1)
+            total += 1
+            names = exports.get(mod)
+            if mod == 'std' or mod.startswith(':') or names is None:
+                out.append(l)                      # std, partition, or foreign
+                continue
+            # keep it if the interface names anything this module exports, or
+            # mentions a segment of the module name (belt and braces)
+            segs = [x for x in mod.split('.') if x != 'xlings']
+            used = any(re.search(r'(?<![\w])' + re.escape(n) + r'(?![\w])', text)
+                       for n in names) or \
+                   any(re.search(r'(?<![\w])' + re.escape(sg) + r'(?![\w])', text, re.I)
+                       for sg in segs)
+            if used:
+                out.append(l)
+            else:
+                drops.append(mod)
+                dropped += 1
+        if drops:
+            report.append((f, drops))
+            if a.write:
+                open(f, 'w').write(head + '\n'.join(out))
+
+    for f, drops in report:
+        print(f'{f}: -{len(drops)}  {", ".join(drops)}')
+    print(f'\n{len(report)} interfaces, {dropped}/{total} plain imports dropped '
+          f'({100*dropped/max(total,1):.0f}%)')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())
diff --git a/mcpp.toml b/mcpp.toml
index de9ea8db..3b0d5c3a 100644
--- a/mcpp.toml
+++ b/mcpp.toml
@@ -1,6 +1,6 @@
 [package]
 name = "xlings"
-version = "2026.8.11.2"
+version = "2026.8.13.1"
 description = "Universal package management infrastructure tool with SubOS isolation"
 license = "Apache-2.0"
 repo = "https://github.com/openxlings/xlings"
@@ -22,8 +22,18 @@ default = "gcc@16.1.0"
 macos = "llvm@20.1.7"
 windows = "llvm@20.1.7"
 
+# Same major as the dev toolchain on purpose. gcc 15.1.0-musl rejects a
+# `std::views::transform` pipeline once its function body lives in a module
+# implementation unit ("use of `operator|` before deduction of `auto`",
+# catalog.cpp), while gcc 16.1.0 accepts it -- and the reverse has bitten this
+# project too: `views::split | ranges::to` compiled under 15.1.0-musl and made a
+# whole module fail with "Bad file data" under 16.1.0
+# (.agents/docs/2026-08-06-subos-architecture-proposal.md). Range adaptors in
+# modules are fragile in BOTH directions across these two versions, so the two
+# targets now share one compiler major instead of trading one breakage for the
+# other.
 [target.x86_64-linux-musl]
-toolchain = "gcc@15.1.0-musl"
+toolchain = "gcc@16.1.0-musl"
 linkage = "static"
 
 # aarch64 (ARM64) static target — host-aware (native musl-gcc on ARM,
diff --git a/src/agent/agent.cpp b/src/agent/agent.cpp
new file mode 100644
index 00000000..586e81e8
--- /dev/null
+++ b/src/agent/agent.cpp
@@ -0,0 +1,99 @@
+// xlings.agent — `xlings agent` subcommand.
+//
+// Provides built-in skill content that LLM agents can retrieve at
+// runtime to learn how to use xlings.  The skill texts are compiled
+// into the binary (see agent/skills/*.cppm) so they are available
+// regardless of working directory or repo checkout.
+//
+// Command tree:
+//   xlings agent              → overview + skill list
+//   xlings agent skills       → skill list (same as above)
+//   xlings agent skills <n>   → print full content of skill <n>
+//   xlings agent <n>          → shorthand for skills <n>
+
+module xlings.agent;
+
+import std;
+import xlings.agent.skill;
+import xlings.agent.resources;
+
+namespace xlings::agent {
+
+// Print the overview text followed by the skill index table.
+void print_overview(const SkillRegistry& reg) {
+    std::cout << resources::kOverview << "\n\n";
+    std::cout << "Available skills (run `xlings agent skills <name>`):\n\n";
+    for (auto& s : reg.list()) {
+        std::string name{s->name()};
+        if (name.size() < 14) name.resize(14, ' ');
+        std::cout << "  " << name << s->description() << "\n";
+    }
+    std::cout << "\n";
+}
+
+// Print the full content of a named skill.
+bool print_skill(const SkillRegistry& reg, std::string_view name) {
+    auto* skill = reg.find(name);
+    if (skill) {
+        std::cout << skill->content() << "\n";
+        return true;
+    }
+    std::cerr << "Unknown skill: " << name << "\n";
+    std::cerr << "Available skills: ";
+    bool first = true;
+    for (auto& s : reg.list()) {
+        if (!first) std::cerr << ", ";
+        std::cerr << s->name();
+        first = false;
+    }
+    std::cerr << "\n";
+    std::cerr << "Run `xlings agent skills <name>` to view a skill.\n";
+    return false;
+}
+
+int run(int argc, char* argv[]) {
+    auto reg = resources::build_registry();
+
+    // No sub-argument: show overview
+    if (argc <= 2) {
+        print_overview(reg);
+        return 0;
+    }
+
+    std::string_view sub{argv[2]};
+
+    // Handle -h/--help as plain text (no TUI)
+    if (sub == "-h" || sub == "--help") {
+        print_overview(reg);
+        return 0;
+    }
+
+    if (sub == "skills") {
+        // `-h`/`--help` here is a help request, not a skill named "--help".
+        // Without this, `xlings agent skills --help` looks up a skill by that
+        // name, fails, and exits 1 -- the one shape a documented command path
+        // must never have.
+        if (argc <= 3 || std::string_view{argv[3]} == "-h"
+            || std::string_view{argv[3]} == "--help") {
+            print_overview(reg);
+            return 0;
+        }
+        // `xlings agent skills <name>`
+        return print_skill(reg, argv[3]) ? 0 : 1;
+    }
+
+    // Shorthand: `xlings agent <name>` → `xlings agent skills <name>`
+    if (reg.find(sub)) {
+        std::cout << reg.find(sub)->content() << "\n";
+        return 0;
+    }
+
+    std::cerr << "Unknown: xlings agent " << sub << "\n";
+    std::cerr << "Usage:\n";
+    std::cerr << "  xlings agent                 Show overview and skill list\n";
+    std::cerr << "  xlings agent skills          List available skills\n";
+    std::cerr << "  xlings agent skills <name>   Show a specific skill\n";
+    return 1;
+}
+
+}
diff --git a/src/agent/agent.cppm b/src/agent/agent.cppm
index fbc132e6..1a7d24a5 100644
--- a/src/agent/agent.cppm
+++ b/src/agent/agent.cppm
@@ -20,82 +20,7 @@ import xlings.agent.resources;
 
 namespace xlings::agent {
 
-// Print the overview text followed by the skill index table.
-void print_overview(const SkillRegistry& reg) {
-    std::cout << resources::kOverview << "\n\n";
-    std::cout << "Available skills (run `xlings agent skills <name>`):\n\n";
-    for (auto& s : reg.list()) {
-        std::string name{s->name()};
-        if (name.size() < 14) name.resize(14, ' ');
-        std::cout << "  " << name << s->description() << "\n";
-    }
-    std::cout << "\n";
-}
-
-// Print the full content of a named skill.
-bool print_skill(const SkillRegistry& reg, std::string_view name) {
-    auto* skill = reg.find(name);
-    if (skill) {
-        std::cout << skill->content() << "\n";
-        return true;
-    }
-    std::cerr << "Unknown skill: " << name << "\n";
-    std::cerr << "Available skills: ";
-    bool first = true;
-    for (auto& s : reg.list()) {
-        if (!first) std::cerr << ", ";
-        std::cerr << s->name();
-        first = false;
-    }
-    std::cerr << "\n";
-    std::cerr << "Run `xlings agent skills <name>` to view a skill.\n";
-    return false;
-}
-
 // Top-level handler for `xlings agent [args...]`.
-export int run(int argc, char* argv[]) {
-    auto reg = resources::build_registry();
-
-    // No sub-argument: show overview
-    if (argc <= 2) {
-        print_overview(reg);
-        return 0;
-    }
-
-    std::string_view sub{argv[2]};
-
-    // Handle -h/--help as plain text (no TUI)
-    if (sub == "-h" || sub == "--help") {
-        print_overview(reg);
-        return 0;
-    }
-
-    if (sub == "skills") {
-        // `-h`/`--help` here is a help request, not a skill named "--help".
-        // Without this, `xlings agent skills --help` looks up a skill by that
-        // name, fails, and exits 1 -- the one shape a documented command path
-        // must never have.
-        if (argc <= 3 || std::string_view{argv[3]} == "-h"
-            || std::string_view{argv[3]} == "--help") {
-            print_overview(reg);
-            return 0;
-        }
-        // `xlings agent skills <name>`
-        return print_skill(reg, argv[3]) ? 0 : 1;
-    }
-
-    // Shorthand: `xlings agent <name>` → `xlings agent skills <name>`
-    if (reg.find(sub)) {
-        std::cout << reg.find(sub)->content() << "\n";
-        return 0;
-    }
-
-    std::cerr << "Unknown: xlings agent " << sub << "\n";
-    std::cerr << "Usage:\n";
-    std::cerr << "  xlings agent                 Show overview and skill list\n";
-    std::cerr << "  xlings agent skills          List available skills\n";
-    std::cerr << "  xlings agent skills <name>   Show a specific skill\n";
-    return 1;
-}
+export int run(int argc, char* argv[]);
 
 }  // namespace xlings::agent
diff --git a/src/agent/resources.cpp b/src/agent/resources.cpp
new file mode 100644
index 00000000..ec4a2c38
--- /dev/null
+++ b/src/agent/resources.cpp
@@ -0,0 +1,24 @@
+// xlings.agent.resources — overview text + skill registry builder.
+//
+// The overview is the static text printed by `xlings agent`.
+// The registry is built by importing each skill module and registering
+// it.  To add a new skill, add its module import and a register call
+// in build_registry().
+
+module xlings.agent.resources;
+
+import std;
+import xlings.agent.skill;
+import xlings.agent.skills.usage;
+import xlings.agent.skills.contributing;
+
+namespace xlings::agent::resources {
+
+SkillRegistry build_registry() {
+    SkillRegistry reg;
+    reg.add(std::make_unique<skills::UsageSkill>());
+    reg.add(std::make_unique<skills::ContributingSkill>());
+    return reg;
+}
+
+}
diff --git a/src/agent/resources.cppm b/src/agent/resources.cppm
index 1fd72acb..8fdcce92 100644
--- a/src/agent/resources.cppm
+++ b/src/agent/resources.cppm
@@ -54,11 +54,6 @@ Run `xlings agent skills usage` now to learn the full usage guide.)PROMPT";
 //   2. Import its module above
 //   3. Add a register call below
 
-export SkillRegistry build_registry() {
-    SkillRegistry reg;
-    reg.add(std::make_unique<skills::UsageSkill>());
-    reg.add(std::make_unique<skills::ContributingSkill>());
-    return reg;
-}
+export SkillRegistry build_registry();
 
 }  // namespace xlings::agent::resources
diff --git a/src/agent/skills/contributing.cpp b/src/agent/skills/contributing.cpp
new file mode 100644
index 00000000..a2849c1e
--- /dev/null
+++ b/src/agent/skills/contributing.cpp
@@ -0,0 +1,22 @@
+// Skill: contributing — xlings project development workflow for AI agents.
+// Written as system-prompt-style instructions to enforce correct dev flow.
+
+module xlings.agent.skills.contributing;
+
+import std;
+import xlings.agent.skill;
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::agent::skills {
+
+auto ContributingSkill::name() const -> std::string_view { return "contributing"; }
+
+auto ContributingSkill::description() const -> std::string_view {
+    return "REQUIRED before any code change. Development workflow, PR rules, release process.";
+}
+
+auto ContributingSkill::content() const -> std::string_view { return kContent; }
+
+} // namespace xlings::agent::skills
diff --git a/src/agent/skills/contributing.cppm b/src/agent/skills/contributing.cppm
index e9369abd..063904e8 100644
--- a/src/agent/skills/contributing.cppm
+++ b/src/agent/skills/contributing.cppm
@@ -10,11 +10,9 @@ namespace xlings::agent::skills {
 
 export class ContributingSkill : public Skill {
 public:
-    auto name() const -> std::string_view override { return "contributing"; }
-    auto description() const -> std::string_view override {
-        return "REQUIRED before any code change. Development workflow, PR rules, release process.";
-    }
-    auto content() const -> std::string_view override { return kContent; }
+    auto name() const -> std::string_view override;
+    auto description() const -> std::string_view override;
+    auto content() const -> std::string_view override;
 
 private:
     static constexpr std::string_view kContent = R"SKILL([SYSTEM INSTRUCTION — xlings development workflow for AI agents]
diff --git a/src/agent/skills/skill.cpp b/src/agent/skills/skill.cpp
new file mode 100644
index 00000000..8c4b35df
--- /dev/null
+++ b/src/agent/skills/skill.cpp
@@ -0,0 +1,40 @@
+// xlings.agent.skill — Skill base class and registry.
+//
+// Every built-in skill implements the Skill interface and registers
+// itself with the SkillRegistry.  The registry drives `xlings agent`
+// (list) and `xlings agent skills <name>` (print).
+//
+// Adding a new skill:
+//   1. Create src/agent/skills/<name>.cppm
+//   2. Implement a class deriving from Skill
+//   3. Register it in SkillRegistry::build() below
+
+module xlings.agent.skill;
+
+import std;
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::agent {
+
+void SkillRegistry::add(std::unique_ptr<Skill> skill) {
+    skills_.push_back(std::move(skill));
+}
+
+auto SkillRegistry::list() const -> const std::vector<std::unique_ptr<Skill>>& {
+    return skills_;
+}
+
+auto SkillRegistry::find(std::string_view name) const -> const Skill* {
+    for (auto& s : skills_) {
+        if (s->name() == name) return s.get();
+    }
+    return nullptr;
+}
+
+auto SkillRegistry::count() const -> std::size_t {
+    return skills_.size();
+}
+
+} // namespace xlings::agent
diff --git a/src/agent/skills/skill.cppm b/src/agent/skills/skill.cppm
index 752f3974..b105b7c2 100644
--- a/src/agent/skills/skill.cppm
+++ b/src/agent/skills/skill.cppm
@@ -28,24 +28,13 @@ export struct Skill {
 
 export class SkillRegistry {
 public:
-    void add(std::unique_ptr<Skill> skill) {
-        skills_.push_back(std::move(skill));
-    }
-
-    auto list() const -> const std::vector<std::unique_ptr<Skill>>& {
-        return skills_;
-    }
-
-    auto find(std::string_view name) const -> const Skill* {
-        for (auto& s : skills_) {
-            if (s->name() == name) return s.get();
-        }
-        return nullptr;
-    }
-
-    auto count() const -> std::size_t {
-        return skills_.size();
-    }
+    void add(std::unique_ptr<Skill> skill);
+
+    auto list() const -> const std::vector<std::unique_ptr<Skill>>&;
+
+    auto find(std::string_view name) const -> const Skill*;
+
+    auto count() const -> std::size_t;
 
 private:
     std::vector<std::unique_ptr<Skill>> skills_;
diff --git a/src/agent/skills/usage.cpp b/src/agent/skills/usage.cpp
new file mode 100644
index 00000000..6cbbaf58
--- /dev/null
+++ b/src/agent/skills/usage.cpp
@@ -0,0 +1,33 @@
+// Skill: usage — Complete xlings usage guide for LLM agents.
+// Written as a system-prompt-style instruction set, not documentation.
+
+module xlings.agent.skills.usage;
+
+import std;
+import xlings.agent.skill;
+import xlings.cli.spec;
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::agent::skills {
+
+auto UsageSkill::name() const -> std::string_view { return "usage"; }
+
+auto UsageSkill::description() const -> std::string_view {
+    return "IMPORTANT: Read this FIRST. Complete usage instructions for AI agents.";
+}
+
+auto UsageSkill::content() const -> std::string_view {
+    static const std::string generated = [] {
+        std::string value{kContent};
+        constexpr std::string_view marker = "@@COMMAND_REFERENCE@@";
+        if (const auto at = value.find(marker); at != std::string::npos) {
+            value.replace(at, marker.size(), cli::spec::agent_reference());
+        }
+        return value;
+    }();
+    return generated;
+}
+
+} // namespace xlings::agent::skills
diff --git a/src/agent/skills/usage.cppm b/src/agent/skills/usage.cppm
index abd3dfb7..12a32c0d 100644
--- a/src/agent/skills/usage.cppm
+++ b/src/agent/skills/usage.cppm
@@ -11,21 +11,9 @@ namespace xlings::agent::skills {
 
 export class UsageSkill : public Skill {
 public:
-    auto name() const -> std::string_view override { return "usage"; }
-    auto description() const -> std::string_view override {
-        return "IMPORTANT: Read this FIRST. Complete usage instructions for AI agents.";
-    }
-    auto content() const -> std::string_view override {
-        static const std::string generated = [] {
-            std::string value{kContent};
-            constexpr std::string_view marker = "@@COMMAND_REFERENCE@@";
-            if (const auto at = value.find(marker); at != std::string::npos) {
-                value.replace(at, marker.size(), cli::spec::agent_reference());
-            }
-            return value;
-        }();
-        return generated;
-    }
+    auto name() const -> std::string_view override;
+    auto description() const -> std::string_view override;
+    auto content() const -> std::string_view override;
 
 private:
     static constexpr std::string_view kContent = R"SKILL([SYSTEM INSTRUCTION — xlings usage for AI agents]
diff --git a/src/agent/text_renderer.cpp b/src/agent/text_renderer.cpp
new file mode 100644
index 00000000..4f5c1050
--- /dev/null
+++ b/src/agent/text_renderer.cpp
@@ -0,0 +1,206 @@
+// xlings.agent.text_renderer — plain-text rendering for --agent mode.
+//
+// Converts DataEvent payloads to clean, unformatted text output.
+// No ANSI codes, no TUI decorations, no progress bar animations.
+// Designed to be easily readable by LLM agents.
+
+module xlings.agent.text_renderer;
+
+import std;
+import xlings.libs.json;
+import xlings.runtime.event;
+
+namespace xlings::agent {
+
+void render_data_event(const DataEvent& e) {
+    auto json = nlohmann::json::parse(e.json, nullptr, false);
+    if (json.is_discarded()) return;
+
+    if (e.kind == "info_panel") {
+        auto title = json.value("title", "");
+        if (!title.empty()) std::println("{}", title);
+        auto print_fields = [](const nlohmann::json& arr) {
+            if (!arr.is_array()) return;
+            for (auto& f : arr) {
+                // This renderer is plain text on purpose, so the amber the
+                // TTY panel uses to mark a broken row cannot reach it. The
+                // marker has to be a character, or an agent reading this
+                // stream sees a failing graphics vendor as one more field.
+                std::println("  {}{}: {}", f.value("alert", false) ? "! " : "",
+                             f.value("label", ""), f.value("value", ""));
+            }
+        };
+        if (json.contains("fields")) print_fields(json["fields"]);
+        if (json.contains("extra_fields")) print_fields(json["extra_fields"]);
+    }
+    else if (e.kind == "tip") {
+        std::println("hint: {}", json.value("message", ""));
+    }
+    else if (e.kind == "search_results") {
+        if (json.contains("results") && json["results"].is_array()) {
+            for (auto& r : json["results"]) {
+                if (r.is_array() && r.size() >= 2) {
+                    std::println("  {}  {}", r[0].get<std::string>(), r[1].get<std::string>());
+                }
+            }
+        }
+    }
+    else if (e.kind == "table") {
+        if (json.contains("headers") && json["headers"].is_array()) {
+            for (auto& h : json["headers"]) {
+                std::print("{}\t", h.get<std::string>());
+            }
+            std::println("");
+        }
+        if (json.contains("rows") && json["rows"].is_array()) {
+            for (auto& row : json["rows"]) {
+                if (row.is_array()) {
+                    for (auto& cell : row) {
+                        std::print("{}\t", cell.get<std::string>());
+                    }
+                    std::println("");
+                }
+            }
+        }
+    }
+    else if (e.kind == "install_plan") {
+        std::println("Install plan:");
+        if (json.contains("packages") && json["packages"].is_array()) {
+            for (auto& p : json["packages"]) {
+                if (p.is_array() && p.size() >= 2) {
+                    std::println("  {} {}", p[0].get<std::string>(), p[1].get<std::string>());
+                }
+            }
+        }
+    }
+    else if (e.kind == "install_summary") {
+        auto ok = json.value("success", 0);
+        auto fail = json.value("failed", 0);
+        if (fail > 0) {
+            std::println("Install complete: {} succeeded, {} failed", ok, fail);
+        } else {
+            std::println("Install complete: {} succeeded", ok);
+        }
+    }
+    else if (e.kind == "remove_plan") {
+        std::println("Remove: {} {} (subos: {})",
+            json.value("name", ""), json.value("version", ""), json.value("subos", ""));
+    }
+    else if (e.kind == "remove_summary") {
+        auto name = json.value("name", json.value("target", ""));
+        // Same distinction the TUI makes: a detach is not a removal, and an
+        // agent reading this must not conclude the payload is gone (#443).
+        if (json.value("detached", false)) {
+            std::string others;
+            if (json.contains("pinned_by") && json["pinned_by"].is_array()) {
+                for (auto& n : json["pinned_by"]) {
+                    if (!n.is_string()) continue;
+                    if (!others.empty()) others += ", ";
+                    others += n.get<std::string>();
+                }
+            }
+            std::println("Detached: {} {} (subos: {}); payload kept, still used by {}",
+                name, json.value("version", ""), json.value("subos", ""),
+                others.empty() ? std::string("another subos") : others);
+        } else {
+            std::println("Removed: {} {} (subos: {})",
+                name, json.value("version", ""), json.value("subos", ""));
+        }
+    }
+    else if (e.kind == "styled_list") {
+        auto title = json.value("title", "");
+        if (!title.empty()) std::println("{}", title);
+        if (json.contains("items") && json["items"].is_array()) {
+            int idx = 1;
+            bool numbered = json.value("numbered", false);
+            for (auto& item : json["items"]) {
+                if (item.is_array() && item.size() >= 2) {
+                    // The status qualifier goes next to the name, not at the
+                    // end of the line: an agent reading this transcript must
+                    // not be able to attribute `inactive` to the description.
+                    std::string status = item.size() >= 3
+                        ? item[2].get<std::string>() : std::string{};
+                    if (!status.empty()) status = " [" + status + "]";
+                    if (numbered) {
+                        std::println("  {}. {}{} {}", idx++, item[0].get<std::string>(), status, item[1].get<std::string>());
+                    } else {
+                        std::println("  {}{} {}", item[0].get<std::string>(), status, item[1].get<std::string>());
+                    }
+                } else if (item.is_string()) {
+                    if (numbered) {
+                        std::println("  {}. {}", idx++, item.get<std::string>());
+                    } else {
+                        std::println("  {}", item.get<std::string>());
+                    }
+                }
+            }
+        }
+    }
+    else if (e.kind == "subos_candidates") {
+        if (json.value("auto_selected", false)) {
+            std::println("Resolved subos: {} -> {}",
+                json.value("query", ""), json.value("selected", ""));
+        } else if (json.contains("candidates")
+                   && json["candidates"].is_array()) {
+            for (auto& candidate : json["candidates"]) {
+                auto name = candidate.value("name", "");
+                auto active = candidate.value("active", false);
+                std::println("  {}{}", name, active ? " (active)" : "");
+            }
+        }
+        auto hint = json.value("hint", "");
+        if (!hint.empty()) std::println("{}", hint);
+    }
+    else if (e.kind == "subos_list") {
+        if (json.contains("entries") && json["entries"].is_array()) {
+            for (auto& s : json["entries"]) {
+                auto name = s.value("name", "");
+                auto active = s.value("active", false);
+                auto pkgs = s.value("pkgCount", 0);
+                std::println("  {}{} ({} packages)",
+                    name, active ? " (active)" : "", pkgs);
+            }
+        }
+    }
+    else if (e.kind == "subos_created") {
+        std::println("Created subos: {} ({})",
+            json.value("name", ""), json.value("dir", ""));
+    }
+    else if (e.kind == "subos_switched") {
+        std::println("Switched to subos: {}", json.value("name", ""));
+    }
+    else if (e.kind == "subos_entering") {
+        std::println("Entering subos: {}", json.value("name", ""));
+    }
+    else if (e.kind == "subos_already_in") {
+        std::println("Already in subos: {}", json.value("name", ""));
+    }
+    else if (e.kind == "subos_nesting") {
+        std::println("Nesting subos: {} -> {}",
+            json.value("from", ""), json.value("to", ""));
+    }
+    else if (e.kind == "subos_removed") {
+        std::println("Removed subos: {}", json.value("name", ""));
+    }
+    else if (e.kind == "help") {
+        auto name = json.value("name", "");
+        auto desc = json.value("description", "");
+        if (!name.empty()) std::println("  xlings {}", name);
+        if (!desc.empty()) std::println("  {}", desc);
+        if (json.contains("args") && json["args"].is_array()) {
+            for (auto& a : json["args"]) {
+                std::println("    {} — {}", a.value("name", ""), a.value("desc", ""));
+            }
+        }
+        if (json.contains("opts") && json["opts"].is_array()) {
+            for (auto& o : json["opts"]) {
+                std::println("    {} — {}", o.value("name", ""), o.value("desc", ""));
+            }
+        }
+    }
+    // download_progress, system_info, env, repo_list, subos_shims:
+    // these are either noisy (progress) or already covered by info_panel.
+    // Skip silently — the log messages carry the essential info.
+}
+
+}
diff --git a/src/agent/text_renderer.cppm b/src/agent/text_renderer.cppm
index 90311fb7..3234d186 100644
--- a/src/agent/text_renderer.cppm
+++ b/src/agent/text_renderer.cppm
@@ -8,202 +8,12 @@ export module xlings.agent.text_renderer;
 
 import std;
 
-import xlings.libs.json;
 import xlings.runtime.event;
 
 namespace xlings::agent {
 
 // Render a DataEvent as plain text to stdout.
 // Silently skips event kinds that are purely visual (e.g. download_progress).
-export void render_data_event(const DataEvent& e) {
-    auto json = nlohmann::json::parse(e.json, nullptr, false);
-    if (json.is_discarded()) return;
-
-    if (e.kind == "info_panel") {
-        auto title = json.value("title", "");
-        if (!title.empty()) std::println("{}", title);
-        auto print_fields = [](const nlohmann::json& arr) {
-            if (!arr.is_array()) return;
-            for (auto& f : arr) {
-                // This renderer is plain text on purpose, so the amber the
-                // TTY panel uses to mark a broken row cannot reach it. The
-                // marker has to be a character, or an agent reading this
-                // stream sees a failing graphics vendor as one more field.
-                std::println("  {}{}: {}", f.value("alert", false) ? "! " : "",
-                             f.value("label", ""), f.value("value", ""));
-            }
-        };
-        if (json.contains("fields")) print_fields(json["fields"]);
-        if (json.contains("extra_fields")) print_fields(json["extra_fields"]);
-    }
-    else if (e.kind == "tip") {
-        std::println("hint: {}", json.value("message", ""));
-    }
-    else if (e.kind == "search_results") {
-        if (json.contains("results") && json["results"].is_array()) {
-            for (auto& r : json["results"]) {
-                if (r.is_array() && r.size() >= 2) {
-                    std::println("  {}  {}", r[0].get<std::string>(), r[1].get<std::string>());
-                }
-            }
-        }
-    }
-    else if (e.kind == "table") {
-        if (json.contains("headers") && json["headers"].is_array()) {
-            for (auto& h : json["headers"]) {
-                std::print("{}\t", h.get<std::string>());
-            }
-            std::println("");
-        }
-        if (json.contains("rows") && json["rows"].is_array()) {
-            for (auto& row : json["rows"]) {
-                if (row.is_array()) {
-                    for (auto& cell : row) {
-                        std::print("{}\t", cell.get<std::string>());
-                    }
-                    std::println("");
-                }
-            }
-        }
-    }
-    else if (e.kind == "install_plan") {
-        std::println("Install plan:");
-        if (json.contains("packages") && json["packages"].is_array()) {
-            for (auto& p : json["packages"]) {
-                if (p.is_array() && p.size() >= 2) {
-                    std::println("  {} {}", p[0].get<std::string>(), p[1].get<std::string>());
-                }
-            }
-        }
-    }
-    else if (e.kind == "install_summary") {
-        auto ok = json.value("success", 0);
-        auto fail = json.value("failed", 0);
-        if (fail > 0) {
-            std::println("Install complete: {} succeeded, {} failed", ok, fail);
-        } else {
-            std::println("Install complete: {} succeeded", ok);
-        }
-    }
-    else if (e.kind == "remove_plan") {
-        std::println("Remove: {} {} (subos: {})",
-            json.value("name", ""), json.value("version", ""), json.value("subos", ""));
-    }
-    else if (e.kind == "remove_summary") {
-        auto name = json.value("name", json.value("target", ""));
-        // Same distinction the TUI makes: a detach is not a removal, and an
-        // agent reading this must not conclude the payload is gone (#443).
-        if (json.value("detached", false)) {
-            std::string others;
-            if (json.contains("pinned_by") && json["pinned_by"].is_array()) {
-                for (auto& n : json["pinned_by"]) {
-                    if (!n.is_string()) continue;
-                    if (!others.empty()) others += ", ";
-                    others += n.get<std::string>();
-                }
-            }
-            std::println("Detached: {} {} (subos: {}); payload kept, still used by {}",
-                name, json.value("version", ""), json.value("subos", ""),
-                others.empty() ? std::string("another subos") : others);
-        } else {
-            std::println("Removed: {} {} (subos: {})",
-                name, json.value("version", ""), json.value("subos", ""));
-        }
-    }
-    else if (e.kind == "styled_list") {
-        auto title = json.value("title", "");
-        if (!title.empty()) std::println("{}", title);
-        if (json.contains("items") && json["items"].is_array()) {
-            int idx = 1;
-            bool numbered = json.value("numbered", false);
-            for (auto& item : json["items"]) {
-                if (item.is_array() && item.size() >= 2) {
-                    // The status qualifier goes next to the name, not at the
-                    // end of the line: an agent reading this transcript must
-                    // not be able to attribute `inactive` to the description.
-                    std::string status = item.size() >= 3
-                        ? item[2].get<std::string>() : std::string{};
-                    if (!status.empty()) status = " [" + status + "]";
-                    if (numbered) {
-                        std::println("  {}. {}{} {}", idx++, item[0].get<std::string>(), status, item[1].get<std::string>());
-                    } else {
-                        std::println("  {}{} {}", item[0].get<std::string>(), status, item[1].get<std::string>());
-                    }
-                } else if (item.is_string()) {
-                    if (numbered) {
-                        std::println("  {}. {}", idx++, item.get<std::string>());
-                    } else {
-                        std::println("  {}", item.get<std::string>());
-                    }
-                }
-            }
-        }
-    }
-    else if (e.kind == "subos_candidates") {
-        if (json.value("auto_selected", false)) {
-            std::println("Resolved subos: {} -> {}",
-                json.value("query", ""), json.value("selected", ""));
-        } else if (json.contains("candidates")
-                   && json["candidates"].is_array()) {
-            for (auto& candidate : json["candidates"]) {
-                auto name = candidate.value("name", "");
-                auto active = candidate.value("active", false);
-                std::println("  {}{}", name, active ? " (active)" : "");
-            }
-        }
-        auto hint = json.value("hint", "");
-        if (!hint.empty()) std::println("{}", hint);
-    }
-    else if (e.kind == "subos_list") {
-        if (json.contains("entries") && json["entries"].is_array()) {
-            for (auto& s : json["entries"]) {
-                auto name = s.value("name", "");
-                auto active = s.value("active", false);
-                auto pkgs = s.value("pkgCount", 0);
-                std::println("  {}{} ({} packages)",
-                    name, active ? " (active)" : "", pkgs);
-            }
-        }
-    }
-    else if (e.kind == "subos_created") {
-        std::println("Created subos: {} ({})",
-            json.value("name", ""), json.value("dir", ""));
-    }
-    else if (e.kind == "subos_switched") {
-        std::println("Switched to subos: {}", json.value("name", ""));
-    }
-    else if (e.kind == "subos_entering") {
-        std::println("Entering subos: {}", json.value("name", ""));
-    }
-    else if (e.kind == "subos_already_in") {
-        std::println("Already in subos: {}", json.value("name", ""));
-    }
-    else if (e.kind == "subos_nesting") {
-        std::println("Nesting subos: {} -> {}",
-            json.value("from", ""), json.value("to", ""));
-    }
-    else if (e.kind == "subos_removed") {
-        std::println("Removed subos: {}", json.value("name", ""));
-    }
-    else if (e.kind == "help") {
-        auto name = json.value("name", "");
-        auto desc = json.value("description", "");
-        if (!name.empty()) std::println("  xlings {}", name);
-        if (!desc.empty()) std::println("  {}", desc);
-        if (json.contains("args") && json["args"].is_array()) {
-            for (auto& a : json["args"]) {
-                std::println("    {} — {}", a.value("name", ""), a.value("desc", ""));
-            }
-        }
-        if (json.contains("opts") && json["opts"].is_array()) {
-            for (auto& o : json["opts"]) {
-                std::println("    {} — {}", o.value("name", ""), o.value("desc", ""));
-            }
-        }
-    }
-    // download_progress, system_info, env, repo_list, subos_shims:
-    // these are either noisy (progress) or already covered by info_panel.
-    // Skip silently — the log messages carry the essential info.
-}
+export void render_data_event(const DataEvent& e);
 
 }  // namespace xlings::agent
diff --git a/src/capabilities.cpp b/src/capabilities.cpp
new file mode 100644
index 00000000..d9bbf22a
--- /dev/null
+++ b/src/capabilities.cpp
@@ -0,0 +1,559 @@
+module xlings.capabilities;
+
+import std;
+import xlings.platform;
+import xlings.runtime.event;
+import xlings.runtime.event_stream;
+import xlings.runtime.capability;
+import xlings.libs.json;
+import xlings.core.xim.commands;
+import xlings.core.xim.index_cmd;
+import xlings.core.xvm.commands;
+import xlings.core.config;
+import xlings.core.home_config;
+import xlings.core.subos;
+import xlings.core.xself;
+import xlings.platform;
+import xlings.runtime.cancellation;
+import xlings.core.utf8;
+
+namespace xlings::capabilities {
+
+Result exit_result(int code) {
+    return nlohmann::json({{"exitCode", code}}).dump();
+}
+
+capability::Registry build_registry() {
+    capability::Registry reg;
+    // xlings core capabilities
+    reg.register_capability(std::make_unique<SearchPackages>());
+    reg.register_capability(std::make_unique<InstallPackages>());
+    reg.register_capability(std::make_unique<PlanInstall>());
+    reg.register_capability(std::make_unique<RemovePackage>());
+    reg.register_capability(std::make_unique<UpdatePackages>());
+    reg.register_capability(std::make_unique<ListPackages>());
+    reg.register_capability(std::make_unique<PackageInfo>());
+    reg.register_capability(std::make_unique<ListVersions>());
+    reg.register_capability(std::make_unique<UseVersion>());
+    reg.register_capability(std::make_unique<SystemStatus>());
+    reg.register_capability(std::make_unique<ListIndexVersions>());
+    // sub-OS + env (added 2026-04-26 per interface-api-v1-eval)
+    reg.register_capability(std::make_unique<ListSubos>());
+    reg.register_capability(std::make_unique<ListSubosShims>());
+    reg.register_capability(std::make_unique<CreateSubos>());
+    reg.register_capability(std::make_unique<SwitchSubos>());
+    reg.register_capability(std::make_unique<RemoveSubos>());
+    reg.register_capability(std::make_unique<Env>());
+    // Index repo management (added 2026-04-26 per interface-api-v1-eval P1)
+    reg.register_capability(std::make_unique<ListRepos>());
+    reg.register_capability(std::make_unique<AddRepo>());
+    reg.register_capability(std::make_unique<RemoveRepo>());
+    return reg;
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::capabilities {
+
+auto SearchPackages::spec() const -> CapabilitySpec {
+    return {
+        .name = "search_packages",
+        .description = "Search available packages by keyword (fuzzy match). Use plain name without version or namespace (e.g. gc matches gcc, musl-gcc)",
+        .inputSchema = R"JSON({"type":"object","properties":{"keyword":{"type":"string","description":"Keyword for fuzzy matching package names, e.g. gc, nod, rust"}},"required":["keyword"]})JSON",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = false,
+    };
+}
+
+auto SearchPackages::execute(Params params, EventStream& stream) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    auto keyword = json.value("keyword", "");
+    return exit_result(xim::cmd_search(keyword, stream));
+}
+
+auto InstallPackages::spec() const -> CapabilitySpec {
+    return {
+        .name = "install_packages",
+        .description = "Install one or more packages",
+        .inputSchema = R"({"type":"object","properties":{"targets":{"type":"array","items":{"type":"string"},"description":"Format: name, name@version, or namespace:name@version"},"yes":{"type":"boolean","description":"Auto-confirm without prompting"},"noDeps":{"type":"boolean","description":"Skip dependency installation"},"global":{"type":"boolean","description":"Install to global scope"},"useAfterInstall":{"type":"boolean","description":"Activate the installed version even if another version is currently active"}},"required":["targets"]})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = true,
+    };
+}
+
+auto InstallPackages::execute(Params params, EventStream& stream) -> Result {
+    return execute(std::move(params), stream, nullptr);
+}
+
+auto InstallPackages::execute(Params params, EventStream& stream, CancellationToken* cancel) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    std::vector<std::string> targets;
+    if (json.contains("targets") && json["targets"].is_array()) {
+        for (auto& t : json["targets"]) targets.push_back(t.get<std::string>());
+    }
+    bool yes = json.value("yes", false);
+    bool noDeps = json.value("noDeps", false);
+    bool global = json.value("global", false);
+    bool useAfter = json.value("useAfterInstall", false);
+    return exit_result(xim::cmd_install(targets, yes, noDeps, stream, global,
+                                         cancel, /*dryRun=*/false, useAfter));
+}
+
+auto PlanInstall::spec() const -> CapabilitySpec {
+    return {
+        .name = "plan_install",
+        .description = "Resolve targets and report what install_packages WOULD do (no download, no install)",
+        .inputSchema = R"({"type":"object","properties":{"targets":{"type":"array","items":{"type":"string"}},"noDeps":{"type":"boolean"},"global":{"type":"boolean"}},"required":["targets"]})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = false,
+    };
+}
+
+auto PlanInstall::execute(Params params, EventStream& stream) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    std::vector<std::string> targets;
+    if (json.contains("targets") && json["targets"].is_array()) {
+        for (auto& t : json["targets"]) targets.push_back(t.get<std::string>());
+    }
+    bool noDeps = json.value("noDeps", false);
+    bool global = json.value("global", false);
+    return exit_result(xim::cmd_install(targets, /*yes=*/true, noDeps, stream,
+                                         global, /*cancel=*/nullptr, /*dryRun=*/true));
+}
+
+auto RemovePackage::spec() const -> CapabilitySpec {
+    return {
+        .name = "remove_package",
+        .description = "Remove one package or one specific version. Only removes one target per call — to remove multiple versions, call multiple times",
+        .inputSchema = R"({"type":"object","properties":{"target":{"type":"string","description":"Format: name, name@version, or namespace:name@version"},"yes":{"type":"boolean","description":"Auto-confirm without prompting"}},"required":["target"]})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = true,
+    };
+}
+
+auto RemovePackage::execute(Params params, EventStream& stream) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    bool yes = json.value("yes", false);
+    bool force = json.value("force", false);
+    return exit_result(
+        xim::cmd_remove(json.value("target", ""), yes, stream, force));
+}
+
+auto UpdatePackages::spec() const -> CapabilitySpec {
+    return {
+        .name = "update_packages",
+        .description = "Update package index or upgrade a specific package to the latest declared version",
+        .inputSchema = R"({"type":"object","properties":{"target":{"type":"string","description":"Package name to upgrade, or omit to refresh the index only"},"yes":{"type":"boolean","description":"Auto-confirm the upgrade prompt"}}})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = true,
+    };
+}
+
+auto UpdatePackages::execute(Params params, EventStream& stream) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    bool yes = json.value("yes", false);
+    return exit_result(xim::cmd_update(json.value("target", ""), yes, stream));
+}
+
+auto ListPackages::spec() const -> CapabilitySpec {
+    return {
+        .name = "list_packages",
+        .description = "List installed packages. Filter is a plain package name keyword (fuzzy match, not regex)",
+        .inputSchema = R"JSON({"type":"object","properties":{"filter":{"type":"string","description":"Plain package name to filter, e.g. gcc, node"}}})JSON",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = false,
+    };
+}
+
+auto ListPackages::execute(Params params, EventStream& stream) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    return exit_result(xim::cmd_list(json.value("filter", ""), stream));
+}
+
+auto PackageInfo::spec() const -> CapabilitySpec {
+    return {
+        .name = "package_info",
+        .description = "Get detailed package info: versions, install status, metadata. Use namespace:name format (e.g. xim:gcc)",
+        .inputSchema = R"JSON({"type":"object","properties":{"target":{"type":"string","description":"Package in namespace:name format, e.g. xim:gcc"}},"required":["target"]})JSON",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = false,
+    };
+}
+
+auto PackageInfo::execute(Params params, EventStream& stream) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    return exit_result(xim::cmd_info(json.value("target", ""), stream));
+}
+
+auto ListVersions::spec() const -> CapabilitySpec {
+    return {
+        .name = "list_installed_versions",
+        .description = "List installed versions for a package and show which is active. Use plain name (e.g. gcc not xim:gcc)",
+        .inputSchema = R"JSON({"type":"object","properties":{"target":{"type":"string","description":"Plain package name, e.g. gcc, node"}},"required":["target"]})JSON",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = false,
+    };
+}
+
+auto ListVersions::execute(Params params, EventStream& stream) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    return exit_result(xvm::cmd_list_versions(json.value("target", ""), stream));
+}
+
+auto UseVersion::spec() const -> CapabilitySpec {
+    return {
+        .name = "use_version",
+        .description = "Switch to a specific version of a package. Use plain name (e.g. gcc not xim:gcc)",
+        .inputSchema = R"JSON({"type":"object","properties":{"target":{"type":"string","description":"Plain package name, e.g. gcc, node"},"version":{"type":"string","description":"Version to switch to, e.g. 15, 22"}},"required":["target","version"]})JSON",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = true,
+    };
+}
+
+auto UseVersion::execute(Params params, EventStream& stream) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    return exit_result(xvm::cmd_use(json.value("target", ""), json.value("version", ""), stream));
+}
+
+auto SystemStatus::spec() const -> CapabilitySpec {
+    return {
+        .name = "system_status",
+        .description = "Show xlings system configuration and status",
+        .inputSchema = R"({"type":"object","properties":{}})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = false,
+    };
+}
+
+auto SystemStatus::execute(Params params, EventStream& stream) -> Result {
+    auto& p = Config::paths();
+    nlohmann::json fields = nlohmann::json::array();
+    auto addField = [&](const std::string& label, const std::string& value, bool hl = false) {
+        fields.push_back({{"label", label}, {"value", value}, {"highlight", hl}});
+    };
+    addField("XLINGS_HOME", p.homeDir.string());
+    addField("XLINGS_DATA", p.dataDir.string());
+    addField("XLINGS_SUBOS", p.subosDir.string());
+    addField("active subos", p.activeSubos, true);
+    addField("bin", p.binDir.string());
+
+    auto mirror = Config::mirror();
+    if (!mirror.empty()) addField("mirror", mirror);
+    auto lang = Config::lang();
+    if (!lang.empty()) addField("lang", lang);
+
+    nlohmann::json payload;
+    payload["title"] = "xlings status";
+    payload["fields"] = std::move(fields);
+    stream.emit(DataEvent{"system_info", payload.dump()});
+    return exit_result(0);
+}
+
+auto ListIndexVersions::spec() const -> CapabilitySpec {
+    return {
+        .name = "list_index_versions",
+        .description = "List published index snapshots and which one is in use",
+        .inputSchema = R"({"type":"object","properties":{"name":{"type":"string"}}})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = false,
+    };
+}
+
+auto ListIndexVersions::execute(Params params, EventStream& stream) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    const auto filter = json.is_object() ? json.value("name", std::string{})
+                                         : std::string{};
+    auto views = xim::collect_index_sources();
+    if (!filter.empty()) {
+        std::erase_if(views, [&](const auto& v) { return v.name != filter; });
+        if (views.empty()) {
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::NotFound,
+                .message = std::format("no index source named '{}'", filter),
+                .recoverable = false,
+            });
+            return exit_result(1);
+        }
+    }
+    stream.emit(DataEvent{"index_versions",
+                          xim::index_sources_json(views).dump()});
+    return exit_result(0);
+}
+
+auto ListSubos::spec() const -> CapabilitySpec {
+    return {
+        .name = "list_subos",
+        .description = "List all sub-OSs and which one is active",
+        .inputSchema = R"({"type":"object","properties":{}})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = false,
+    };
+}
+
+auto ListSubos::execute(Params, EventStream& stream) -> Result {
+    auto all = subos::candidate_view().candidates;
+    nlohmann::json entries = nlohmann::json::array();
+    for (auto& s : all) {
+        entries.push_back({
+            {"name",     s.name},
+            {"dir",      s.dir.string()},
+            {"pkgCount", s.toolCount},
+            {"active",   s.isActive},
+        });
+    }
+    nlohmann::json payload;
+    payload["entries"] = std::move(entries);
+    stream.emit(DataEvent{"subos_list", payload.dump()});
+    return exit_result(0);
+}
+
+auto ListSubosShims::spec() const -> CapabilitySpec {
+    return {
+        .name = "list_subos_shims",
+        .description = "List installed shim binaries in the active sub-OS bin directory",
+        .inputSchema = R"({"type":"object","properties":{}})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = false,
+    };
+}
+
+auto ListSubosShims::execute(Params, EventStream& stream) -> Result {
+    auto& p = Config::paths();
+    std::vector<std::string> shims;
+    if (std::filesystem::exists(p.binDir)) {
+        for (auto& e : platform::dir_entries(p.binDir)) {
+            auto stem = e.path().stem().string();
+            if (xself::is_builtin_shim(stem) || stem == "xvm-alias") continue;
+            shims.push_back(std::move(stem));
+        }
+    }
+    std::ranges::sort(shims);
+    nlohmann::json payload;
+    payload["shims"]  = shims;
+    payload["binDir"] = p.binDir.string();
+    stream.emit(DataEvent{"subos_shims", payload.dump()});
+    return exit_result(0);
+}
+
+auto CreateSubos::spec() const -> CapabilitySpec {
+    return {
+        .name = "create_subos",
+        .description = "Create a new sub-OS. The name must be alphanumeric (plus _ or -); 'current' is reserved",
+        .inputSchema = R"({"type":"object","properties":{"name":{"type":"string"},"dir":{"type":"string","description":"Optional custom directory; defaults to $XLINGS_HOME/subos/<name>"}},"required":["name"]})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = true,
+    };
+}
+
+auto CreateSubos::execute(Params params, EventStream& stream) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    auto name = json.value("name", "");
+    auto dir  = json.value("dir", "");
+    return exit_result(subos::create(
+        name,
+        dir.empty() ? std::filesystem::path{} : std::filesystem::path{dir},
+        stream));
+}
+
+auto SwitchSubos::spec() const -> CapabilitySpec {
+    return {
+        .name = "switch_subos",
+        .description = "Switch the active sub-OS to <name>",
+        .inputSchema = R"({"type":"object","properties":{"name":{"type":"string"}},"required":["name"]})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = true,
+    };
+}
+
+auto SwitchSubos::execute(Params params, EventStream& stream) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    return exit_result(subos::use(json.value("name", ""), stream));
+}
+
+auto RemoveSubos::spec() const -> CapabilitySpec {
+    return {
+        .name = "remove_subos",
+        .description = "Remove a sub-OS. Refuses to remove 'default' or the currently active sub-OS",
+        .inputSchema = R"({"type":"object","properties":{"name":{"type":"string"}},"required":["name"]})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = true,
+    };
+}
+
+auto RemoveSubos::execute(Params params, EventStream& stream) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    return exit_result(subos::remove(json.value("name", ""), stream));
+}
+
+auto ListRepos::spec() const -> CapabilitySpec {
+    return {
+        .name = "list_repos",
+        .description = "List configured xim package index repositories (global + project)",
+        .inputSchema = R"({"type":"object","properties":{}})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = false,
+    };
+}
+
+auto ListRepos::execute(Params, EventStream& stream) -> Result {
+    nlohmann::json repos = nlohmann::json::array();
+    for (auto& r : Config::global_index_repos()) {
+        repos.push_back({{"name", r.name}, {"url", r.url}, {"scope", "global"}});
+    }
+    if (Config::has_project_config()) {
+        for (auto& r : Config::project_index_repos()) {
+            repos.push_back({{"name", r.name}, {"url", r.url}, {"scope", "project"}});
+        }
+    }
+    nlohmann::json payload;
+    payload["repos"] = std::move(repos);
+    payload["override"] = (Config::has_project_config() && !Config::project_index_repos().empty())
+                          ? "project" : "global";
+    stream.emit(DataEvent{"repo_list", payload.dump()});
+    return exit_result(0);
+}
+
+auto AddRepo::spec() const -> CapabilitySpec {
+    return {
+        .name = "add_repo",
+        .description = "Add or update a global xim index repository. If the name already exists, the URL is updated in place",
+        .inputSchema = R"({"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","description":"git URL of the index repository"}},"required":["name","url"]})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = true,
+    };
+}
+
+auto AddRepo::execute(Params params, EventStream& stream) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    auto name = json.value("name", "");
+    auto url  = json.value("url",  "");
+    if (name.empty() || url.empty()) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = "add_repo requires non-empty name and url",
+            .recoverable = false,
+        });
+        return exit_result(1);
+    }
+
+    auto committed = update_home_config(
+        Config::paths().homeDir, [&](nlohmann::json& cfg) {
+            if (!cfg.contains("index_repos")
+                || !cfg["index_repos"].is_array()) {
+                cfg["index_repos"] = nlohmann::json::array();
+            }
+            for (auto& entry : cfg["index_repos"]) {
+                if (entry.is_object() && entry.contains("name")
+                    && entry["name"].get<std::string>() == name) {
+                    entry["url"] = url;
+                    return true;
+                }
+            }
+            nlohmann::json entry;
+            entry["name"] = name;
+            entry["url"]  = url;
+            cfg["index_repos"].push_back(std::move(entry));
+            return true;
+        });
+    if (!committed) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::Permission,
+            .message = "write .xlings.json failed: " + committed.error(),
+            .recoverable = false,
+        });
+        return exit_result(1);
+    }
+    return exit_result(0);
+}
+
+auto RemoveRepo::spec() const -> CapabilitySpec {
+    return {
+        .name = "remove_repo",
+        .description = "Remove a global xim index repository by name",
+        .inputSchema = R"({"type":"object","properties":{"name":{"type":"string"}},"required":["name"]})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = true,
+    };
+}
+
+auto RemoveRepo::execute(Params params, EventStream& stream) -> Result {
+    auto json = nlohmann::json::parse(params, nullptr, false);
+    auto name = json.value("name", "");
+    if (name.empty()) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = "remove_repo requires non-empty name",
+            .recoverable = false,
+        });
+        return exit_result(1);
+    }
+
+    // "not found" is decided inside the lock too. Deciding it from an
+    // earlier read could report success for a repo another process had
+    // already deleted, or -- worse -- write back an index_repos array
+    // that predates a repo it had just added.
+    auto committed = update_home_config(
+        Config::paths().homeDir, [&](nlohmann::json& cfg) {
+            if (!cfg.contains("index_repos")
+                || !cfg["index_repos"].is_array()) {
+                return false;
+            }
+            auto& arr = cfg["index_repos"];
+            bool removed = false;
+            for (auto it = arr.begin(); it != arr.end(); ) {
+                if (it->is_object() && it->contains("name")
+                    && (*it)["name"].get<std::string>() == name) {
+                    it = arr.erase(it);
+                    removed = true;
+                } else { ++it; }
+            }
+            return removed;
+        });
+    if (!committed) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::Permission,
+            .message = "write .xlings.json failed: " + committed.error(),
+            .recoverable = false,
+        });
+        return exit_result(1);
+    }
+    if (!*committed) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::NotFound,
+            .message = "no repo named '" + name + "'",
+            .recoverable = true,
+        });
+        return exit_result(1);
+    }
+    return exit_result(0);
+}
+
+auto Env::spec() const -> CapabilitySpec {
+    return {
+        .name = "env",
+        .description = "Return effective xlings environment (home, active sub-OS, paths, mirror, lang)",
+        .inputSchema = R"({"type":"object","properties":{}})",
+        .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
+        .destructive = false,
+    };
+}
+
+auto Env::execute(Params, EventStream& stream) -> Result {
+    auto& p = Config::paths();
+    nlohmann::json payload;
+    payload["xlingsHome"]  = p.homeDir.string();
+    payload["dataDir"]     = p.dataDir.string();
+    payload["subosDir"]    = p.subosDir.string();
+    payload["binDir"]      = p.binDir.string();
+    payload["libDir"]      = p.libDir.string();
+    payload["activeSubos"] = p.activeSubos;
+    payload["mirror"]      = Config::mirror();
+    payload["lang"]        = Config::lang();
+    stream.emit(DataEvent{"env", payload.dump()});
+    return exit_result(0);
+}
+
+} // namespace xlings::capabilities
diff --git a/src/capabilities.cppm b/src/capabilities.cppm
index f4443a45..cfaa6753 100644
--- a/src/capabilities.cppm
+++ b/src/capabilities.cppm
@@ -1,21 +1,10 @@
 export module xlings.capabilities;
 
 import std;
-import xlings.platform;
 import xlings.runtime.event;
 import xlings.runtime.event_stream;
 import xlings.runtime.capability;
-import xlings.libs.json;
-import xlings.core.xim.commands;
-import xlings.core.xim.index_cmd;
-import xlings.core.xvm.commands;
-import xlings.core.config;
-import xlings.core.home_config;
-import xlings.core.subos;
-import xlings.core.xself;
-import xlings.platform;
 import xlings.runtime.cancellation;
-import xlings.core.utf8;
 
 namespace xlings::capabilities {
 
@@ -24,55 +13,19 @@ using capability::CapabilitySpec;
 using capability::Params;
 using capability::Result;
 
-Result exit_result(int code) {
-    return nlohmann::json({{"exitCode", code}}).dump();
-}
+Result exit_result(int code);
 
 class SearchPackages : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "search_packages",
-            .description = "Search available packages by keyword (fuzzy match). Use plain name without version or namespace (e.g. gc matches gcc, musl-gcc)",
-            .inputSchema = R"JSON({"type":"object","properties":{"keyword":{"type":"string","description":"Keyword for fuzzy matching package names, e.g. gc, nod, rust"}},"required":["keyword"]})JSON",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = false,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        auto keyword = json.value("keyword", "");
-        return exit_result(xim::cmd_search(keyword, stream));
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 class InstallPackages : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "install_packages",
-            .description = "Install one or more packages",
-            .inputSchema = R"({"type":"object","properties":{"targets":{"type":"array","items":{"type":"string"},"description":"Format: name, name@version, or namespace:name@version"},"yes":{"type":"boolean","description":"Auto-confirm without prompting"},"noDeps":{"type":"boolean","description":"Skip dependency installation"},"global":{"type":"boolean","description":"Install to global scope"},"useAfterInstall":{"type":"boolean","description":"Activate the installed version even if another version is currently active"}},"required":["targets"]})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = true,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        return execute(std::move(params), stream, nullptr);
-    }
-    auto execute(Params params, EventStream& stream, CancellationToken* cancel) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        std::vector<std::string> targets;
-        if (json.contains("targets") && json["targets"].is_array()) {
-            for (auto& t : json["targets"]) targets.push_back(t.get<std::string>());
-        }
-        bool yes = json.value("yes", false);
-        bool noDeps = json.value("noDeps", false);
-        bool global = json.value("global", false);
-        bool useAfter = json.value("useAfterInstall", false);
-        return exit_result(xim::cmd_install(targets, yes, noDeps, stream, global,
-                                             cancel, /*dryRun=*/false, useAfter));
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
+    auto execute(Params params, EventStream& stream, CancellationToken* cancel) -> Result override;
 };
 
 // Pre-flight planning entry point. Resolves targets and emits the
@@ -80,168 +33,50 @@ public:
 // Clients use this for dry-run / "would do X" UX without committing.
 class PlanInstall : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "plan_install",
-            .description = "Resolve targets and report what install_packages WOULD do (no download, no install)",
-            .inputSchema = R"({"type":"object","properties":{"targets":{"type":"array","items":{"type":"string"}},"noDeps":{"type":"boolean"},"global":{"type":"boolean"}},"required":["targets"]})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = false,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        std::vector<std::string> targets;
-        if (json.contains("targets") && json["targets"].is_array()) {
-            for (auto& t : json["targets"]) targets.push_back(t.get<std::string>());
-        }
-        bool noDeps = json.value("noDeps", false);
-        bool global = json.value("global", false);
-        return exit_result(xim::cmd_install(targets, /*yes=*/true, noDeps, stream,
-                                             global, /*cancel=*/nullptr, /*dryRun=*/true));
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 class RemovePackage : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "remove_package",
-            .description = "Remove one package or one specific version. Only removes one target per call — to remove multiple versions, call multiple times",
-            .inputSchema = R"({"type":"object","properties":{"target":{"type":"string","description":"Format: name, name@version, or namespace:name@version"},"yes":{"type":"boolean","description":"Auto-confirm without prompting"}},"required":["target"]})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = true,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        bool yes = json.value("yes", false);
-        bool force = json.value("force", false);
-        return exit_result(
-            xim::cmd_remove(json.value("target", ""), yes, stream, force));
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 class UpdatePackages : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "update_packages",
-            .description = "Update package index or upgrade a specific package to the latest declared version",
-            .inputSchema = R"({"type":"object","properties":{"target":{"type":"string","description":"Package name to upgrade, or omit to refresh the index only"},"yes":{"type":"boolean","description":"Auto-confirm the upgrade prompt"}}})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = true,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        bool yes = json.value("yes", false);
-        return exit_result(xim::cmd_update(json.value("target", ""), yes, stream));
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 class ListPackages : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "list_packages",
-            .description = "List installed packages. Filter is a plain package name keyword (fuzzy match, not regex)",
-            .inputSchema = R"JSON({"type":"object","properties":{"filter":{"type":"string","description":"Plain package name to filter, e.g. gcc, node"}}})JSON",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = false,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        return exit_result(xim::cmd_list(json.value("filter", ""), stream));
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 class PackageInfo : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "package_info",
-            .description = "Get detailed package info: versions, install status, metadata. Use namespace:name format (e.g. xim:gcc)",
-            .inputSchema = R"JSON({"type":"object","properties":{"target":{"type":"string","description":"Package in namespace:name format, e.g. xim:gcc"}},"required":["target"]})JSON",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = false,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        return exit_result(xim::cmd_info(json.value("target", ""), stream));
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 class ListVersions : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "list_installed_versions",
-            .description = "List installed versions for a package and show which is active. Use plain name (e.g. gcc not xim:gcc)",
-            .inputSchema = R"JSON({"type":"object","properties":{"target":{"type":"string","description":"Plain package name, e.g. gcc, node"}},"required":["target"]})JSON",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = false,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        return exit_result(xvm::cmd_list_versions(json.value("target", ""), stream));
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 class UseVersion : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "use_version",
-            .description = "Switch to a specific version of a package. Use plain name (e.g. gcc not xim:gcc)",
-            .inputSchema = R"JSON({"type":"object","properties":{"target":{"type":"string","description":"Plain package name, e.g. gcc, node"},"version":{"type":"string","description":"Version to switch to, e.g. 15, 22"}},"required":["target","version"]})JSON",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = true,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        return exit_result(xvm::cmd_use(json.value("target", ""), json.value("version", ""), stream));
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 class SystemStatus : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "system_status",
-            .description = "Show xlings system configuration and status",
-            .inputSchema = R"({"type":"object","properties":{}})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = false,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto& p = Config::paths();
-        nlohmann::json fields = nlohmann::json::array();
-        auto addField = [&](const std::string& label, const std::string& value, bool hl = false) {
-            fields.push_back({{"label", label}, {"value", value}, {"highlight", hl}});
-        };
-        addField("XLINGS_HOME", p.homeDir.string());
-        addField("XLINGS_DATA", p.dataDir.string());
-        addField("XLINGS_SUBOS", p.subosDir.string());
-        addField("active subos", p.activeSubos, true);
-        addField("bin", p.binDir.string());
-
-        auto mirror = Config::mirror();
-        if (!mirror.empty()) addField("mirror", mirror);
-        auto lang = Config::lang();
-        if (!lang.empty()) addField("lang", lang);
-
-        nlohmann::json payload;
-        payload["title"] = "xlings status";
-        payload["fields"] = std::move(fields);
-        stream.emit(DataEvent{"system_info", payload.dump()});
-        return exit_result(0);
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 // #476: the programmatic entry point for index snapshot selection.
@@ -253,356 +88,66 @@ public:
 // `xlings index use`.
 class ListIndexVersions : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "list_index_versions",
-            .description = "List published index snapshots and which one is in use",
-            .inputSchema = R"({"type":"object","properties":{"name":{"type":"string"}}})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = false,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        const auto filter = json.is_object() ? json.value("name", std::string{})
-                                             : std::string{};
-        auto views = xim::collect_index_sources();
-        if (!filter.empty()) {
-            std::erase_if(views, [&](const auto& v) { return v.name != filter; });
-            if (views.empty()) {
-                stream.emit(ErrorEvent{
-                    .code = ErrorCode::NotFound,
-                    .message = std::format("no index source named '{}'", filter),
-                    .recoverable = false,
-                });
-                return exit_result(1);
-            }
-        }
-        stream.emit(DataEvent{"index_versions",
-                              xim::index_sources_json(views).dump()});
-        return exit_result(0);
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 class ListSubos : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "list_subos",
-            .description = "List all sub-OSs and which one is active",
-            .inputSchema = R"({"type":"object","properties":{}})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = false,
-        };
-    }
-    auto execute(Params, EventStream& stream) -> Result override {
-        auto all = subos::candidate_view().candidates;
-        nlohmann::json entries = nlohmann::json::array();
-        for (auto& s : all) {
-            entries.push_back({
-                {"name",     s.name},
-                {"dir",      s.dir.string()},
-                {"pkgCount", s.toolCount},
-                {"active",   s.isActive},
-            });
-        }
-        nlohmann::json payload;
-        payload["entries"] = std::move(entries);
-        stream.emit(DataEvent{"subos_list", payload.dump()});
-        return exit_result(0);
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params, EventStream& stream) -> Result override;
 };
 
 class ListSubosShims : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "list_subos_shims",
-            .description = "List installed shim binaries in the active sub-OS bin directory",
-            .inputSchema = R"({"type":"object","properties":{}})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = false,
-        };
-    }
-    auto execute(Params, EventStream& stream) -> Result override {
-        auto& p = Config::paths();
-        std::vector<std::string> shims;
-        if (std::filesystem::exists(p.binDir)) {
-            for (auto& e : platform::dir_entries(p.binDir)) {
-                auto stem = e.path().stem().string();
-                if (xself::is_builtin_shim(stem) || stem == "xvm-alias") continue;
-                shims.push_back(std::move(stem));
-            }
-        }
-        std::ranges::sort(shims);
-        nlohmann::json payload;
-        payload["shims"]  = shims;
-        payload["binDir"] = p.binDir.string();
-        stream.emit(DataEvent{"subos_shims", payload.dump()});
-        return exit_result(0);
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params, EventStream& stream) -> Result override;
 };
 
 class CreateSubos : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "create_subos",
-            .description = "Create a new sub-OS. The name must be alphanumeric (plus _ or -); 'current' is reserved",
-            .inputSchema = R"({"type":"object","properties":{"name":{"type":"string"},"dir":{"type":"string","description":"Optional custom directory; defaults to $XLINGS_HOME/subos/<name>"}},"required":["name"]})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = true,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        auto name = json.value("name", "");
-        auto dir  = json.value("dir", "");
-        return exit_result(subos::create(
-            name,
-            dir.empty() ? std::filesystem::path{} : std::filesystem::path{dir},
-            stream));
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 class SwitchSubos : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "switch_subos",
-            .description = "Switch the active sub-OS to <name>",
-            .inputSchema = R"({"type":"object","properties":{"name":{"type":"string"}},"required":["name"]})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = true,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        return exit_result(subos::use(json.value("name", ""), stream));
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 class RemoveSubos : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "remove_subos",
-            .description = "Remove a sub-OS. Refuses to remove 'default' or the currently active sub-OS",
-            .inputSchema = R"({"type":"object","properties":{"name":{"type":"string"}},"required":["name"]})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = true,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        return exit_result(subos::remove(json.value("name", ""), stream));
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 // ─── Index repos ────────────────────────────────────────────
 
 class ListRepos : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "list_repos",
-            .description = "List configured xim package index repositories (global + project)",
-            .inputSchema = R"({"type":"object","properties":{}})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = false,
-        };
-    }
-    auto execute(Params, EventStream& stream) -> Result override {
-        nlohmann::json repos = nlohmann::json::array();
-        for (auto& r : Config::global_index_repos()) {
-            repos.push_back({{"name", r.name}, {"url", r.url}, {"scope", "global"}});
-        }
-        if (Config::has_project_config()) {
-            for (auto& r : Config::project_index_repos()) {
-                repos.push_back({{"name", r.name}, {"url", r.url}, {"scope", "project"}});
-            }
-        }
-        nlohmann::json payload;
-        payload["repos"] = std::move(repos);
-        payload["override"] = (Config::has_project_config() && !Config::project_index_repos().empty())
-                              ? "project" : "global";
-        stream.emit(DataEvent{"repo_list", payload.dump()});
-        return exit_result(0);
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params, EventStream& stream) -> Result override;
 };
 
 class AddRepo : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "add_repo",
-            .description = "Add or update a global xim index repository. If the name already exists, the URL is updated in place",
-            .inputSchema = R"({"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","description":"git URL of the index repository"}},"required":["name","url"]})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = true,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        auto name = json.value("name", "");
-        auto url  = json.value("url",  "");
-        if (name.empty() || url.empty()) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::InvalidInput,
-                .message = "add_repo requires non-empty name and url",
-                .recoverable = false,
-            });
-            return exit_result(1);
-        }
-
-        auto committed = update_home_config(
-            Config::paths().homeDir, [&](nlohmann::json& cfg) {
-                if (!cfg.contains("index_repos")
-                    || !cfg["index_repos"].is_array()) {
-                    cfg["index_repos"] = nlohmann::json::array();
-                }
-                for (auto& entry : cfg["index_repos"]) {
-                    if (entry.is_object() && entry.contains("name")
-                        && entry["name"].get<std::string>() == name) {
-                        entry["url"] = url;
-                        return true;
-                    }
-                }
-                nlohmann::json entry;
-                entry["name"] = name;
-                entry["url"]  = url;
-                cfg["index_repos"].push_back(std::move(entry));
-                return true;
-            });
-        if (!committed) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::Permission,
-                .message = "write .xlings.json failed: " + committed.error(),
-                .recoverable = false,
-            });
-            return exit_result(1);
-        }
-        return exit_result(0);
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 class RemoveRepo : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "remove_repo",
-            .description = "Remove a global xim index repository by name",
-            .inputSchema = R"({"type":"object","properties":{"name":{"type":"string"}},"required":["name"]})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = true,
-        };
-    }
-    auto execute(Params params, EventStream& stream) -> Result override {
-        auto json = nlohmann::json::parse(params, nullptr, false);
-        auto name = json.value("name", "");
-        if (name.empty()) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::InvalidInput,
-                .message = "remove_repo requires non-empty name",
-                .recoverable = false,
-            });
-            return exit_result(1);
-        }
-
-        // "not found" is decided inside the lock too. Deciding it from an
-        // earlier read could report success for a repo another process had
-        // already deleted, or -- worse -- write back an index_repos array
-        // that predates a repo it had just added.
-        auto committed = update_home_config(
-            Config::paths().homeDir, [&](nlohmann::json& cfg) {
-                if (!cfg.contains("index_repos")
-                    || !cfg["index_repos"].is_array()) {
-                    return false;
-                }
-                auto& arr = cfg["index_repos"];
-                bool removed = false;
-                for (auto it = arr.begin(); it != arr.end(); ) {
-                    if (it->is_object() && it->contains("name")
-                        && (*it)["name"].get<std::string>() == name) {
-                        it = arr.erase(it);
-                        removed = true;
-                    } else { ++it; }
-                }
-                return removed;
-            });
-        if (!committed) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::Permission,
-                .message = "write .xlings.json failed: " + committed.error(),
-                .recoverable = false,
-            });
-            return exit_result(1);
-        }
-        if (!*committed) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::NotFound,
-                .message = "no repo named '" + name + "'",
-                .recoverable = true,
-            });
-            return exit_result(1);
-        }
-        return exit_result(0);
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params params, EventStream& stream) -> Result override;
 };
 
 class Env : public Capability {
 public:
-    auto spec() const -> CapabilitySpec override {
-        return {
-            .name = "env",
-            .description = "Return effective xlings environment (home, active sub-OS, paths, mirror, lang)",
-            .inputSchema = R"({"type":"object","properties":{}})",
-            .outputSchema = R"({"type":"object","properties":{"exitCode":{"type":"integer"}}})",
-            .destructive = false,
-        };
-    }
-    auto execute(Params, EventStream& stream) -> Result override {
-        auto& p = Config::paths();
-        nlohmann::json payload;
-        payload["xlingsHome"]  = p.homeDir.string();
-        payload["dataDir"]     = p.dataDir.string();
-        payload["subosDir"]    = p.subosDir.string();
-        payload["binDir"]      = p.binDir.string();
-        payload["libDir"]      = p.libDir.string();
-        payload["activeSubos"] = p.activeSubos;
-        payload["mirror"]      = Config::mirror();
-        payload["lang"]        = Config::lang();
-        stream.emit(DataEvent{"env", payload.dump()});
-        return exit_result(0);
-    }
+    auto spec() const -> CapabilitySpec override;
+    auto execute(Params, EventStream& stream) -> Result override;
 };
 
-export capability::Registry build_registry() {
-    capability::Registry reg;
-    // xlings core capabilities
-    reg.register_capability(std::make_unique<SearchPackages>());
-    reg.register_capability(std::make_unique<InstallPackages>());
-    reg.register_capability(std::make_unique<PlanInstall>());
-    reg.register_capability(std::make_unique<RemovePackage>());
-    reg.register_capability(std::make_unique<UpdatePackages>());
-    reg.register_capability(std::make_unique<ListPackages>());
-    reg.register_capability(std::make_unique<PackageInfo>());
-    reg.register_capability(std::make_unique<ListVersions>());
-    reg.register_capability(std::make_unique<UseVersion>());
-    reg.register_capability(std::make_unique<SystemStatus>());
-    reg.register_capability(std::make_unique<ListIndexVersions>());
-    // sub-OS + env (added 2026-04-26 per interface-api-v1-eval)
-    reg.register_capability(std::make_unique<ListSubos>());
-    reg.register_capability(std::make_unique<ListSubosShims>());
-    reg.register_capability(std::make_unique<CreateSubos>());
-    reg.register_capability(std::make_unique<SwitchSubos>());
-    reg.register_capability(std::make_unique<RemoveSubos>());
-    reg.register_capability(std::make_unique<Env>());
-    // Index repo management (added 2026-04-26 per interface-api-v1-eval P1)
-    reg.register_capability(std::make_unique<ListRepos>());
-    reg.register_capability(std::make_unique<AddRepo>());
-    reg.register_capability(std::make_unique<RemoveRepo>());
-    return reg;
-}
+export capability::Registry build_registry();
 
 } // namespace xlings::capabilities
diff --git a/src/cli.cpp b/src/cli.cpp
new file mode 100644
index 00000000..fc62fcd4
--- /dev/null
+++ b/src/cli.cpp
@@ -0,0 +1,1252 @@
+module;
+
+#include "ftxui/component/event.hpp"
+#include "ftxui/component/mouse.hpp"
+
+#include <cstdio>
+
+module xlings.cli;
+
+import std;
+import mcpplibs.cmdline;
+import mcpplibs.capi.lua;
+import mcpplibs.xpkg.executor;
+import xlings.core.config;
+import xlings.core.home_config;
+import xlings.libs.json;
+import xlings.core.log;
+import xlings.runtime;
+import xlings.ui;
+import xlings.core.i18n;
+import xlings.platform;
+import xlings.capabilities;
+import xlings.agent;
+import xlings.agent.text_renderer;
+import xlings.interface;
+import xlings.core.subos;
+import xlings.core.xself;
+import xlings.core.xim.commands;
+import xlings.core.xvm.types;
+import xlings.core.xvm.db;
+import xlings.core.xvm.commands;
+import xlings.core.profile;
+import xlings.core.utf8;
+import xlings.cli.spec;
+import xlings.core.xim.index_cmd;
+
+namespace xlings::cli {
+
+// ─── EventStream consumer: dispatch DataEvent to ui:: functions ───
+void dispatch_data_event(const DataEvent& e) {
+    auto json = nlohmann::json::parse(e.json, nullptr, false);
+    if (json.is_discarded()) {
+        log::warn("invalid JSON in DataEvent kind={}", e.kind);
+        return;
+    }
+
+    if (e.kind == "info_panel") {
+        std::string title = json.value("title", "");
+        std::vector<ui::InfoField> fields;
+        if (json.contains("fields") && json["fields"].is_array()) {
+            for (auto& f : json["fields"]) {
+                fields.push_back({
+                    f.value("label", ""),
+                    f.value("value", ""),
+                    f.value("highlight", false),
+                    f.value("alert", false)
+                });
+            }
+        }
+        std::vector<ui::InfoField> extra;
+        if (json.contains("extra_fields") && json["extra_fields"].is_array()) {
+            for (auto& f : json["extra_fields"]) {
+                extra.push_back({
+                    f.value("label", ""),
+                    f.value("value", ""),
+                    f.value("highlight", false),
+                    f.value("alert", false)
+                });
+            }
+        }
+        ui::print_info_panel(title, fields, extra);
+    }
+    else if (e.kind == "help") {
+        std::string name = json.value("name", "");
+        std::string desc = json.value("description", "");
+        std::vector<ui::HelpArg> args;
+        if (json.contains("args") && json["args"].is_array()) {
+            for (auto& a : json["args"]) {
+                args.push_back({
+                    a.value("name", ""),
+                    a.value("desc", ""),
+                    a.value("required", false)
+                });
+            }
+        }
+        std::vector<ui::HelpOpt> opts;
+        if (json.contains("opts") && json["opts"].is_array()) {
+            for (auto& o : json["opts"]) {
+                opts.push_back({
+                    o.value("name", ""),
+                    o.value("desc", "")
+                });
+            }
+        }
+        ui::print_subcommand_help(name, desc, args, opts);
+    }
+    else if (e.kind == "tip") {
+        ui::print_tip(json.value("message", ""));
+    }
+    else if (e.kind == "styled_list") {
+        std::string title = json.value("title", "");
+        bool numbered = json.value("numbered", false);
+        std::vector<ui::ListRow> items;
+        if (json.contains("items") && json["items"].is_array()) {
+            for (auto& item : json["items"]) {
+                if (item.is_array() && item.size() >= 2) {
+                    items.push_back({
+                        item[0].get<std::string>(),
+                        item[1].get<std::string>(),
+                        item.size() >= 3 ? item[2].get<std::string>()
+                                         : std::string{},
+                    });
+                } else if (item.is_string()) {
+                    items.push_back({item.get<std::string>(), "", ""});
+                }
+            }
+        }
+        ui::print_styled_list(title, items, numbered);
+    }
+    else if (e.kind == "install_plan") {
+        std::vector<std::pair<std::string, std::string>> packages;
+        if (json.contains("packages") && json["packages"].is_array()) {
+            for (auto& p : json["packages"]) {
+                if (p.is_array() && p.size() >= 2) {
+                    packages.emplace_back(p[0].get<std::string>(), p[1].get<std::string>());
+                }
+            }
+        }
+        ui::print_install_plan(packages);
+    }
+    else if (e.kind == "install_summary") {
+        ui::print_install_summary(json.value("success", 0), json.value("failed", 0));
+    }
+    else if (e.kind == "remove_plan") {
+        ui::print_remove_plan(
+            json.value("subos", ""),
+            json.value("name", ""),
+            json.value("version", ""));
+    }
+    else if (e.kind == "remove_summary") {
+        // Tolerate the legacy "target" key (older interface clients) by
+        // falling back when name/version were not provided.
+        auto name = json.value("name", json.value("target", ""));
+        std::vector<std::string> pinnedBy;
+        if (json.contains("pinned_by") && json["pinned_by"].is_array()) {
+            for (auto& n : json["pinned_by"]) {
+                if (n.is_string()) pinnedBy.push_back(n.get<std::string>());
+            }
+        }
+        ui::print_remove_summary(
+            json.value("subos", ""),
+            name,
+            json.value("version", ""),
+            json.value("detached", false),
+            pinnedBy);
+    }
+    else if (e.kind == "subos_candidates") {
+        std::vector<std::tuple<std::string, std::string, int, bool>> entries;
+        if (json.contains("candidates") && json["candidates"].is_array()) {
+            for (auto& candidate : json["candidates"]) {
+                entries.emplace_back(
+                    candidate.value("name", ""),
+                    candidate.value("dir", ""),
+                    candidate.value("pkgCount", 0),
+                    candidate.value("active", false));
+            }
+        }
+        if (json.value("auto_selected", false)) {
+            ui::print_subos_resolved(
+                json.value("query", ""), json.value("selected", ""));
+        } else {
+            ui::print_subos_list(entries);
+            auto hint = json.value("hint", "");
+            if (!hint.empty()) ui::print_tip(hint);
+        }
+    }
+    else if (e.kind == "subos_list") {
+        std::vector<std::tuple<std::string, std::string, int, bool>> entries;
+        if (json.contains("entries") && json["entries"].is_array()) {
+            for (auto& e : json["entries"]) {
+                entries.emplace_back(
+                    e.value("name", ""),
+                    e.value("dir", ""),
+                    e.value("pkgCount", 0),
+                    e.value("active", false)
+                );
+            }
+        }
+        ui::print_subos_list(entries);
+    }
+    else if (e.kind == "subos_created") {
+        ui::print_subos_created(
+            json.value("name", ""), json.value("dir", ""));
+    }
+    else if (e.kind == "subos_switched") {
+        ui::print_subos_switched(
+            json.value("name", ""), json.value("dir", ""));
+    }
+    else if (e.kind == "subos_entering") {
+        ui::print_subos_entering(json.value("name", ""));
+    }
+    else if (e.kind == "subos_already_in") {
+        ui::print_subos_already_in(json.value("name", ""));
+    }
+    else if (e.kind == "subos_nesting") {
+        ui::print_subos_nesting(
+            json.value("from", ""), json.value("to", ""));
+    }
+    else if (e.kind == "subos_removed") {
+        ui::print_subos_removed(json.value("name", ""));
+    }
+    else if (e.kind == "search_results") {
+        std::vector<std::pair<std::string, std::string>> results;
+        if (json.contains("results") && json["results"].is_array()) {
+            for (auto& r : json["results"]) {
+                if (r.is_array() && r.size() >= 2) {
+                    results.emplace_back(r[0].get<std::string>(), r[1].get<std::string>());
+                }
+            }
+        }
+        ui::print_search_results(results);
+    }
+    else if (e.kind == "table") {
+        std::vector<std::string> headers;
+        if (json.contains("headers") && json["headers"].is_array()) {
+            for (auto& h : json["headers"]) {
+                headers.push_back(h.get<std::string>());
+            }
+        }
+        std::vector<std::vector<std::string>> rows;
+        if (json.contains("rows") && json["rows"].is_array()) {
+            for (auto& r : json["rows"]) {
+                std::vector<std::string> row;
+                if (r.is_array()) {
+                    for (auto& c : r) row.push_back(c.get<std::string>());
+                }
+                rows.push_back(std::move(row));
+            }
+        }
+        ui::print_table(headers, rows);
+    }
+    else if (e.kind == "download_progress") {
+        // Skip CLI rendering in TUI mode (agent TUI handles progress separately)
+        if (platform::is_tui_mode()) return;
+        auto nameWidth = json.value("nameWidth", std::size_t{20});
+        auto elapsedSec = json.value("elapsedSec", 0.0);
+        auto sizesReady = json.value("sizesReady", false);
+        std::vector<ui::DownloadProgressEntry> entries;
+        if (json.contains("files") && json["files"].is_array()) {
+            for (auto& f : json["files"]) {
+                entries.push_back({
+                    f.value("name", std::string{}),
+                    f.value("totalBytes", 0.0),
+                    f.value("downloadedBytes", 0.0),
+                    f.value("started", false),
+                    f.value("finished", false),
+                    f.value("success", false)
+                });
+            }
+        }
+        auto prevLines = json.value("prevLines", 0);
+        ui::render_download_progress(entries, nameWidth, elapsedSec, sizesReady, prevLines);
+    }
+    else {
+        log::debug("unhandled DataEvent kind: {}", e.kind);
+    }
+}
+
+// ─── EventStream consumer: handle PromptEvent via ui:: interactive functions ───
+void handle_prompt(EventStream& stream, const PromptEvent& p) {
+    // Binary yes/no → confirm dialog
+    if (p.options.size() == 2 && p.options[0] == "y" && p.options[1] == "n") {
+        bool defaultYes = (p.defaultValue == "y");
+        bool result = ui::confirm(p.question, defaultYes);
+        stream.respond(p.id, result ? "y" : "n");
+        return;
+    }
+
+    // Multiple options → package selector
+    if (!p.options.empty()) {
+        std::vector<std::pair<std::string, std::string>> items;
+        for (auto& opt : p.options) {
+            items.emplace_back(opt, "");
+        }
+        auto result = ui::select_package(items);
+        stream.respond(p.id, result.value_or(""));
+        return;
+    }
+
+    // Free input — use default
+    stream.respond(p.id, p.defaultValue);
+}
+
+// Parse legacy config.xlings (Lua format) and extract workspace from the xim table.
+// Returns empty workspace if file doesn't exist or has no xim/xlings_deps.
+xvm::Workspace parse_legacy_config_(const std::filesystem::path& configFile) {
+    namespace fs = std::filesystem;
+    xvm::Workspace workspace;
+
+    if (!fs::exists(configFile)) return workspace;
+
+    auto* L = lua::L_newstate();
+    if (!L) return workspace;
+    lua::L_openlibs(L);
+
+    // Provide a no-op is_host() so Lua files with conditionals don't error
+    lua::L_dostring(L, "function is_host() return false end");
+
+    if (lua::L_dofile(L, configFile.string().c_str()) != lua::OK) {
+        log::warn("failed to parse legacy config: {}", lua::tostring(L, -1));
+        lua::close(L);
+        return workspace;
+    }
+
+    // Read xim table: { pkg_name = "version", ... }
+    lua::getglobal(L, "xim");
+    if (lua::type(L, -1) == lua::TTABLE) {
+        lua::pushnil(L);
+        while (lua::next(L, -2)) {
+            if (lua::type(L, -2) == lua::TSTRING) {
+                std::string key = lua::tostring(L, -2);
+                // Skip non-package entries
+                if (key != "xppcmds") {
+                    std::string version;
+                    if (lua::type(L, -1) == lua::TSTRING) {
+                        version = lua::tostring(L, -1);
+                    }
+                    workspace[key] = version;
+                }
+            }
+            lua::pop(L, 1); // pop value, keep key for next iteration
+        }
+    }
+    lua::pop(L, 1); // pop xim
+
+    // Fallback: older format uses xlings_deps = "cpp, vscode, mdbook"
+    if (workspace.empty()) {
+        lua::getglobal(L, "xlings_deps");
+        if (lua::type(L, -1) == lua::TSTRING) {
+            std::string deps = lua::tostring(L, -1);
+            std::istringstream ss(deps);
+            std::string token;
+            while (std::getline(ss, token, ',')) {
+                auto start = token.find_first_not_of(" \t");
+                auto end = token.find_last_not_of(" \t");
+                if (start != std::string::npos) {
+                    workspace[token.substr(start, end - start + 1)] = "";
+                }
+            }
+        }
+        lua::pop(L, 1);
+    }
+
+    lua::close(L);
+    return workspace;
+}
+
+// Generate .xlings.json from a workspace map
+void generate_xlings_json_(const std::filesystem::path& dir, const xvm::Workspace& workspace) {
+    nlohmann::json ws;
+    for (auto& [name, version] : workspace) {
+        ws[name] = version;
+    }
+    nlohmann::json root;
+    root["workspace"] = ws;
+    auto outPath = dir / ".xlings.json";
+    platform::write_string_to_file(outPath.string(), root.dump(2));
+}
+
+// Normalize a target-spec from positional args for the single-target
+// commands (remove/update/info — `use` has its own list-versions
+// semantic and parses inline).
+//
+// Accepted forms (equivalent):
+//   1 positional, contains '@'   →  passed as-is  (e.g. "node@22.17.1")
+//   1 positional, no '@'         →  passed as-is  (bare name; the cmd
+//                                    decides what to do — typically
+//                                    "use the active version")
+//   2 positionals                →  folded into "<arg0>@<arg1>"
+//
+// Rejected:
+//   3+ positionals
+//   2 positionals where arg0 already contains '@' (ambiguous)
+//
+// Returns false (with a logged error) on bad input. Caller should
+// `return 1` on false.
+bool parse_target_spec_(const mcpplibs::cmdline::ParsedArgs& args,
+                        std::string& out) {
+    auto n = args.positional_count();
+    if (n == 0) {
+        log::error("missing target argument");
+        return false;
+    }
+    if (n > 2) {
+        log::error("too many positional arguments (expected 1 or 2, got {})", n);
+        log::error("  hint: use `<name>@<version>` or `<name> <version>`");
+        return false;
+    }
+    auto first = std::string(args.positional(0));
+    if (n == 1) {
+        out = std::move(first);
+        return true;
+    }
+    // n == 2: "<name> <version>" form. The first arg must be a bare
+    // name — if it already includes '@', the user gave us two version
+    // hints and we can't reconcile.
+    if (first.find('@') != std::string::npos) {
+        auto bare = first.substr(0, first.find('@'));
+        log::error("ambiguous target: '{}' already includes @<version>, "
+                   "but a separate version '{}' was also given",
+                   first, std::string(args.positional(1)));
+        log::error("  hint: pick one of `{}` or `{} {}`",
+                   first, bare, std::string(args.positional(1)));
+        return false;
+    }
+    out = first + "@" + std::string(args.positional(1));
+    return true;
+}
+
+// Install packages from project .xlings.json workspace
+int install_from_project_config_(EventStream& stream) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    auto cwd = fs::current_path(ec);
+    if (ec) return 1;
+    auto homeDir = Config::paths().homeDir;
+
+    // Walk up from cwd looking for .xlings.json with workspace
+    fs::path cur = cwd;
+    while (!cur.empty()) {
+        auto curNorm = fs::weakly_canonical(cur, ec);
+        auto homeNorm = fs::weakly_canonical(homeDir, ec);
+        if (curNorm == homeNorm) {
+            auto parent = cur.parent_path();
+            if (parent == cur) break;
+            cur = parent;
+            continue;
+        }
+
+        // Try .xlings.json first
+        auto cfg = cur / ".xlings.json";
+        if (fs::exists(cfg, ec) && fs::is_regular_file(cfg, ec)) {
+            try {
+                auto content = platform::read_file_to_string(cfg.string());
+                auto json = nlohmann::json::parse(content, nullptr, false);
+                if (!json.is_discarded() && json.contains("workspace") && json["workspace"].is_object()) {
+                    auto workspace = xvm::workspace_from_json(json["workspace"]);
+                    auto targets = Config::workspace_install_targets(workspace);
+                    if (!targets.empty()) {
+                        // Project-config install: the workspace file declares
+                        // which versions should be active in this subos, so
+                        // force-activate to keep workspace state in sync with
+                        // the config.
+                        return xim::cmd_install(targets, true, false, stream,
+                                                /*forceGlobal=*/false,
+                                                /*cancel=*/nullptr,
+                                                /*dryRun=*/false,
+                                                /*useAfterInstall=*/true);
+                    }
+                }
+            } catch (...) {
+                log::error("failed to parse {}", cfg.string());
+                return 1;
+            }
+        }
+
+        // Fallback: try legacy config.xlings (Lua format)
+        auto legacyCfg = cur / "config.xlings";
+        if (fs::exists(legacyCfg, ec) && fs::is_regular_file(legacyCfg, ec)) {
+            auto workspace = parse_legacy_config_(legacyCfg);
+            if (!workspace.empty()) {
+                log::println("detected legacy config: {}", legacyCfg.string());
+                log::println("generating .xlings.json from config.xlings ...");
+                generate_xlings_json_(cur, workspace);
+                log::println("generated: {}", (cur / ".xlings.json").string());
+                auto targets = Config::workspace_install_targets(workspace);
+                return xim::cmd_install(targets, true, false, stream,
+                                        /*forceGlobal=*/false,
+                                        /*cancel=*/nullptr,
+                                        /*dryRun=*/false,
+                                        /*useAfterInstall=*/true);
+            }
+        }
+
+        auto parent = cur.parent_path();
+        if (parent == cur) break;
+        cur = parent;
+    }
+
+    ui::print_tip("create <project>/.xlings.json with workspace, or run `xlings install <package>`");
+    return 0;
+}
+
+void apply_global_opts_(const mcpplibs::cmdline::ParsedArgs& args) {
+    if (args.is_flag_set("verbose")) log::set_level(log::Level::Debug);
+    if (args.is_flag_set("quiet")) log::set_level(log::Level::Error);
+}
+
+// config subcommand handler
+int cmd_config_(const mcpplibs::cmdline::ParsedArgs& args, EventStream& stream) {
+    // Edits are collected rather than applied, then replayed against the
+    // document `update_home_config` re-reads under the state lock. Applying
+    // them to a copy read here instead would write back every *other* key as
+    // it looked before an install that finished in the meantime -- see
+    // core/home_config.cppm. Validation and the user-facing logging stay out
+    // here so a rejected argument never reaches the lock.
+    std::vector<std::function<void(nlohmann::json&)>> edits;
+
+    // --lang
+    if (auto lang = args.value("lang")) {
+        std::string value(*lang);
+        edits.push_back([value](nlohmann::json& j) { j["lang"] = value; });
+        log::println("lang = {}", value);
+    }
+
+    // --mirror
+    if (auto mirror = args.value("mirror")) {
+        std::string value(*mirror);
+        edits.push_back([value](nlohmann::json& j) { j["mirror"] = value; });
+        log::println("mirror = {}", value);
+    }
+
+    auto commit_edits = [&]() -> bool {
+        if (edits.empty()) return true;
+        auto committed = update_home_config(
+            Config::paths().homeDir, [&](nlohmann::json& j) {
+                for (const auto& edit : edits) edit(j);
+                return true;
+            });
+        if (!committed) {
+            log::error("{}", committed.error());
+            return false;
+        }
+        return true;
+    };
+
+    // --add-xpkg
+    if (auto xpkg = args.value("add-xpkg")) {
+        if (!commit_edits()) return 1;
+        return xim::cmd_add_xpkg(std::string(*xpkg), stream);
+    }
+
+    // --index-repo  namespace:https://....git
+    if (auto repo = args.value("index-repo")) {
+        std::string val(*repo);
+        auto colonPos = val.find(':');
+        // Find the colon that separates name from URL (skip scheme "https://")
+        // Format: name:url  e.g. myrepo:https://github.com/user/repo.git
+        if (colonPos == std::string::npos || colonPos == 0) {
+            log::error("invalid format, expected: <namespace>:<url>");
+            log::error("  e.g. myrepo:https://github.com/user/repo.git");
+            return 1;
+        }
+        auto name = val.substr(0, colonPos);
+        auto url = val.substr(colonPos + 1);
+        if (url.empty()) {
+            log::error("invalid format, expected: <namespace>:<url>");
+            return 1;
+        }
+
+        // Upsert against the freshly-read document: a repo another process
+        // added since we started must be updated in place, not duplicated.
+        edits.push_back([name, url](nlohmann::json& json) {
+            if (!json.contains("index_repos")
+                || !json["index_repos"].is_array()) {
+                json["index_repos"] = nlohmann::json::array();
+            }
+            for (auto& entry : json["index_repos"]) {
+                if (entry.is_object() && entry.contains("name") &&
+                    entry["name"].get<std::string>() == name) {
+                    entry["url"] = url;
+                    return;
+                }
+            }
+            nlohmann::json entry;
+            entry["name"] = name;
+            entry["url"] = url;
+            json["index_repos"].push_back(entry);
+        });
+        log::println("index-repo {} = {}", name, url);
+    }
+
+    if (!edits.empty()) {
+        return commit_edits() ? 0 : 1;
+    }
+
+    // No options: show current config via TUI info panel
+    auto& p = Config::paths();
+    std::vector<ui::InfoField> fields;
+    fields.push_back({"XLINGS_HOME", p.homeDir.string()});
+    fields.push_back({"XLINGS_DATA", Config::display_path(p.dataDir)});
+    fields.push_back({"XLINGS_SUBOS", Config::display_path(p.subosDir)});
+    fields.push_back({"active subos", p.activeSubos, true});
+    fields.push_back({"bin", Config::display_path(p.binDir)});
+
+    auto mirror = Config::mirror();
+    if (!mirror.empty()) fields.push_back({"mirror", mirror});
+    auto lang = Config::lang();
+    if (!lang.empty()) fields.push_back({"lang", lang});
+
+    auto& repos = Config::global_index_repos();
+    for (auto& repo : repos) {
+        fields.push_back({"index-repo", repo.name + " : " + repo.url});
+    }
+
+    if (Config::has_project_config()) {
+        fields.push_back({"project data", Config::project_data_dir().string()});
+        auto& projectRepos = Config::project_index_repos();
+        for (auto& repo : projectRepos) {
+            fields.push_back({"project repo", repo.name + " : " + repo.url});
+        }
+    }
+
+    ui::print_info_panel("xlings config", fields);
+    return 0;
+}
+
+// `xlings profile list|commit|rollback` — generations of the active subos.
+//
+// The module had commit / list_generations / rollback and no way to reach
+// any of them: four exported functions, zero callers, no subcommand. So the
+// feature read as working and was not, and `rollback` in particular wrote a
+// YAML file nothing consulted.
+//
+// Commit is explicit rather than automatic. Recording a generation on every
+// install would change the hot path for everyone, and which mutations
+// deserve a generation is a product decision, not one to make on the way
+// past. Explicit commits make the feature usable now without deciding it.
+int run_profile_(int argc, char* argv[], EventStream& stream) {
+    const std::string action = (argc >= 3) ? argv[2] : "list";
+    auto& p = Config::paths();
+    const auto envDir = p.subosDir;
+
+    if (action == "list") {
+        auto gens = profile::list_generations(envDir);
+        auto current = profile::load_current(envDir);
+        if (gens.empty()) {
+            std::println("no generations yet — record one with "
+                         "`xlings profile commit [reason]`");
+            return 0;
+        }
+        for (const auto& gen : gens) {
+            std::println("{}{:>4}  {}  {} package(s)  {}",
+                         gen.number == current.number ? "*" : " ",
+                         gen.number, gen.created, gen.packages.size(),
+                         gen.reason);
+        }
+        return 0;
+    }
+
+    if (action == "commit") {
+        const std::string reason = (argc >= 4) ? argv[3] : "manual";
+        std::map<std::string, std::string> packages;
+        for (const auto& [target, version] : Config::effective_workspace()) {
+            packages[target] = version;
+        }
+        profile::commit(envDir, packages, reason);
+        auto current = profile::load_current(envDir);
+        std::println("[xlings:profile] recorded generation {} ({} package(s))",
+                     current.number, packages.size());
+        return 0;
+    }
+
+    if (action == "rollback") {
+        if (argc < 4) {
+            ui::print_usage("xlings profile rollback <generation>");
+            return 1;
+        }
+        int target = 0;
+        try { target = std::stoi(argv[3]); }
+        catch (...) {
+            log::error("not a generation number: {}", argv[3]);
+            return 1;
+        }
+        auto packages = profile::rollback(envDir, target);
+        if (!packages) {
+            log::error("[xlings:profile] {}", packages.error());
+            return 1;
+        }
+        // Apply through the same path `xlings use` takes. Recording the
+        // selection is not rolling back: the previous implementation stopped
+        // at the record and left every version where it was.
+        int failed = 0;
+        for (const auto& [name, version] : *packages) {
+            if (xvm::cmd_use(name, version, stream) != 0) ++failed;
+        }
+        std::println("[xlings:profile] rolled back to generation {}", target);
+        return failed == 0 ? 0 : 1;
+    }
+
+    ui::print_usage("xlings profile [list | commit [reason] | rollback <n>]");
+    return action == "-h" || action == "--help" ? 0 : 1;
+}
+
+int run(int argc, char* argv[]) {
+    if (argc == 2
+        && std::string_view{argv[1]} == "--command-reference-json") {
+        std::println("{}", spec::reference_json().dump());
+        return 0;
+    }
+    using namespace mcpplibs;
+
+    // Bare `xlings` (no args) used to silently exit 0 because the
+    // help branch below requires fargc >= 2 (i.e. at least one arg).
+    // Treat it as `xlings --help` instead — much friendlier for first
+    // contact and matches what most modern package managers do.
+    if (argc <= 1) {
+        ui::print_help(Info::VERSION);
+        return 0;
+    }
+
+    // Create EventStream for core→UI decoupling
+    EventStream stream;
+    // Default TUI consumer for CLI mode (will be toggled in agent mode).
+    // ErrorEvent/LogEvent surfacing keeps capability-emitted errors visible
+    // to CLI users — without it, anything that emits an ErrorEvent (subos
+    // operations, repo helpers) would silently fail in CLI mode.
+    int tui_listener = stream.on_event([&stream](const Event& e) {
+        if (auto* d = std::get_if<DataEvent>(&e)) {
+            dispatch_data_event(*d);
+        }
+        else if (auto* p = std::get_if<PromptEvent>(&e)) {
+            handle_prompt(stream, *p);
+        }
+        else if (auto* er = std::get_if<ErrorEvent>(&e)) {
+            // Wrapped here, not at the call sites. An ErrorEvent's message is
+            // composed by whichever command raised it, and some of them carry
+            // a list of candidates or a full command line -- the width
+            // contract has to be a property of the renderer, or every command
+            // re-derives it and one of them gets it wrong. log:: itself
+            // cannot do this: core does not depend on ui.
+            auto emit = [](std::string_view text, std::string_view indent) {
+                const int prefix = 8  // "[error] "
+                    + ui::layout::display_width(indent);
+                const int width = std::max(1,
+                    ui::layout::fit_width(
+                        prefix + ui::layout::display_width(text)) - prefix);
+                for (auto& line : ui::layout::wrap_to_width(text, width)) {
+                    log::error("{}{}", indent, line);
+                }
+            };
+            emit(er->message, "");
+            if (!er->hint.empty()) emit(er->hint, "  ");
+        }
+        else if (auto* l = std::get_if<LogEvent>(&e)) {
+            switch (l->level) {
+                case LogLevel::debug: log::debug("{}", l->message); break;
+                case LogLevel::info:  log::info("{}",  l->message); break;
+                case LogLevel::warn:  log::warn("{}",  l->message); break;
+                case LogLevel::error: log::error("{}", l->message); break;
+            }
+        }
+    });
+
+    // Build Capability Registry (for Agent/MCP use — CLI keeps direct dispatch)
+    auto registry = capabilities::build_registry();
+
+    // Scan for global flags (--verbose, -v, --quiet, -q, --agent) anywhere
+    // in argv so they work regardless of position.
+    bool agent_mode = false;
+    for (int i = 1; i < argc; ++i) {
+        std::string_view a { argv[i] };
+        if (a == "--verbose" || a == "-v") log::set_level(log::Level::Debug);
+        else if (a == "--quiet" || a == "-q") log::set_level(log::Level::Error);
+        else if (a == "--agent") agent_mode = true;
+    }
+
+    // --agent: replace TUI listener with plain-text renderer, disable colors.
+    // Unlike interface mode, we do NOT set tui_mode(true) — log output should
+    // still reach the terminal, just without ANSI decoration.
+    if (agent_mode) {
+        stream.set_enabled(tui_listener, false);
+        log::enable_color(false);
+        // One switch for every writer, not just log's own prefixes.
+        ui::layout::set_plain(true);
+        stream.on_event([&stream](const Event& e) {
+            if (auto* d = std::get_if<DataEvent>(&e)) {
+                agent::render_data_event(*d);
+            }
+            else if (auto* p = std::get_if<PromptEvent>(&e)) {
+                // In agent mode, auto-respond with default (use --yes for confirms)
+                stream.respond(p->id, p->defaultValue);
+            }
+            else if (auto* er = std::get_if<ErrorEvent>(&e)) {
+                std::println(stderr, "Error: {}", er->message);
+                if (!er->hint.empty()) std::println(stderr, "Hint: {}", er->hint);
+            }
+            else if (auto* l = std::get_if<LogEvent>(&e)) {
+                if (l->level == LogLevel::error)
+                    std::println(stderr, "{}", l->message);
+                else if (l->level == LogLevel::warn)
+                    std::println(stderr, "{}", l->message);
+                else
+                    std::println("{}", l->message);
+            }
+        });
+    }
+
+    // Build filtered argv without global flags for positional-arg handlers
+    // (subos, self, script parse argv[2]/argv[3] positionally)
+    std::vector<char*> fargv;
+    fargv.push_back(argv[0]);
+    for (int i = 1; i < argc; ++i) {
+        std::string_view a { argv[i] };
+        if (a == "--verbose" || a == "-v" || a == "--quiet" || a == "-q"
+            || a == "--agent") continue;
+        fargv.push_back(argv[i]);
+    }
+    int fargc = static_cast<int>(fargv.size());
+
+    // Find the first non-flag argument as the command name
+    std::string cmd;
+    for (int i = 1; i < fargc; ++i) {
+        std::string_view a { fargv[i] };
+        if (!a.starts_with("-")) { cmd = std::string(a); break; }
+    }
+
+    // Special: subos, self, script need raw argc/argv
+    if (fargc >= 2) {
+        // Handle -h/--help/--version before cmdline library to avoid
+        // std::format width-specifier crash in GCC 15 C++23 modules.
+        if (cmd == "-h" || cmd == "--help" || cmd.empty()) {
+            if (cmd.empty()) {
+                // Only flags, no command — check if -h was requested
+                for (int i = 1; i < fargc; ++i) {
+                    std::string_view a { fargv[i] };
+                    if (a == "-h" || a == "--help") { ui::print_help(Info::VERSION); return 0; }
+                    if (a == "--version") { std::println("xlings {}", Info::VERSION); return 0; }
+                }
+            }
+            ui::print_help(Info::VERSION);
+            return 0;
+        }
+        if (cmd == "--version") {
+            std::println("xlings {}", Info::VERSION);
+            return 0;
+        }
+
+        // agent — dispatched before the generic help interception so it keeps
+        // handling its own -h as plain text. `xlings agent -h` has to print
+        // the skill overview (the list of what is installed and readable),
+        // and the boxed subcommand help rendered from the spec neither is
+        // plain text nor names a single skill. The whole point of this command
+        // family is that a machine reads its output.
+        if (cmd == "agent") return agent::run(fargc, fargv.data());
+
+        // Intercept subcommand help: xlings <cmd> -h/--help
+        bool wantsHelp = false;
+        for (int i = 2; i < fargc; ++i) {
+            std::string_view a { fargv[i] };
+            if (a == "-h" || a == "--help") { wantsHelp = true; break; }
+        }
+        if (wantsHelp) {
+            using A = ui::HelpArg;
+            using O = ui::HelpOpt;
+
+            std::vector<std::string_view> commandPath;
+            commandPath.push_back(cmd);
+            if (fargc > 2) {
+                const std::string_view nested{fargv[2]};
+                if (!nested.starts_with('-')) {
+                    auto candidate = commandPath;
+                    candidate.push_back(nested);
+                    if (spec::find(candidate)) commandPath = std::move(candidate);
+                }
+            }
+            if (const auto* command = spec::find(commandPath)) {
+                std::vector<A> arguments;
+                std::vector<O> options;
+                std::vector<O> children;
+                for (const auto& argument : command->arguments) {
+                    arguments.push_back({argument.name, argument.description,
+                                         argument.required});
+                }
+                for (const auto& option : command->options) {
+                    options.push_back({option.syntax, option.description});
+                }
+                for (const auto& child : command->children) {
+                    children.push_back({child.name, child.description});
+                }
+                ui::print_subcommand_help(command->name, command->description,
+                                          arguments, options, children);
+                return 0;
+            }
+
+        }
+
+        // index — positional dispatch like subos/self, so it validates the
+        // same way and never reaches the cmdline builder's package semantics.
+        if (cmd == "index") {
+            const std::array<std::string_view, 1> path{cmd};
+            if (const auto* command = spec::find(path)) {
+                std::vector<std::string_view> manualArgs;
+                for (int i = 2; i < fargc; ++i) manualArgs.emplace_back(fargv[i]);
+                if (auto validated = spec::validate_manual_argv(*command, manualArgs);
+                    !validated) {
+                    log::error("{}", validated.error().message);
+                    return 2;
+                }
+            }
+            std::string sub = fargc > 2 ? fargv[2] : "list";
+            if (sub == "ls") sub = "list";
+            if (sub == "list") {
+                std::string filter;
+                bool asJson = false;
+                for (int i = 3; i < fargc; ++i) {
+                    std::string_view a{fargv[i]};
+                    if (a == "--json") asJson = true;
+                    else if (!a.starts_with('-')) filter = std::string(a);
+                }
+                return xim::cmd_index_list(filter, asJson, stream);
+            }
+            if (sub == "use") {
+                return xim::cmd_index_use(fargc > 3 ? fargv[3] : "",
+                                          fargc > 4 ? fargv[4] : "", stream);
+            }
+            log::error("unknown subcommand for `xlings index`: {}", sub);
+            return 2;
+        }
+
+        if (cmd == "subos" || cmd == "self" || cmd == "profile") {
+            const std::array<std::string_view, 1> path{cmd};
+            if (const auto* command = spec::find(path)) {
+                std::vector<std::string_view> manualArgs;
+                for (int i = 2; i < fargc; ++i) manualArgs.emplace_back(fargv[i]);
+                if (auto validated = spec::validate_manual_argv(
+                        *command, manualArgs); !validated) {
+                    log::error("{}", validated.error().message);
+                    return 2;
+                }
+            }
+        }
+
+        // Detect unknown commands early — show TUI error + help
+        {
+            const bool known = std::ranges::any_of(spec::root().children,
+                [&](const auto& command) {
+                    return command.name == cmd
+                        || std::ranges::find(command.aliases, cmd)
+                            != command.aliases.end();
+                });
+            if (!known && !cmd.starts_with("-")) {
+                log::error("unknown command: {}", cmd);
+                return 1;
+            }
+        }
+
+        if (cmd == "subos") return subos::run(fargc, fargv.data(), stream);
+        if (cmd == "self") return xself::run(fargc, fargv.data(), stream);
+        if (cmd == "profile") return run_profile_(fargc, fargv.data(), stream);
+        if (cmd == "script") {
+            if (fargc < 3) {
+                ui::print_usage("xlings script <script-file> [args...]");
+                return 1;
+            }
+            namespace fs = std::filesystem;
+            fs::path scriptFile = fargv[2];
+            auto execResult = mcpplibs::xpkg::create_executor(scriptFile);
+            if (!execResult) {
+                log::error("failed to load script: {}", execResult.error());
+                return 1;
+            }
+            mcpplibs::xpkg::ExecutionContext ctx;
+            ctx.platform = std::string(platform::OS_NAME);
+            ctx.bin_dir = Config::paths().binDir;
+            ctx.subos_sysrootdir = Config::paths().subosDir.string();
+            ctx.run_dir = fs::current_path();
+            ctx.xpkg_dir = Config::paths().dataDir / "xpkgs";
+            for (int i = 3; i < fargc; ++i) {
+                ctx.args.emplace_back(fargv[i]);
+            }
+            auto result = execResult->run_script(ctx);
+            if (!result.success) {
+                log::error("script error: {}", result.error);
+                return 1;
+            }
+            return 0;
+        }
+    }
+
+    // cmdline::App stores actions as std::function<void(ParsedArgs&)>, so the
+    // int returns from each action lambda below are silently discarded by the
+    // library on its way through std::function. Capture the lambda's intended
+    // exit code into this shared int and have run() return it after app.run()
+    // completes. Without this every cmd_* return value (1 for failures, 2 for
+    // refused-by-policy, ...) is squashed to 0 — so e.g. CI scripts that branch
+    // on `xlings install` exit code never see install failures.
+    int action_rc = 0;
+    auto wrap_rc = [&action_rc](auto&& fn) {
+        return [fn = std::forward<decltype(fn)>(fn), &action_rc]
+               (const cmdline::ParsedArgs& args) {
+            action_rc = fn(args);
+        };
+    };
+
+    auto app = cmdline::App("xlings")
+        .version(std::string(Info::VERSION))
+        .author("d2learn community")
+        .description("A modern package manager and development environment tool")
+
+        // Global options
+        .option("yes").short_name('y').help("Skip confirmation prompts").global()
+        .option("verbose").short_name('v').help("Enable verbose output").global()
+        .option("quiet").short_name('q').help("Suppress non-essential output").global()
+        .option("agent").help("Plain-text output without TUI formatting (for LLM agents)").global()
+
+        // install
+        .subcommand("install")
+            .description("Install packages (e.g. xlings install gcc@15 node)")
+            .option(cmdline::Option("global").short_name('g').help("Install to global scope (not project-local subos)"))
+            .option(cmdline::Option("use").short_name('u').help("Activate the installed version even if another version is currently active"))
+            .arg("packages").help("Package names with optional version")
+            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
+                apply_global_opts_(args);
+                std::vector<std::string> targets;
+                for (std::size_t i = 0; i < args.positional_count(); ++i) {
+                    auto t = args.positional(i);
+                    if (!t.empty()) targets.emplace_back(t);
+                }
+                // Friendly hint: `install` treats every positional as an
+                // independent target (multi-package semantic). If the user
+                // wrote two args where the first looks like a bare package
+                // name and the second looks version-like, they probably
+                // meant the combined `name@version` form (single package),
+                // which is the convention the rest of the CLI follows.
+                if (targets.size() == 2
+                    && targets[0].find('@') == std::string::npos
+                    && !targets[1].empty()
+                    && (std::isdigit(static_cast<unsigned char>(targets[1][0]))
+                        || targets[1] == "latest"))
+                {
+                    log::warn("install: each positional is a separate package; "
+                              "did you mean `{}@{}` (single package) instead "
+                              "of two packages '{}' and '{}'?",
+                              targets[0], targets[1], targets[0], targets[1]);
+                }
+
+                if (targets.empty()) return install_from_project_config_(stream);
+
+                bool yes = args.is_flag_set("yes");
+                bool global = args.is_flag_set("global");
+                bool useAfter = args.is_flag_set("use");
+                return xim::cmd_install(targets, yes, false, stream, global,
+                                        /*cancel=*/nullptr, /*dryRun=*/false,
+                                        useAfter);
+            }))
+
+        // remove
+        // `-g` mirrors install's. Without it, a package installed with
+        // `install -g` from inside a project could not be removed from inside
+        // that project at all: remove resolved the project subos, found the
+        // package registered in the home's, and there was no way to say
+        // otherwise. Scope has to be expressible on both halves of a
+        // reversible pair, or the pair is not reversible.
+        .subcommand("remove")
+            .description("Remove a package")
+            .option(cmdline::Option("global").short_name('g').help("Act on the global scope (not the project-local subos)"))
+            .option(cmdline::Option("force").help("Remove even if installed packages depend on it"))
+            .arg("package").required().help("Package to remove (name or name@ver)")
+            .arg("version").help("Optional version (alternative to name@ver form)")
+            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
+                apply_global_opts_(args);
+                if (args.is_flag_set("global")) {
+                    Config::set_force_global_scope(true);
+                }
+                std::string target;
+                if (!parse_target_spec_(args, target)) return 1;
+                bool yes = args.is_flag_set("yes");
+                // Separate from `yes`, deliberately. `-y` says "do not ask me",
+                // which is a statement about prompting; breaking a dependency
+                // link is a different decision and a scripted `remove -y`
+                // should still be stopped by it.
+                bool force = args.is_flag_set("force");
+                return xim::cmd_remove(target, yes, stream, force);
+            }))
+
+        // update
+        .subcommand("update")
+            .description("Update package index or a specific package")
+            .arg("package").help("Package to update (omit for index only)")
+            .arg("version").help("Optional version (alternative to name@ver form)")
+            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
+                apply_global_opts_(args);
+                std::string target;
+                if (args.positional_count() > 0) {
+                    if (!parse_target_spec_(args, target)) return 1;
+                }
+                bool yes = args.is_flag_set("yes");
+                return xim::cmd_update(target, yes, stream);
+            }))
+
+        // search
+        .subcommand("search")
+            .description("Search for packages")
+            .arg("keyword").required().help("Search keyword")
+            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
+                apply_global_opts_(args);
+                return xim::cmd_search(std::string(args.positional(0)), stream);
+            }))
+
+        // list
+        .subcommand("list")
+            .description("List installed packages")
+            .option(cmdline::Option("all").short_name('a').help("Show packages across all subos (default: current subos only)"))
+            .arg("filter").help("Filter pattern")
+            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
+                apply_global_opts_(args);
+                std::string filter;
+                if (args.positional_count() > 0)
+                    filter = std::string(args.positional(0));
+                bool show_all = args.is_flag_set("all");
+                return xim::cmd_list(filter, stream, show_all);
+            }))
+
+        // info
+        .subcommand("info")
+            .description("Show package information")
+            .option(cmdline::Option("all-versions").help("Show every available version"))
+            .arg("package").required().help("Package name (or name@ver)")
+            .arg("version").help("Optional version (alternative to name@ver form)")
+            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
+                apply_global_opts_(args);
+                std::string target;
+                if (!parse_target_spec_(args, target)) return 1;
+                return xim::cmd_info(target, stream,
+                                     args.is_flag_set("all-versions"));
+            }))
+
+        // why — the resolution record, read back
+        .subcommand("why")
+            .description("Show why a dependency resolved to the version it did")
+            .arg("package").required().help("Installed package name")
+            .arg("dep").help("Optional dependency name to filter by")
+            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
+                apply_global_opts_(args);
+                return xim::cmd_why(args.value("package").value_or(""),
+                                    args.value("dep").value_or(""), stream);
+            }))
+
+        // use — accepts both `<name> <ver>` (legacy form) and `<name>@<ver>`
+        // (one-shot form, matching install/remove). Bare `<name>` switches
+        // when exactly one version is installed and lists them (exit 0) when
+        // several are, rather than blocking on a picker — see
+        // xvm::cmd_use_by_name. `--all` widens the candidate set to the
+        // global view (every version every subos has ever installed).
+        .subcommand("use")
+            .description("Switch tool version")
+            .option(cmdline::Option("all").short_name('a').help("Show versions across all subos (default: current subos only)"))
+            .option(cmdline::Option("strict").help("Refuse the switch if any program of the current release has no version in the new one"))
+            .arg("target").required().help("Tool name (or name@ver one-shot)")
+            .arg("version").help("Version to switch to (omit to list installed versions)")
+            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
+                apply_global_opts_(args);
+                auto n = args.positional_count();
+                if (n == 0) {
+                    log::error("missing target argument");
+                    return 1;
+                }
+                if (n > 2) {
+                    log::error("too many positional arguments (expected 1 or 2, got {})", n);
+                    log::error("  hint: use `<name>@<version>` or `<name> <version>`");
+                    return 1;
+                }
+                bool show_all = args.is_flag_set("all");
+                bool strict = args.is_flag_set("strict");
+                auto first = std::string(args.positional(0));
+                if (n == 1) {
+                    auto at = first.find('@');
+                    if (at == std::string::npos)
+                        return xvm::cmd_use_by_name(first, stream, show_all,
+                                                    strict);
+                    return xvm::cmd_use(first.substr(0, at),
+                                        first.substr(at + 1), stream, strict);
+                }
+                // n == 2: must be `<name> <version>`
+                if (first.find('@') != std::string::npos) {
+                    auto bare = first.substr(0, first.find('@'));
+                    log::error("ambiguous target: '{}' already includes "
+                               "@<version>, but a separate version '{}' was "
+                               "also given", first,
+                               std::string(args.positional(1)));
+                    log::error("  hint: pick one of `{}` or `{} {}`",
+                               first, bare, std::string(args.positional(1)));
+                    return 1;
+                }
+                return xvm::cmd_use(first, std::string(args.positional(1)),
+                                    stream, strict);
+            }))
+
+        // config
+        .subcommand("config")
+            .description("Show or modify xlings configuration")
+            .option(cmdline::Option("lang").takes_value().value_name("LANG").help("Set language (en/zh)"))
+            .option(cmdline::Option("mirror").takes_value().value_name("MIRROR").help("Set mirror (GLOBAL/CN)"))
+            .option(cmdline::Option("add-xpkg").takes_value().value_name("FILE").help("Add xpkg file to package index"))
+            .option(cmdline::Option("index-repo").takes_value().value_name("NS:URL").help("Add/update index repo (e.g. myns:https://...git)"))
+            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
+                apply_global_opts_(args);
+                return cmd_config_(args, stream);
+            }))
+
+        // interface — programmatic JSON API (NDJSON over stdio).
+        // See docs/plans/2026-04-25-interface-api-v1.md for full protocol spec.
+        .subcommand("interface")
+            .description("Programmatic JSON API for external tools (NDJSON over stdio)")
+            .option(cmdline::Option("args").takes_value().value_name("JSON")
+                .help("Capability arguments as JSON string"))
+            .option(cmdline::Option("args-file").takes_value().value_name("PATH")
+                .help("Read capability arguments from a file (avoids cmd.exe quoting on Windows)"))
+            .option(cmdline::Option("list").help("List all available capabilities with schemas"))
+            .option(cmdline::Option("version").help("Print protocol version and exit"))
+            .arg("capability").help("Capability name to invoke")
+            .action(wrap_rc([&stream, tui_listener, &registry](const cmdline::ParsedArgs& args) -> int {
+                return interface::run(args, stream, tui_listener, registry);
+            }));
+
+    // Top-level catch: any uncaught std::exception (most commonly
+    // std::filesystem::filesystem_error from a missing error_code
+    // overload, but also out-of-memory, invalid_argument from JSON parsing,
+    // etc.) would otherwise propagate out of main() and trigger
+    // std::terminate(). On Windows, terminate() does not flush stdio
+    // buffers, so any log::error already queued is lost — CI sees a
+    // silent non-zero exit. Convert to a logged error + non-zero return
+    // so the user always sees what went wrong.
+    try {
+        // app.run returns its own status (1 for parse errors, 0 on
+        // successful dispatch). On successful dispatch, the action
+        // lambda's intended exit code lives in `action_rc` (cmdline lib
+        // discards it on its own). Surface the action's rc when app.run
+        // succeeded so e.g. `xlings install <bad-pkg>` returns non-zero
+        // to scripts and CI.
+        auto app_rc = app.run(argc, argv);
+        if (app_rc != 0) return app_rc;
+        return action_rc;
+    } catch (const std::filesystem::filesystem_error& e) {
+        log::error("filesystem error: {}", e.what());
+        if (!e.path1().empty()) log::error("  path: {}", e.path1().string());
+        log::error("  hint: this is likely a bug; please report at "
+                   "https://github.com/openxlings/xlings/issues");
+        return 1;
+    } catch (const std::exception& e) {
+        log::error("internal error: {}", e.what());
+        log::error("  hint: this is likely a bug; please report at "
+                   "https://github.com/openxlings/xlings/issues");
+        return 1;
+    } catch (...) {
+        log::error("internal error: unknown exception");
+        return 1;
+    }
+}
+
+}
diff --git a/src/cli.cppm b/src/cli.cppm
index eb11534a..3ec33d6a 100644
--- a/src/cli.cppm
+++ b/src/cli.cppm
@@ -10,1247 +10,16 @@ import std;
 import mcpplibs.cmdline;
 import mcpplibs.capi.lua;
 import mcpplibs.xpkg.executor;
-import xlings.core.config;
-import xlings.core.home_config;
-import xlings.libs.json;
-import xlings.core.log;
-import xlings.runtime;
-import xlings.ui;
-import xlings.core.i18n;
-import xlings.platform;
-import xlings.capabilities;
 import xlings.agent;
-import xlings.agent.text_renderer;
 import xlings.interface;
 import xlings.core.subos;
 import xlings.core.xself;
-import xlings.core.xim.commands;
-import xlings.core.xvm.types;
-import xlings.core.xvm.db;
-import xlings.core.xvm.commands;
-import xlings.core.profile;
-import xlings.core.utf8;
 import xlings.cli.spec;
-import xlings.core.xim.index_cmd;
 
 namespace lua = mcpplibs::capi::lua;
 
 namespace xlings::cli {
 
-// ─── EventStream consumer: dispatch DataEvent to ui:: functions ───
-
-static void dispatch_data_event(const DataEvent& e) {
-    auto json = nlohmann::json::parse(e.json, nullptr, false);
-    if (json.is_discarded()) {
-        log::warn("invalid JSON in DataEvent kind={}", e.kind);
-        return;
-    }
-
-    if (e.kind == "info_panel") {
-        std::string title = json.value("title", "");
-        std::vector<ui::InfoField> fields;
-        if (json.contains("fields") && json["fields"].is_array()) {
-            for (auto& f : json["fields"]) {
-                fields.push_back({
-                    f.value("label", ""),
-                    f.value("value", ""),
-                    f.value("highlight", false),
-                    f.value("alert", false)
-                });
-            }
-        }
-        std::vector<ui::InfoField> extra;
-        if (json.contains("extra_fields") && json["extra_fields"].is_array()) {
-            for (auto& f : json["extra_fields"]) {
-                extra.push_back({
-                    f.value("label", ""),
-                    f.value("value", ""),
-                    f.value("highlight", false),
-                    f.value("alert", false)
-                });
-            }
-        }
-        ui::print_info_panel(title, fields, extra);
-    }
-    else if (e.kind == "help") {
-        std::string name = json.value("name", "");
-        std::string desc = json.value("description", "");
-        std::vector<ui::HelpArg> args;
-        if (json.contains("args") && json["args"].is_array()) {
-            for (auto& a : json["args"]) {
-                args.push_back({
-                    a.value("name", ""),
-                    a.value("desc", ""),
-                    a.value("required", false)
-                });
-            }
-        }
-        std::vector<ui::HelpOpt> opts;
-        if (json.contains("opts") && json["opts"].is_array()) {
-            for (auto& o : json["opts"]) {
-                opts.push_back({
-                    o.value("name", ""),
-                    o.value("desc", "")
-                });
-            }
-        }
-        ui::print_subcommand_help(name, desc, args, opts);
-    }
-    else if (e.kind == "tip") {
-        ui::print_tip(json.value("message", ""));
-    }
-    else if (e.kind == "styled_list") {
-        std::string title = json.value("title", "");
-        bool numbered = json.value("numbered", false);
-        std::vector<ui::ListRow> items;
-        if (json.contains("items") && json["items"].is_array()) {
-            for (auto& item : json["items"]) {
-                if (item.is_array() && item.size() >= 2) {
-                    items.push_back({
-                        item[0].get<std::string>(),
-                        item[1].get<std::string>(),
-                        item.size() >= 3 ? item[2].get<std::string>()
-                                         : std::string{},
-                    });
-                } else if (item.is_string()) {
-                    items.push_back({item.get<std::string>(), "", ""});
-                }
-            }
-        }
-        ui::print_styled_list(title, items, numbered);
-    }
-    else if (e.kind == "install_plan") {
-        std::vector<std::pair<std::string, std::string>> packages;
-        if (json.contains("packages") && json["packages"].is_array()) {
-            for (auto& p : json["packages"]) {
-                if (p.is_array() && p.size() >= 2) {
-                    packages.emplace_back(p[0].get<std::string>(), p[1].get<std::string>());
-                }
-            }
-        }
-        ui::print_install_plan(packages);
-    }
-    else if (e.kind == "install_summary") {
-        ui::print_install_summary(json.value("success", 0), json.value("failed", 0));
-    }
-    else if (e.kind == "remove_plan") {
-        ui::print_remove_plan(
-            json.value("subos", ""),
-            json.value("name", ""),
-            json.value("version", ""));
-    }
-    else if (e.kind == "remove_summary") {
-        // Tolerate the legacy "target" key (older interface clients) by
-        // falling back when name/version were not provided.
-        auto name = json.value("name", json.value("target", ""));
-        std::vector<std::string> pinnedBy;
-        if (json.contains("pinned_by") && json["pinned_by"].is_array()) {
-            for (auto& n : json["pinned_by"]) {
-                if (n.is_string()) pinnedBy.push_back(n.get<std::string>());
-            }
-        }
-        ui::print_remove_summary(
-            json.value("subos", ""),
-            name,
-            json.value("version", ""),
-            json.value("detached", false),
-            pinnedBy);
-    }
-    else if (e.kind == "subos_candidates") {
-        std::vector<std::tuple<std::string, std::string, int, bool>> entries;
-        if (json.contains("candidates") && json["candidates"].is_array()) {
-            for (auto& candidate : json["candidates"]) {
-                entries.emplace_back(
-                    candidate.value("name", ""),
-                    candidate.value("dir", ""),
-                    candidate.value("pkgCount", 0),
-                    candidate.value("active", false));
-            }
-        }
-        if (json.value("auto_selected", false)) {
-            ui::print_subos_resolved(
-                json.value("query", ""), json.value("selected", ""));
-        } else {
-            ui::print_subos_list(entries);
-            auto hint = json.value("hint", "");
-            if (!hint.empty()) ui::print_tip(hint);
-        }
-    }
-    else if (e.kind == "subos_list") {
-        std::vector<std::tuple<std::string, std::string, int, bool>> entries;
-        if (json.contains("entries") && json["entries"].is_array()) {
-            for (auto& e : json["entries"]) {
-                entries.emplace_back(
-                    e.value("name", ""),
-                    e.value("dir", ""),
-                    e.value("pkgCount", 0),
-                    e.value("active", false)
-                );
-            }
-        }
-        ui::print_subos_list(entries);
-    }
-    else if (e.kind == "subos_created") {
-        ui::print_subos_created(
-            json.value("name", ""), json.value("dir", ""));
-    }
-    else if (e.kind == "subos_switched") {
-        ui::print_subos_switched(
-            json.value("name", ""), json.value("dir", ""));
-    }
-    else if (e.kind == "subos_entering") {
-        ui::print_subos_entering(json.value("name", ""));
-    }
-    else if (e.kind == "subos_already_in") {
-        ui::print_subos_already_in(json.value("name", ""));
-    }
-    else if (e.kind == "subos_nesting") {
-        ui::print_subos_nesting(
-            json.value("from", ""), json.value("to", ""));
-    }
-    else if (e.kind == "subos_removed") {
-        ui::print_subos_removed(json.value("name", ""));
-    }
-    else if (e.kind == "search_results") {
-        std::vector<std::pair<std::string, std::string>> results;
-        if (json.contains("results") && json["results"].is_array()) {
-            for (auto& r : json["results"]) {
-                if (r.is_array() && r.size() >= 2) {
-                    results.emplace_back(r[0].get<std::string>(), r[1].get<std::string>());
-                }
-            }
-        }
-        ui::print_search_results(results);
-    }
-    else if (e.kind == "table") {
-        std::vector<std::string> headers;
-        if (json.contains("headers") && json["headers"].is_array()) {
-            for (auto& h : json["headers"]) {
-                headers.push_back(h.get<std::string>());
-            }
-        }
-        std::vector<std::vector<std::string>> rows;
-        if (json.contains("rows") && json["rows"].is_array()) {
-            for (auto& r : json["rows"]) {
-                std::vector<std::string> row;
-                if (r.is_array()) {
-                    for (auto& c : r) row.push_back(c.get<std::string>());
-                }
-                rows.push_back(std::move(row));
-            }
-        }
-        ui::print_table(headers, rows);
-    }
-    else if (e.kind == "download_progress") {
-        // Skip CLI rendering in TUI mode (agent TUI handles progress separately)
-        if (platform::is_tui_mode()) return;
-        auto nameWidth = json.value("nameWidth", std::size_t{20});
-        auto elapsedSec = json.value("elapsedSec", 0.0);
-        auto sizesReady = json.value("sizesReady", false);
-        std::vector<ui::DownloadProgressEntry> entries;
-        if (json.contains("files") && json["files"].is_array()) {
-            for (auto& f : json["files"]) {
-                entries.push_back({
-                    f.value("name", std::string{}),
-                    f.value("totalBytes", 0.0),
-                    f.value("downloadedBytes", 0.0),
-                    f.value("started", false),
-                    f.value("finished", false),
-                    f.value("success", false)
-                });
-            }
-        }
-        auto prevLines = json.value("prevLines", 0);
-        ui::render_download_progress(entries, nameWidth, elapsedSec, sizesReady, prevLines);
-    }
-    else {
-        log::debug("unhandled DataEvent kind: {}", e.kind);
-    }
-}
-
-// ─── EventStream consumer: handle PromptEvent via ui:: interactive functions ───
-
-static void handle_prompt(EventStream& stream, const PromptEvent& p) {
-    // Binary yes/no → confirm dialog
-    if (p.options.size() == 2 && p.options[0] == "y" && p.options[1] == "n") {
-        bool defaultYes = (p.defaultValue == "y");
-        bool result = ui::confirm(p.question, defaultYes);
-        stream.respond(p.id, result ? "y" : "n");
-        return;
-    }
-
-    // Multiple options → package selector
-    if (!p.options.empty()) {
-        std::vector<std::pair<std::string, std::string>> items;
-        for (auto& opt : p.options) {
-            items.emplace_back(opt, "");
-        }
-        auto result = ui::select_package(items);
-        stream.respond(p.id, result.value_or(""));
-        return;
-    }
-
-    // Free input — use default
-    stream.respond(p.id, p.defaultValue);
-}
-
-// Parse legacy config.xlings (Lua format) and extract workspace from the xim table.
-// Returns empty workspace if file doesn't exist or has no xim/xlings_deps.
-xvm::Workspace parse_legacy_config_(const std::filesystem::path& configFile) {
-    namespace fs = std::filesystem;
-    xvm::Workspace workspace;
-
-    if (!fs::exists(configFile)) return workspace;
-
-    auto* L = lua::L_newstate();
-    if (!L) return workspace;
-    lua::L_openlibs(L);
-
-    // Provide a no-op is_host() so Lua files with conditionals don't error
-    lua::L_dostring(L, "function is_host() return false end");
-
-    if (lua::L_dofile(L, configFile.string().c_str()) != lua::OK) {
-        log::warn("failed to parse legacy config: {}", lua::tostring(L, -1));
-        lua::close(L);
-        return workspace;
-    }
-
-    // Read xim table: { pkg_name = "version", ... }
-    lua::getglobal(L, "xim");
-    if (lua::type(L, -1) == lua::TTABLE) {
-        lua::pushnil(L);
-        while (lua::next(L, -2)) {
-            if (lua::type(L, -2) == lua::TSTRING) {
-                std::string key = lua::tostring(L, -2);
-                // Skip non-package entries
-                if (key != "xppcmds") {
-                    std::string version;
-                    if (lua::type(L, -1) == lua::TSTRING) {
-                        version = lua::tostring(L, -1);
-                    }
-                    workspace[key] = version;
-                }
-            }
-            lua::pop(L, 1); // pop value, keep key for next iteration
-        }
-    }
-    lua::pop(L, 1); // pop xim
-
-    // Fallback: older format uses xlings_deps = "cpp, vscode, mdbook"
-    if (workspace.empty()) {
-        lua::getglobal(L, "xlings_deps");
-        if (lua::type(L, -1) == lua::TSTRING) {
-            std::string deps = lua::tostring(L, -1);
-            std::istringstream ss(deps);
-            std::string token;
-            while (std::getline(ss, token, ',')) {
-                auto start = token.find_first_not_of(" \t");
-                auto end = token.find_last_not_of(" \t");
-                if (start != std::string::npos) {
-                    workspace[token.substr(start, end - start + 1)] = "";
-                }
-            }
-        }
-        lua::pop(L, 1);
-    }
-
-    lua::close(L);
-    return workspace;
-}
-
-// Generate .xlings.json from a workspace map
-void generate_xlings_json_(const std::filesystem::path& dir, const xvm::Workspace& workspace) {
-    nlohmann::json ws;
-    for (auto& [name, version] : workspace) {
-        ws[name] = version;
-    }
-    nlohmann::json root;
-    root["workspace"] = ws;
-    auto outPath = dir / ".xlings.json";
-    platform::write_string_to_file(outPath.string(), root.dump(2));
-}
-
-// Normalize a target-spec from positional args for the single-target
-// commands (remove/update/info — `use` has its own list-versions
-// semantic and parses inline).
-//
-// Accepted forms (equivalent):
-//   1 positional, contains '@'   →  passed as-is  (e.g. "node@22.17.1")
-//   1 positional, no '@'         →  passed as-is  (bare name; the cmd
-//                                    decides what to do — typically
-//                                    "use the active version")
-//   2 positionals                →  folded into "<arg0>@<arg1>"
-//
-// Rejected:
-//   3+ positionals
-//   2 positionals where arg0 already contains '@' (ambiguous)
-//
-// Returns false (with a logged error) on bad input. Caller should
-// `return 1` on false.
-bool parse_target_spec_(const mcpplibs::cmdline::ParsedArgs& args,
-                        std::string& out) {
-    auto n = args.positional_count();
-    if (n == 0) {
-        log::error("missing target argument");
-        return false;
-    }
-    if (n > 2) {
-        log::error("too many positional arguments (expected 1 or 2, got {})", n);
-        log::error("  hint: use `<name>@<version>` or `<name> <version>`");
-        return false;
-    }
-    auto first = std::string(args.positional(0));
-    if (n == 1) {
-        out = std::move(first);
-        return true;
-    }
-    // n == 2: "<name> <version>" form. The first arg must be a bare
-    // name — if it already includes '@', the user gave us two version
-    // hints and we can't reconcile.
-    if (first.find('@') != std::string::npos) {
-        auto bare = first.substr(0, first.find('@'));
-        log::error("ambiguous target: '{}' already includes @<version>, "
-                   "but a separate version '{}' was also given",
-                   first, std::string(args.positional(1)));
-        log::error("  hint: pick one of `{}` or `{} {}`",
-                   first, bare, std::string(args.positional(1)));
-        return false;
-    }
-    out = first + "@" + std::string(args.positional(1));
-    return true;
-}
-
-// Install packages from project .xlings.json workspace
-int install_from_project_config_(EventStream& stream) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    auto cwd = fs::current_path(ec);
-    if (ec) return 1;
-    auto homeDir = Config::paths().homeDir;
-
-    // Walk up from cwd looking for .xlings.json with workspace
-    fs::path cur = cwd;
-    while (!cur.empty()) {
-        auto curNorm = fs::weakly_canonical(cur, ec);
-        auto homeNorm = fs::weakly_canonical(homeDir, ec);
-        if (curNorm == homeNorm) {
-            auto parent = cur.parent_path();
-            if (parent == cur) break;
-            cur = parent;
-            continue;
-        }
-
-        // Try .xlings.json first
-        auto cfg = cur / ".xlings.json";
-        if (fs::exists(cfg, ec) && fs::is_regular_file(cfg, ec)) {
-            try {
-                auto content = platform::read_file_to_string(cfg.string());
-                auto json = nlohmann::json::parse(content, nullptr, false);
-                if (!json.is_discarded() && json.contains("workspace") && json["workspace"].is_object()) {
-                    auto workspace = xvm::workspace_from_json(json["workspace"]);
-                    auto targets = Config::workspace_install_targets(workspace);
-                    if (!targets.empty()) {
-                        // Project-config install: the workspace file declares
-                        // which versions should be active in this subos, so
-                        // force-activate to keep workspace state in sync with
-                        // the config.
-                        return xim::cmd_install(targets, true, false, stream,
-                                                /*forceGlobal=*/false,
-                                                /*cancel=*/nullptr,
-                                                /*dryRun=*/false,
-                                                /*useAfterInstall=*/true);
-                    }
-                }
-            } catch (...) {
-                log::error("failed to parse {}", cfg.string());
-                return 1;
-            }
-        }
-
-        // Fallback: try legacy config.xlings (Lua format)
-        auto legacyCfg = cur / "config.xlings";
-        if (fs::exists(legacyCfg, ec) && fs::is_regular_file(legacyCfg, ec)) {
-            auto workspace = parse_legacy_config_(legacyCfg);
-            if (!workspace.empty()) {
-                log::println("detected legacy config: {}", legacyCfg.string());
-                log::println("generating .xlings.json from config.xlings ...");
-                generate_xlings_json_(cur, workspace);
-                log::println("generated: {}", (cur / ".xlings.json").string());
-                auto targets = Config::workspace_install_targets(workspace);
-                return xim::cmd_install(targets, true, false, stream,
-                                        /*forceGlobal=*/false,
-                                        /*cancel=*/nullptr,
-                                        /*dryRun=*/false,
-                                        /*useAfterInstall=*/true);
-            }
-        }
-
-        auto parent = cur.parent_path();
-        if (parent == cur) break;
-        cur = parent;
-    }
-
-    ui::print_tip("create <project>/.xlings.json with workspace, or run `xlings install <package>`");
-    return 0;
-}
-
-void apply_global_opts_(const mcpplibs::cmdline::ParsedArgs& args) {
-    if (args.is_flag_set("verbose")) log::set_level(log::Level::Debug);
-    if (args.is_flag_set("quiet")) log::set_level(log::Level::Error);
-}
-
-
-// config subcommand handler
-int cmd_config_(const mcpplibs::cmdline::ParsedArgs& args, EventStream& stream) {
-    // Edits are collected rather than applied, then replayed against the
-    // document `update_home_config` re-reads under the state lock. Applying
-    // them to a copy read here instead would write back every *other* key as
-    // it looked before an install that finished in the meantime -- see
-    // core/home_config.cppm. Validation and the user-facing logging stay out
-    // here so a rejected argument never reaches the lock.
-    std::vector<std::function<void(nlohmann::json&)>> edits;
-
-    // --lang
-    if (auto lang = args.value("lang")) {
-        std::string value(*lang);
-        edits.push_back([value](nlohmann::json& j) { j["lang"] = value; });
-        log::println("lang = {}", value);
-    }
-
-    // --mirror
-    if (auto mirror = args.value("mirror")) {
-        std::string value(*mirror);
-        edits.push_back([value](nlohmann::json& j) { j["mirror"] = value; });
-        log::println("mirror = {}", value);
-    }
-
-    auto commit_edits = [&]() -> bool {
-        if (edits.empty()) return true;
-        auto committed = update_home_config(
-            Config::paths().homeDir, [&](nlohmann::json& j) {
-                for (const auto& edit : edits) edit(j);
-                return true;
-            });
-        if (!committed) {
-            log::error("{}", committed.error());
-            return false;
-        }
-        return true;
-    };
-
-    // --add-xpkg
-    if (auto xpkg = args.value("add-xpkg")) {
-        if (!commit_edits()) return 1;
-        return xim::cmd_add_xpkg(std::string(*xpkg), stream);
-    }
-
-    // --index-repo  namespace:https://....git
-    if (auto repo = args.value("index-repo")) {
-        std::string val(*repo);
-        auto colonPos = val.find(':');
-        // Find the colon that separates name from URL (skip scheme "https://")
-        // Format: name:url  e.g. myrepo:https://github.com/user/repo.git
-        if (colonPos == std::string::npos || colonPos == 0) {
-            log::error("invalid format, expected: <namespace>:<url>");
-            log::error("  e.g. myrepo:https://github.com/user/repo.git");
-            return 1;
-        }
-        auto name = val.substr(0, colonPos);
-        auto url = val.substr(colonPos + 1);
-        if (url.empty()) {
-            log::error("invalid format, expected: <namespace>:<url>");
-            return 1;
-        }
-
-        // Upsert against the freshly-read document: a repo another process
-        // added since we started must be updated in place, not duplicated.
-        edits.push_back([name, url](nlohmann::json& json) {
-            if (!json.contains("index_repos")
-                || !json["index_repos"].is_array()) {
-                json["index_repos"] = nlohmann::json::array();
-            }
-            for (auto& entry : json["index_repos"]) {
-                if (entry.is_object() && entry.contains("name") &&
-                    entry["name"].get<std::string>() == name) {
-                    entry["url"] = url;
-                    return;
-                }
-            }
-            nlohmann::json entry;
-            entry["name"] = name;
-            entry["url"] = url;
-            json["index_repos"].push_back(entry);
-        });
-        log::println("index-repo {} = {}", name, url);
-    }
-
-    if (!edits.empty()) {
-        return commit_edits() ? 0 : 1;
-    }
-
-    // No options: show current config via TUI info panel
-    auto& p = Config::paths();
-    std::vector<ui::InfoField> fields;
-    fields.push_back({"XLINGS_HOME", p.homeDir.string()});
-    fields.push_back({"XLINGS_DATA", Config::display_path(p.dataDir)});
-    fields.push_back({"XLINGS_SUBOS", Config::display_path(p.subosDir)});
-    fields.push_back({"active subos", p.activeSubos, true});
-    fields.push_back({"bin", Config::display_path(p.binDir)});
-
-    auto mirror = Config::mirror();
-    if (!mirror.empty()) fields.push_back({"mirror", mirror});
-    auto lang = Config::lang();
-    if (!lang.empty()) fields.push_back({"lang", lang});
-
-    auto& repos = Config::global_index_repos();
-    for (auto& repo : repos) {
-        fields.push_back({"index-repo", repo.name + " : " + repo.url});
-    }
-
-    if (Config::has_project_config()) {
-        fields.push_back({"project data", Config::project_data_dir().string()});
-        auto& projectRepos = Config::project_index_repos();
-        for (auto& repo : projectRepos) {
-            fields.push_back({"project repo", repo.name + " : " + repo.url});
-        }
-    }
-
-    ui::print_info_panel("xlings config", fields);
-    return 0;
-}
-
-// `xlings profile list|commit|rollback` — generations of the active subos.
-//
-// The module had commit / list_generations / rollback and no way to reach
-// any of them: four exported functions, zero callers, no subcommand. So the
-// feature read as working and was not, and `rollback` in particular wrote a
-// YAML file nothing consulted.
-//
-// Commit is explicit rather than automatic. Recording a generation on every
-// install would change the hot path for everyone, and which mutations
-// deserve a generation is a product decision, not one to make on the way
-// past. Explicit commits make the feature usable now without deciding it.
-int run_profile_(int argc, char* argv[], EventStream& stream) {
-    const std::string action = (argc >= 3) ? argv[2] : "list";
-    auto& p = Config::paths();
-    const auto envDir = p.subosDir;
-
-    if (action == "list") {
-        auto gens = profile::list_generations(envDir);
-        auto current = profile::load_current(envDir);
-        if (gens.empty()) {
-            std::println("no generations yet — record one with "
-                         "`xlings profile commit [reason]`");
-            return 0;
-        }
-        for (const auto& gen : gens) {
-            std::println("{}{:>4}  {}  {} package(s)  {}",
-                         gen.number == current.number ? "*" : " ",
-                         gen.number, gen.created, gen.packages.size(),
-                         gen.reason);
-        }
-        return 0;
-    }
-
-    if (action == "commit") {
-        const std::string reason = (argc >= 4) ? argv[3] : "manual";
-        std::map<std::string, std::string> packages;
-        for (const auto& [target, version] : Config::effective_workspace()) {
-            packages[target] = version;
-        }
-        profile::commit(envDir, packages, reason);
-        auto current = profile::load_current(envDir);
-        std::println("[xlings:profile] recorded generation {} ({} package(s))",
-                     current.number, packages.size());
-        return 0;
-    }
-
-    if (action == "rollback") {
-        if (argc < 4) {
-            ui::print_usage("xlings profile rollback <generation>");
-            return 1;
-        }
-        int target = 0;
-        try { target = std::stoi(argv[3]); }
-        catch (...) {
-            log::error("not a generation number: {}", argv[3]);
-            return 1;
-        }
-        auto packages = profile::rollback(envDir, target);
-        if (!packages) {
-            log::error("[xlings:profile] {}", packages.error());
-            return 1;
-        }
-        // Apply through the same path `xlings use` takes. Recording the
-        // selection is not rolling back: the previous implementation stopped
-        // at the record and left every version where it was.
-        int failed = 0;
-        for (const auto& [name, version] : *packages) {
-            if (xvm::cmd_use(name, version, stream) != 0) ++failed;
-        }
-        std::println("[xlings:profile] rolled back to generation {}", target);
-        return failed == 0 ? 0 : 1;
-    }
-
-    ui::print_usage("xlings profile [list | commit [reason] | rollback <n>]");
-    return action == "-h" || action == "--help" ? 0 : 1;
-}
-
-export int run(int argc, char* argv[]) {
-    if (argc == 2
-        && std::string_view{argv[1]} == "--command-reference-json") {
-        std::println("{}", spec::reference_json().dump());
-        return 0;
-    }
-    using namespace mcpplibs;
-
-    // Bare `xlings` (no args) used to silently exit 0 because the
-    // help branch below requires fargc >= 2 (i.e. at least one arg).
-    // Treat it as `xlings --help` instead — much friendlier for first
-    // contact and matches what most modern package managers do.
-    if (argc <= 1) {
-        ui::print_help(Info::VERSION);
-        return 0;
-    }
-
-    // Create EventStream for core→UI decoupling
-    EventStream stream;
-    // Default TUI consumer for CLI mode (will be toggled in agent mode).
-    // ErrorEvent/LogEvent surfacing keeps capability-emitted errors visible
-    // to CLI users — without it, anything that emits an ErrorEvent (subos
-    // operations, repo helpers) would silently fail in CLI mode.
-    int tui_listener = stream.on_event([&stream](const Event& e) {
-        if (auto* d = std::get_if<DataEvent>(&e)) {
-            dispatch_data_event(*d);
-        }
-        else if (auto* p = std::get_if<PromptEvent>(&e)) {
-            handle_prompt(stream, *p);
-        }
-        else if (auto* er = std::get_if<ErrorEvent>(&e)) {
-            // Wrapped here, not at the call sites. An ErrorEvent's message is
-            // composed by whichever command raised it, and some of them carry
-            // a list of candidates or a full command line -- the width
-            // contract has to be a property of the renderer, or every command
-            // re-derives it and one of them gets it wrong. log:: itself
-            // cannot do this: core does not depend on ui.
-            auto emit = [](std::string_view text, std::string_view indent) {
-                const int prefix = 8  // "[error] "
-                    + ui::layout::display_width(indent);
-                const int width = std::max(1,
-                    ui::layout::fit_width(
-                        prefix + ui::layout::display_width(text)) - prefix);
-                for (auto& line : ui::layout::wrap_to_width(text, width)) {
-                    log::error("{}{}", indent, line);
-                }
-            };
-            emit(er->message, "");
-            if (!er->hint.empty()) emit(er->hint, "  ");
-        }
-        else if (auto* l = std::get_if<LogEvent>(&e)) {
-            switch (l->level) {
-                case LogLevel::debug: log::debug("{}", l->message); break;
-                case LogLevel::info:  log::info("{}",  l->message); break;
-                case LogLevel::warn:  log::warn("{}",  l->message); break;
-                case LogLevel::error: log::error("{}", l->message); break;
-            }
-        }
-    });
-
-    // Build Capability Registry (for Agent/MCP use — CLI keeps direct dispatch)
-    auto registry = capabilities::build_registry();
-
-    // Scan for global flags (--verbose, -v, --quiet, -q, --agent) anywhere
-    // in argv so they work regardless of position.
-    bool agent_mode = false;
-    for (int i = 1; i < argc; ++i) {
-        std::string_view a { argv[i] };
-        if (a == "--verbose" || a == "-v") log::set_level(log::Level::Debug);
-        else if (a == "--quiet" || a == "-q") log::set_level(log::Level::Error);
-        else if (a == "--agent") agent_mode = true;
-    }
-
-    // --agent: replace TUI listener with plain-text renderer, disable colors.
-    // Unlike interface mode, we do NOT set tui_mode(true) — log output should
-    // still reach the terminal, just without ANSI decoration.
-    if (agent_mode) {
-        stream.set_enabled(tui_listener, false);
-        log::enable_color(false);
-        // One switch for every writer, not just log's own prefixes.
-        ui::layout::set_plain(true);
-        stream.on_event([&stream](const Event& e) {
-            if (auto* d = std::get_if<DataEvent>(&e)) {
-                agent::render_data_event(*d);
-            }
-            else if (auto* p = std::get_if<PromptEvent>(&e)) {
-                // In agent mode, auto-respond with default (use --yes for confirms)
-                stream.respond(p->id, p->defaultValue);
-            }
-            else if (auto* er = std::get_if<ErrorEvent>(&e)) {
-                std::println(stderr, "Error: {}", er->message);
-                if (!er->hint.empty()) std::println(stderr, "Hint: {}", er->hint);
-            }
-            else if (auto* l = std::get_if<LogEvent>(&e)) {
-                if (l->level == LogLevel::error)
-                    std::println(stderr, "{}", l->message);
-                else if (l->level == LogLevel::warn)
-                    std::println(stderr, "{}", l->message);
-                else
-                    std::println("{}", l->message);
-            }
-        });
-    }
-
-    // Build filtered argv without global flags for positional-arg handlers
-    // (subos, self, script parse argv[2]/argv[3] positionally)
-    std::vector<char*> fargv;
-    fargv.push_back(argv[0]);
-    for (int i = 1; i < argc; ++i) {
-        std::string_view a { argv[i] };
-        if (a == "--verbose" || a == "-v" || a == "--quiet" || a == "-q"
-            || a == "--agent") continue;
-        fargv.push_back(argv[i]);
-    }
-    int fargc = static_cast<int>(fargv.size());
-
-    // Find the first non-flag argument as the command name
-    std::string cmd;
-    for (int i = 1; i < fargc; ++i) {
-        std::string_view a { fargv[i] };
-        if (!a.starts_with("-")) { cmd = std::string(a); break; }
-    }
-
-    // Special: subos, self, script need raw argc/argv
-    if (fargc >= 2) {
-        // Handle -h/--help/--version before cmdline library to avoid
-        // std::format width-specifier crash in GCC 15 C++23 modules.
-        if (cmd == "-h" || cmd == "--help" || cmd.empty()) {
-            if (cmd.empty()) {
-                // Only flags, no command — check if -h was requested
-                for (int i = 1; i < fargc; ++i) {
-                    std::string_view a { fargv[i] };
-                    if (a == "-h" || a == "--help") { ui::print_help(Info::VERSION); return 0; }
-                    if (a == "--version") { std::println("xlings {}", Info::VERSION); return 0; }
-                }
-            }
-            ui::print_help(Info::VERSION);
-            return 0;
-        }
-        if (cmd == "--version") {
-            std::println("xlings {}", Info::VERSION);
-            return 0;
-        }
-
-        // agent — dispatched before the generic help interception so it keeps
-        // handling its own -h as plain text. `xlings agent -h` has to print
-        // the skill overview (the list of what is installed and readable),
-        // and the boxed subcommand help rendered from the spec neither is
-        // plain text nor names a single skill. The whole point of this command
-        // family is that a machine reads its output.
-        if (cmd == "agent") return agent::run(fargc, fargv.data());
-
-        // Intercept subcommand help: xlings <cmd> -h/--help
-        bool wantsHelp = false;
-        for (int i = 2; i < fargc; ++i) {
-            std::string_view a { fargv[i] };
-            if (a == "-h" || a == "--help") { wantsHelp = true; break; }
-        }
-        if (wantsHelp) {
-            using A = ui::HelpArg;
-            using O = ui::HelpOpt;
-
-            std::vector<std::string_view> commandPath;
-            commandPath.push_back(cmd);
-            if (fargc > 2) {
-                const std::string_view nested{fargv[2]};
-                if (!nested.starts_with('-')) {
-                    auto candidate = commandPath;
-                    candidate.push_back(nested);
-                    if (spec::find(candidate)) commandPath = std::move(candidate);
-                }
-            }
-            if (const auto* command = spec::find(commandPath)) {
-                std::vector<A> arguments;
-                std::vector<O> options;
-                std::vector<O> children;
-                for (const auto& argument : command->arguments) {
-                    arguments.push_back({argument.name, argument.description,
-                                         argument.required});
-                }
-                for (const auto& option : command->options) {
-                    options.push_back({option.syntax, option.description});
-                }
-                for (const auto& child : command->children) {
-                    children.push_back({child.name, child.description});
-                }
-                ui::print_subcommand_help(command->name, command->description,
-                                          arguments, options, children);
-                return 0;
-            }
-
-        }
-
-        // index — positional dispatch like subos/self, so it validates the
-        // same way and never reaches the cmdline builder's package semantics.
-        if (cmd == "index") {
-            const std::array<std::string_view, 1> path{cmd};
-            if (const auto* command = spec::find(path)) {
-                std::vector<std::string_view> manualArgs;
-                for (int i = 2; i < fargc; ++i) manualArgs.emplace_back(fargv[i]);
-                if (auto validated = spec::validate_manual_argv(*command, manualArgs);
-                    !validated) {
-                    log::error("{}", validated.error().message);
-                    return 2;
-                }
-            }
-            std::string sub = fargc > 2 ? fargv[2] : "list";
-            if (sub == "ls") sub = "list";
-            if (sub == "list") {
-                std::string filter;
-                bool asJson = false;
-                for (int i = 3; i < fargc; ++i) {
-                    std::string_view a{fargv[i]};
-                    if (a == "--json") asJson = true;
-                    else if (!a.starts_with('-')) filter = std::string(a);
-                }
-                return xim::cmd_index_list(filter, asJson, stream);
-            }
-            if (sub == "use") {
-                return xim::cmd_index_use(fargc > 3 ? fargv[3] : "",
-                                          fargc > 4 ? fargv[4] : "", stream);
-            }
-            log::error("unknown subcommand for `xlings index`: {}", sub);
-            return 2;
-        }
-
-        if (cmd == "subos" || cmd == "self" || cmd == "profile") {
-            const std::array<std::string_view, 1> path{cmd};
-            if (const auto* command = spec::find(path)) {
-                std::vector<std::string_view> manualArgs;
-                for (int i = 2; i < fargc; ++i) manualArgs.emplace_back(fargv[i]);
-                if (auto validated = spec::validate_manual_argv(
-                        *command, manualArgs); !validated) {
-                    log::error("{}", validated.error().message);
-                    return 2;
-                }
-            }
-        }
-
-        // Detect unknown commands early — show TUI error + help
-        {
-            const bool known = std::ranges::any_of(spec::root().children,
-                [&](const auto& command) {
-                    return command.name == cmd
-                        || std::ranges::find(command.aliases, cmd)
-                            != command.aliases.end();
-                });
-            if (!known && !cmd.starts_with("-")) {
-                log::error("unknown command: {}", cmd);
-                return 1;
-            }
-        }
-
-        if (cmd == "subos") return subos::run(fargc, fargv.data(), stream);
-        if (cmd == "self") return xself::run(fargc, fargv.data(), stream);
-        if (cmd == "profile") return run_profile_(fargc, fargv.data(), stream);
-        if (cmd == "script") {
-            if (fargc < 3) {
-                ui::print_usage("xlings script <script-file> [args...]");
-                return 1;
-            }
-            namespace fs = std::filesystem;
-            fs::path scriptFile = fargv[2];
-            auto execResult = mcpplibs::xpkg::create_executor(scriptFile);
-            if (!execResult) {
-                log::error("failed to load script: {}", execResult.error());
-                return 1;
-            }
-            mcpplibs::xpkg::ExecutionContext ctx;
-            ctx.platform = std::string(platform::OS_NAME);
-            ctx.bin_dir = Config::paths().binDir;
-            ctx.subos_sysrootdir = Config::paths().subosDir.string();
-            ctx.run_dir = fs::current_path();
-            ctx.xpkg_dir = Config::paths().dataDir / "xpkgs";
-            for (int i = 3; i < fargc; ++i) {
-                ctx.args.emplace_back(fargv[i]);
-            }
-            auto result = execResult->run_script(ctx);
-            if (!result.success) {
-                log::error("script error: {}", result.error);
-                return 1;
-            }
-            return 0;
-        }
-    }
-
-    // cmdline::App stores actions as std::function<void(ParsedArgs&)>, so the
-    // int returns from each action lambda below are silently discarded by the
-    // library on its way through std::function. Capture the lambda's intended
-    // exit code into this shared int and have run() return it after app.run()
-    // completes. Without this every cmd_* return value (1 for failures, 2 for
-    // refused-by-policy, ...) is squashed to 0 — so e.g. CI scripts that branch
-    // on `xlings install` exit code never see install failures.
-    int action_rc = 0;
-    auto wrap_rc = [&action_rc](auto&& fn) {
-        return [fn = std::forward<decltype(fn)>(fn), &action_rc]
-               (const cmdline::ParsedArgs& args) {
-            action_rc = fn(args);
-        };
-    };
-
-    auto app = cmdline::App("xlings")
-        .version(std::string(Info::VERSION))
-        .author("d2learn community")
-        .description("A modern package manager and development environment tool")
-
-        // Global options
-        .option("yes").short_name('y').help("Skip confirmation prompts").global()
-        .option("verbose").short_name('v').help("Enable verbose output").global()
-        .option("quiet").short_name('q').help("Suppress non-essential output").global()
-        .option("agent").help("Plain-text output without TUI formatting (for LLM agents)").global()
-
-        // install
-        .subcommand("install")
-            .description("Install packages (e.g. xlings install gcc@15 node)")
-            .option(cmdline::Option("global").short_name('g').help("Install to global scope (not project-local subos)"))
-            .option(cmdline::Option("use").short_name('u').help("Activate the installed version even if another version is currently active"))
-            .arg("packages").help("Package names with optional version")
-            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
-                apply_global_opts_(args);
-                std::vector<std::string> targets;
-                for (std::size_t i = 0; i < args.positional_count(); ++i) {
-                    auto t = args.positional(i);
-                    if (!t.empty()) targets.emplace_back(t);
-                }
-                // Friendly hint: `install` treats every positional as an
-                // independent target (multi-package semantic). If the user
-                // wrote two args where the first looks like a bare package
-                // name and the second looks version-like, they probably
-                // meant the combined `name@version` form (single package),
-                // which is the convention the rest of the CLI follows.
-                if (targets.size() == 2
-                    && targets[0].find('@') == std::string::npos
-                    && !targets[1].empty()
-                    && (std::isdigit(static_cast<unsigned char>(targets[1][0]))
-                        || targets[1] == "latest"))
-                {
-                    log::warn("install: each positional is a separate package; "
-                              "did you mean `{}@{}` (single package) instead "
-                              "of two packages '{}' and '{}'?",
-                              targets[0], targets[1], targets[0], targets[1]);
-                }
-
-                if (targets.empty()) return install_from_project_config_(stream);
-
-                bool yes = args.is_flag_set("yes");
-                bool global = args.is_flag_set("global");
-                bool useAfter = args.is_flag_set("use");
-                return xim::cmd_install(targets, yes, false, stream, global,
-                                        /*cancel=*/nullptr, /*dryRun=*/false,
-                                        useAfter);
-            }))
-
-        // remove
-        // `-g` mirrors install's. Without it, a package installed with
-        // `install -g` from inside a project could not be removed from inside
-        // that project at all: remove resolved the project subos, found the
-        // package registered in the home's, and there was no way to say
-        // otherwise. Scope has to be expressible on both halves of a
-        // reversible pair, or the pair is not reversible.
-        .subcommand("remove")
-            .description("Remove a package")
-            .option(cmdline::Option("global").short_name('g').help("Act on the global scope (not the project-local subos)"))
-            .option(cmdline::Option("force").help("Remove even if installed packages depend on it"))
-            .arg("package").required().help("Package to remove (name or name@ver)")
-            .arg("version").help("Optional version (alternative to name@ver form)")
-            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
-                apply_global_opts_(args);
-                if (args.is_flag_set("global")) {
-                    Config::set_force_global_scope(true);
-                }
-                std::string target;
-                if (!parse_target_spec_(args, target)) return 1;
-                bool yes = args.is_flag_set("yes");
-                // Separate from `yes`, deliberately. `-y` says "do not ask me",
-                // which is a statement about prompting; breaking a dependency
-                // link is a different decision and a scripted `remove -y`
-                // should still be stopped by it.
-                bool force = args.is_flag_set("force");
-                return xim::cmd_remove(target, yes, stream, force);
-            }))
-
-        // update
-        .subcommand("update")
-            .description("Update package index or a specific package")
-            .arg("package").help("Package to update (omit for index only)")
-            .arg("version").help("Optional version (alternative to name@ver form)")
-            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
-                apply_global_opts_(args);
-                std::string target;
-                if (args.positional_count() > 0) {
-                    if (!parse_target_spec_(args, target)) return 1;
-                }
-                bool yes = args.is_flag_set("yes");
-                return xim::cmd_update(target, yes, stream);
-            }))
-
-        // search
-        .subcommand("search")
-            .description("Search for packages")
-            .arg("keyword").required().help("Search keyword")
-            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
-                apply_global_opts_(args);
-                return xim::cmd_search(std::string(args.positional(0)), stream);
-            }))
-
-        // list
-        .subcommand("list")
-            .description("List installed packages")
-            .option(cmdline::Option("all").short_name('a').help("Show packages across all subos (default: current subos only)"))
-            .arg("filter").help("Filter pattern")
-            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
-                apply_global_opts_(args);
-                std::string filter;
-                if (args.positional_count() > 0)
-                    filter = std::string(args.positional(0));
-                bool show_all = args.is_flag_set("all");
-                return xim::cmd_list(filter, stream, show_all);
-            }))
-
-        // info
-        .subcommand("info")
-            .description("Show package information")
-            .option(cmdline::Option("all-versions").help("Show every available version"))
-            .arg("package").required().help("Package name (or name@ver)")
-            .arg("version").help("Optional version (alternative to name@ver form)")
-            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
-                apply_global_opts_(args);
-                std::string target;
-                if (!parse_target_spec_(args, target)) return 1;
-                return xim::cmd_info(target, stream,
-                                     args.is_flag_set("all-versions"));
-            }))
-
-        // why — the resolution record, read back
-        .subcommand("why")
-            .description("Show why a dependency resolved to the version it did")
-            .arg("package").required().help("Installed package name")
-            .arg("dep").help("Optional dependency name to filter by")
-            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
-                apply_global_opts_(args);
-                return xim::cmd_why(args.value("package").value_or(""),
-                                    args.value("dep").value_or(""), stream);
-            }))
-
-        // use — accepts both `<name> <ver>` (legacy form) and `<name>@<ver>`
-        // (one-shot form, matching install/remove). Bare `<name>` switches
-        // when exactly one version is installed and lists them (exit 0) when
-        // several are, rather than blocking on a picker — see
-        // xvm::cmd_use_by_name. `--all` widens the candidate set to the
-        // global view (every version every subos has ever installed).
-        .subcommand("use")
-            .description("Switch tool version")
-            .option(cmdline::Option("all").short_name('a').help("Show versions across all subos (default: current subos only)"))
-            .option(cmdline::Option("strict").help("Refuse the switch if any program of the current release has no version in the new one"))
-            .arg("target").required().help("Tool name (or name@ver one-shot)")
-            .arg("version").help("Version to switch to (omit to list installed versions)")
-            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
-                apply_global_opts_(args);
-                auto n = args.positional_count();
-                if (n == 0) {
-                    log::error("missing target argument");
-                    return 1;
-                }
-                if (n > 2) {
-                    log::error("too many positional arguments (expected 1 or 2, got {})", n);
-                    log::error("  hint: use `<name>@<version>` or `<name> <version>`");
-                    return 1;
-                }
-                bool show_all = args.is_flag_set("all");
-                bool strict = args.is_flag_set("strict");
-                auto first = std::string(args.positional(0));
-                if (n == 1) {
-                    auto at = first.find('@');
-                    if (at == std::string::npos)
-                        return xvm::cmd_use_by_name(first, stream, show_all,
-                                                    strict);
-                    return xvm::cmd_use(first.substr(0, at),
-                                        first.substr(at + 1), stream, strict);
-                }
-                // n == 2: must be `<name> <version>`
-                if (first.find('@') != std::string::npos) {
-                    auto bare = first.substr(0, first.find('@'));
-                    log::error("ambiguous target: '{}' already includes "
-                               "@<version>, but a separate version '{}' was "
-                               "also given", first,
-                               std::string(args.positional(1)));
-                    log::error("  hint: pick one of `{}` or `{} {}`",
-                               first, bare, std::string(args.positional(1)));
-                    return 1;
-                }
-                return xvm::cmd_use(first, std::string(args.positional(1)),
-                                    stream, strict);
-            }))
-
-        // config
-        .subcommand("config")
-            .description("Show or modify xlings configuration")
-            .option(cmdline::Option("lang").takes_value().value_name("LANG").help("Set language (en/zh)"))
-            .option(cmdline::Option("mirror").takes_value().value_name("MIRROR").help("Set mirror (GLOBAL/CN)"))
-            .option(cmdline::Option("add-xpkg").takes_value().value_name("FILE").help("Add xpkg file to package index"))
-            .option(cmdline::Option("index-repo").takes_value().value_name("NS:URL").help("Add/update index repo (e.g. myns:https://...git)"))
-            .action(wrap_rc([&stream](const cmdline::ParsedArgs& args) -> int {
-                apply_global_opts_(args);
-                return cmd_config_(args, stream);
-            }))
-
-        // interface — programmatic JSON API (NDJSON over stdio).
-        // See docs/plans/2026-04-25-interface-api-v1.md for full protocol spec.
-        .subcommand("interface")
-            .description("Programmatic JSON API for external tools (NDJSON over stdio)")
-            .option(cmdline::Option("args").takes_value().value_name("JSON")
-                .help("Capability arguments as JSON string"))
-            .option(cmdline::Option("args-file").takes_value().value_name("PATH")
-                .help("Read capability arguments from a file (avoids cmd.exe quoting on Windows)"))
-            .option(cmdline::Option("list").help("List all available capabilities with schemas"))
-            .option(cmdline::Option("version").help("Print protocol version and exit"))
-            .arg("capability").help("Capability name to invoke")
-            .action(wrap_rc([&stream, tui_listener, &registry](const cmdline::ParsedArgs& args) -> int {
-                return interface::run(args, stream, tui_listener, registry);
-            }));
-
-    // Top-level catch: any uncaught std::exception (most commonly
-    // std::filesystem::filesystem_error from a missing error_code
-    // overload, but also out-of-memory, invalid_argument from JSON parsing,
-    // etc.) would otherwise propagate out of main() and trigger
-    // std::terminate(). On Windows, terminate() does not flush stdio
-    // buffers, so any log::error already queued is lost — CI sees a
-    // silent non-zero exit. Convert to a logged error + non-zero return
-    // so the user always sees what went wrong.
-    try {
-        // app.run returns its own status (1 for parse errors, 0 on
-        // successful dispatch). On successful dispatch, the action
-        // lambda's intended exit code lives in `action_rc` (cmdline lib
-        // discards it on its own). Surface the action's rc when app.run
-        // succeeded so e.g. `xlings install <bad-pkg>` returns non-zero
-        // to scripts and CI.
-        auto app_rc = app.run(argc, argv);
-        if (app_rc != 0) return app_rc;
-        return action_rc;
-    } catch (const std::filesystem::filesystem_error& e) {
-        log::error("filesystem error: {}", e.what());
-        if (!e.path1().empty()) log::error("  path: {}", e.path1().string());
-        log::error("  hint: this is likely a bug; please report at "
-                   "https://github.com/openxlings/xlings/issues");
-        return 1;
-    } catch (const std::exception& e) {
-        log::error("internal error: {}", e.what());
-        log::error("  hint: this is likely a bug; please report at "
-                   "https://github.com/openxlings/xlings/issues");
-        return 1;
-    } catch (...) {
-        log::error("internal error: unknown exception");
-        return 1;
-    }
-}
+export int run(int argc, char* argv[]);
 
 } // namespace xlings::cli
diff --git a/src/cli/spec.cpp b/src/cli/spec.cpp
new file mode 100644
index 00000000..c086eb6a
--- /dev/null
+++ b/src/cli/spec.cpp
@@ -0,0 +1,307 @@
+module xlings.cli.spec;
+
+import std;
+import xlings.libs.json;
+
+namespace xlings::cli::spec {
+
+const CommandSpec& root() {
+    static const CommandSpec value{
+        .name = "xlings",
+        .description = "Universal package management and SubOS environments",
+        .options = {
+            {"-h, --help", "Show help for the selected command"},
+            {"--version", "Show version"},
+            {"-y, --yes", "Skip confirmation prompts", true},
+            {"--agent", "Use stable plain-text output", true},
+            {"-v, --verbose", "Enable verbose output", true},
+            {"-q, --quiet", "Suppress non-essential output", true},
+        },
+        .children = {
+            {"install", "Install packages", {}, {{"packages", "Package names", false, true}},
+                {{"-g, --global", "Use global scope"}, {"-u, --use", "Activate installed version"}}, {}},
+            {"remove", "Remove a package", {}, {{"package", "Package name", true}, {"version", "Optional version", false}},
+                {{"-g, --global", "Use global scope"},
+                 {"--force", "Remove even if installed packages depend on it"}}, {}},
+            {"update", "Update package index or package", {}, {{"package", "Optional package", false}, {"version", "Optional version", false}}, {}, {}},
+            {"search", "Search for packages", {}, {{"keyword", "Search keyword", true}}, {}, {}},
+            {"list", "List installed packages", {}, {{"filter", "Filter pattern", false}},
+                {{"-a, --all", "Show every subos"}}, {}},
+            {"info", "Show package information", {}, {{"package", "Package name", true}, {"version", "Optional version", false}},
+                {{"--all-versions", "Show every available version"}}, {}},
+            {"why", "Show why a dependency resolved to the version it did", {},
+                {{"package", "Installed package name", true}, {"dep", "Optional dependency name", false}}, {}, {}},
+            {"use", "Switch tool version", {}, {{"target", "Tool name", true}, {"version", "Optional version", false}},
+                {{"-a, --all", "Show every subos"}, {"--strict", "Require a coherent release"}}, {}},
+            {"config", "Show or modify configuration", {}, {},
+                {{"--lang <LANG>", "Set language"}, {"--mirror <MIRROR>", "Set mirror"}, {"--add-xpkg <FILE>", "Add package recipe"}, {"--index-repo <NS:URL>", "Add index repository"}}, {}},
+            {"subos", "Manage SubOS environments", {}, {}, {}, {
+                {"new", "Create a SubOS", {}, {{"name", "SubOS name", true}}, {{"--storage <MODE>", "shared, tmpfs or image"}, {"--image-size <SIZE>", "Image size"}, {"--from <SOURCE>", "Fork source"}, {"--runtime <SPEC>", "Runtime binding, e.g. glibc@2.44"}}, {}},
+                {"use", "Enter a SubOS", {}, {{"name", "Optional SubOS name; omit to list candidates", false}}, {{"--global", "Persist the active SubOS"}, {"--shell [KIND]", "Emit shell activation code"}, {"--sandbox [BACKEND]", "Enable sandbox (bwrap or proot on Linux)"}, {"--cmd <COMMAND>", "Run one command"}, {"--keep", "Keep the namespace keeper"}, {"--no-keep", "Disable the namespace keeper"}, {"--ttl <SECONDS>", "Keeper idle timeout"}, {"--gpu", "Expose GPU devices (bwrap only)"}}, {}},
+                {"list", "List SubOS environments", {"ls"}, {}, {}, {}},
+                {"remove", "Remove a SubOS", {"rm"}, {{"name", "SubOS name", true}}, {}, {}},
+                {"info", "Show SubOS details", {"i"}, {{"name", "Optional SubOS", false}}, {}, {}},
+                {"stop", "Stop a SubOS keeper", {}, {{"name", "SubOS name", true}}, {}, {}},
+            }},
+            {"self", "Manage xlings itself", {}, {}, {}, {
+                {"install", "Install xlings", {}, {}, {}, {}},
+                {"uninstall", "Uninstall xlings", {}, {}, {{"-y, --yes", "Skip confirmation"}, {"--keep-data", "Keep data"}, {"--dry-run", "Preview"}}, {}},
+                {"init", "Initialize directories", {}, {}, {}, {}},
+                {"update", "Update xlings", {}, {}, {}, {}},
+                {"config", "Show configuration", {}, {}, {}, {}},
+                {"clean", "Clean cache", {}, {}, {{"--dry-run", "Preview"}}, {}},
+                {"migrate", "Migrate old layout", {}, {}, {}, {}},
+                {"doctor", "Verify installation", {}, {}, {{"--deep", "Audit package payloads and runtime functionality"}, {"--scope <PACKAGE[@VERSION]>", "Limit deep payload/runtime audit to one local package coordinate"}, {"--fix", "Repair (implies --deep)"}, {"--dry-run", "Preview repairs without changing detection depth"}, {"--all", "Show all findings"}, {"--reset-metadata", "Discard unreadable metadata"}}, {}},
+            }},
+            {"script", "Run an xlings script", {}, {{"script-file", "Script path", true}, {"args", "Script arguments", false, true}}, {}, {}},
+            {"interface", "Use the NDJSON interface", {}, {{"capability", "Capability name", false}}, {{"--args <JSON>", "Capability arguments"}, {"--args-file <PATH>", "Read capability arguments from a file"}, {"--list", "List capabilities"}, {"--version", "Show protocol version"}}, {}},
+            {"index", "Inspect and select package index snapshots", {}, {}, {}, {
+                {"list", "List published index snapshots", {"ls"}, {{"name", "Optional index source", false}},
+                    {{"--json", "Machine-readable output"}}, {}},
+                {"use", "Pin an index source to a snapshot", {}, {{"name", "Index source", true}, {"version", "Snapshot version, or 'latest'", true}}, {}, {}},
+            }},
+            {"agent", "Agent integration", {}, {}, {}, {
+                {"skills", "List or show built-in skills", {}, {{"name", "Optional skill name", false}}, {}, {}},
+            }},
+            {"profile", "Manage profile configuration", {}, {}, {}, {
+                {"list", "List recorded generations", {}, {}, {}, {}},
+                {"commit", "Record the active generation", {}, {{"reason", "Optional reason", false}}, {}, {}},
+                {"rollback", "Restore a recorded generation", {}, {{"generation", "Generation number", true}}, {}, {}},
+            }},
+        },
+    };
+    return value;
+}
+
+const CommandSpec* find(std::span<const std::string_view> path) {
+    const CommandSpec* current = &root();
+    for (const auto part : path) {
+        const auto found = std::ranges::find_if(current->children,
+            [&](const CommandSpec& child) {
+                return child.name == part
+                    || std::ranges::find(child.aliases, part) != child.aliases.end();
+            });
+        if (found == current->children.end()) return nullptr;
+        current = &*found;
+    }
+    return current;
+}
+
+std::vector<std::string_view> option_aliases(const OptionSpec& option) {
+    std::vector<std::string_view> aliases;
+    for (const auto piece : std::views::split(option.syntax, ',')) {
+        auto alias = std::string_view{piece.begin(), piece.end()};
+        while (!alias.empty() && alias.front() == ' ') alias.remove_prefix(1);
+        alias = alias.substr(0, alias.find_first_of(" <[="));
+        if (!alias.empty()) aliases.push_back(alias);
+    }
+    return aliases;
+}
+
+const std::vector<const OptionSpec*>& global_options() {
+    static const std::vector<const OptionSpec*> value = [] {
+        std::vector<const OptionSpec*> options;
+        for (const auto& option : root().options) {
+            if (option.global) options.push_back(&option);
+        }
+        return options;
+    }();
+    return value;
+}
+
+bool is_global_option(std::string_view token) {
+    const auto name = token.substr(0, token.find('='));
+    for (const auto* option : global_options()) {
+        for (const auto alias : option_aliases(*option)) {
+            if (alias == name) return true;
+        }
+    }
+    return false;
+}
+
+namespace detail_ {
+
+std::size_t free_tokens_(std::span<const std::string_view> argv,
+                         std::size_t from) {
+    std::size_t count = 0;
+    for (std::size_t i = from; i < argv.size(); ++i) {
+        if (!argv[i].starts_with('-')) ++count;
+    }
+    return count;
+}
+
+std::expected<ParsedManualArgs, CliError> validate_(
+    const CommandSpec& command,
+    std::span<const std::string_view> argv,
+    // Full invocation path, so a diagnostic names the command the user typed.
+    // `command.name` alone turns `xlings subos use` into `xlings use` -- a
+    // different, existing command -- and `xlings self doctor` into
+    // `xlings doctor`, which does not exist at all.
+    const std::string& path) {
+    if (!command.children.empty() && !argv.empty()
+        && !argv.front().starts_with('-')) {
+        if (const auto* child = find(std::array<std::string_view, 2>{
+                command.name, argv.front()})) {
+            return validate_(*child, argv.subspan(1),
+                             path + " " + std::string(argv.front()));
+        }
+        return std::unexpected(CliError{std::format(
+            "unknown subcommand for `{}`: {}", path, argv.front())});
+    }
+
+    const auto required = static_cast<std::size_t>(
+        std::ranges::count_if(command.arguments,
+            [](const auto& argument) { return argument.required; }));
+
+    ParsedManualArgs parsed;
+    for (std::size_t i = 0; i < argv.size(); ++i) {
+        const auto token = argv[i];
+        if (!token.starts_with('-')) {
+            parsed.positional.emplace_back(token);
+            continue;
+        }
+
+        const auto equals = token.find('=');
+        const auto optionName = token.substr(0, equals);
+        const OptionSpec* matched = nullptr;
+        for (const auto& option : command.options) {
+            for (const auto alias : option_aliases(option)) {
+                if (alias == optionName) { matched = &option; break; }
+            }
+            if (matched) break;
+        }
+        if (!matched) {
+            for (const auto* option : global_options()) {
+                for (const auto alias : option_aliases(*option)) {
+                    if (alias == optionName) { matched = option; break; }
+                }
+                if (matched) break;
+            }
+        }
+        if (!matched) {
+            return std::unexpected(CliError{std::format(
+                "unknown option for `{}`: {}", path, token)});
+        }
+        parsed.options.insert(std::string(optionName));
+
+        const bool requiresValue = matched->syntax.contains('<');
+        const bool optionalValue = matched->syntax.contains('[');
+        if (equals != std::string_view::npos) {
+            if (token.substr(equals + 1).empty()) {
+                return std::unexpected(CliError{std::format(
+                    "missing value for option: {}", optionName)});
+            }
+            continue;
+        }
+        if (requiresValue) {
+            if (i + 1 >= argv.size() || argv[i + 1].starts_with('-')) {
+                return std::unexpected(CliError{std::format(
+                    "missing value for option: {}", optionName)});
+            }
+            ++i;
+            continue;
+        }
+        if (optionalValue && i + 1 < argv.size()
+            && !argv[i + 1].starts_with('-')) {
+            // Take the next token as this option's value unless a required
+            // positional still needs it. Deciding by a whitelist of known
+            // values instead would mean every new shell kind, sandbox backend
+            // or storage mode the parser learns silently reappears here as a
+            // "surplus positional argument" -- which is exactly how
+            // `--shell powershell` became an exit-2 error while the parser
+            // that runs it accepted the word.
+            if (parsed.positional.size()
+                    + detail_::free_tokens_(argv, i + 2) >= required) {
+                ++i;
+            }
+        }
+    }
+
+    const bool variadic = !command.arguments.empty()
+        && command.arguments.back().variadic;
+    if (parsed.positional.size() < required) {
+        return std::unexpected(CliError{std::format(
+            "missing argument for `{}`", path)});
+    }
+    if (!variadic && parsed.positional.size() > command.arguments.size()) {
+        return std::unexpected(CliError{std::format(
+            "surplus positional argument for `{}`: {}", path,
+            parsed.positional[command.arguments.size()])});
+    }
+    return parsed;
+}
+
+}
+
+std::expected<ParsedManualArgs, CliError> validate_manual_argv(
+    const CommandSpec& command,
+    std::span<const std::string_view> argv) {
+    return detail_::validate_(command, argv, "xlings " + command.name);
+}
+
+nlohmann::json help_json(const CommandSpec& command) {
+    nlohmann::json value;
+    value["name"] = command.name;
+    value["description"] = command.description;
+    value["arguments"] = nlohmann::json::array();
+    value["options"] = nlohmann::json::array();
+    value["subcommands"] = nlohmann::json::array();
+    for (const auto& argument : command.arguments) {
+        value["arguments"].push_back({{"name", argument.name},
+            {"description", argument.description}, {"required", argument.required},
+            {"variadic", argument.variadic}});
+    }
+    for (const auto& option : command.options) {
+        value["options"].push_back({{"syntax", option.syntax},
+                                     {"description", option.description},
+                                     {"global", option.global}});
+    }
+    for (const auto& child : command.children) {
+        value["subcommands"].push_back(help_json(child));
+    }
+    return value;
+}
+
+nlohmann::json reference_json() { return help_json(root()); }
+
+std::string agent_reference() {
+    // The global options come first and on their own. They used to be spelled
+    // out in every hand-written example (`xlings install <pkg> --yes --agent`);
+    // a per-command listing that skips the root node drops them entirely, and
+    // an agent reading only this section would never learn the two flags the
+    // rules above tell it to always pass.
+    std::string output = "GLOBAL OPTIONS — valid on every command\n";
+    for (const auto* option : global_options()) {
+        output += "  " + option->syntax + "\n    " + option->description + "\n";
+    }
+    output += "\n";
+
+    const auto append = [&](this const auto& self, const CommandSpec& command,
+                            std::string path) -> void {
+        if (command.name != "xlings") {
+            if (!path.empty()) path += " ";
+            path += command.name;
+            output += "  xlings " + path;
+            for (const auto& argument : command.arguments) {
+                output += argument.required ? " <" : " [";
+                output += argument.name;
+                output += argument.required ? ">" : "]";
+                if (argument.variadic) output += "...";
+            }
+            output += "\n    " + command.description + "\n";
+            if (!command.options.empty()) {
+                output += "    options: ";
+                for (std::size_t i = 0; i < command.options.size(); ++i) {
+                    if (i != 0) output += "; ";
+                    output += command.options[i].syntax;
+                }
+                output += "\n";
+            }
+        }
+        for (const auto& child : command.children) self(child, path);
+    };
+    append(root(), {});
+    return output;
+}
+
+}
diff --git a/src/cli/spec.cppm b/src/cli/spec.cppm
index 1cf52c03..f3e628de 100644
--- a/src/cli/spec.cppm
+++ b/src/cli/spec.cppm
@@ -35,87 +35,9 @@ struct CommandSpec {
     std::vector<CommandSpec> children;
 };
 
-const CommandSpec& root() {
-    static const CommandSpec value{
-        .name = "xlings",
-        .description = "Universal package management and SubOS environments",
-        .options = {
-            {"-h, --help", "Show help for the selected command"},
-            {"--version", "Show version"},
-            {"-y, --yes", "Skip confirmation prompts", true},
-            {"--agent", "Use stable plain-text output", true},
-            {"-v, --verbose", "Enable verbose output", true},
-            {"-q, --quiet", "Suppress non-essential output", true},
-        },
-        .children = {
-            {"install", "Install packages", {}, {{"packages", "Package names", false, true}},
-                {{"-g, --global", "Use global scope"}, {"-u, --use", "Activate installed version"}}, {}},
-            {"remove", "Remove a package", {}, {{"package", "Package name", true}, {"version", "Optional version", false}},
-                {{"-g, --global", "Use global scope"},
-                 {"--force", "Remove even if installed packages depend on it"}}, {}},
-            {"update", "Update package index or package", {}, {{"package", "Optional package", false}, {"version", "Optional version", false}}, {}, {}},
-            {"search", "Search for packages", {}, {{"keyword", "Search keyword", true}}, {}, {}},
-            {"list", "List installed packages", {}, {{"filter", "Filter pattern", false}},
-                {{"-a, --all", "Show every subos"}}, {}},
-            {"info", "Show package information", {}, {{"package", "Package name", true}, {"version", "Optional version", false}},
-                {{"--all-versions", "Show every available version"}}, {}},
-            {"why", "Show why a dependency resolved to the version it did", {},
-                {{"package", "Installed package name", true}, {"dep", "Optional dependency name", false}}, {}, {}},
-            {"use", "Switch tool version", {}, {{"target", "Tool name", true}, {"version", "Optional version", false}},
-                {{"-a, --all", "Show every subos"}, {"--strict", "Require a coherent release"}}, {}},
-            {"config", "Show or modify configuration", {}, {},
-                {{"--lang <LANG>", "Set language"}, {"--mirror <MIRROR>", "Set mirror"}, {"--add-xpkg <FILE>", "Add package recipe"}, {"--index-repo <NS:URL>", "Add index repository"}}, {}},
-            {"subos", "Manage SubOS environments", {}, {}, {}, {
-                {"new", "Create a SubOS", {}, {{"name", "SubOS name", true}}, {{"--storage <MODE>", "shared, tmpfs or image"}, {"--image-size <SIZE>", "Image size"}, {"--from <SOURCE>", "Fork source"}, {"--runtime <SPEC>", "Runtime binding, e.g. glibc@2.44"}}, {}},
-                {"use", "Enter a SubOS", {}, {{"name", "Optional SubOS name; omit to list candidates", false}}, {{"--global", "Persist the active SubOS"}, {"--shell [KIND]", "Emit shell activation code"}, {"--sandbox [BACKEND]", "Enable sandbox (bwrap or proot on Linux)"}, {"--cmd <COMMAND>", "Run one command"}, {"--keep", "Keep the namespace keeper"}, {"--no-keep", "Disable the namespace keeper"}, {"--ttl <SECONDS>", "Keeper idle timeout"}, {"--gpu", "Expose GPU devices (bwrap only)"}}, {}},
-                {"list", "List SubOS environments", {"ls"}, {}, {}, {}},
-                {"remove", "Remove a SubOS", {"rm"}, {{"name", "SubOS name", true}}, {}, {}},
-                {"info", "Show SubOS details", {"i"}, {{"name", "Optional SubOS", false}}, {}, {}},
-                {"stop", "Stop a SubOS keeper", {}, {{"name", "SubOS name", true}}, {}, {}},
-            }},
-            {"self", "Manage xlings itself", {}, {}, {}, {
-                {"install", "Install xlings", {}, {}, {}, {}},
-                {"uninstall", "Uninstall xlings", {}, {}, {{"-y, --yes", "Skip confirmation"}, {"--keep-data", "Keep data"}, {"--dry-run", "Preview"}}, {}},
-                {"init", "Initialize directories", {}, {}, {}, {}},
-                {"update", "Update xlings", {}, {}, {}, {}},
-                {"config", "Show configuration", {}, {}, {}, {}},
-                {"clean", "Clean cache", {}, {}, {{"--dry-run", "Preview"}}, {}},
-                {"migrate", "Migrate old layout", {}, {}, {}, {}},
-                {"doctor", "Verify installation", {}, {}, {{"--deep", "Audit package payloads and runtime functionality"}, {"--scope <PACKAGE[@VERSION]>", "Limit deep payload/runtime audit to one local package coordinate"}, {"--fix", "Repair (implies --deep)"}, {"--dry-run", "Preview repairs without changing detection depth"}, {"--all", "Show all findings"}, {"--reset-metadata", "Discard unreadable metadata"}}, {}},
-            }},
-            {"script", "Run an xlings script", {}, {{"script-file", "Script path", true}, {"args", "Script arguments", false, true}}, {}, {}},
-            {"interface", "Use the NDJSON interface", {}, {{"capability", "Capability name", false}}, {{"--args <JSON>", "Capability arguments"}, {"--args-file <PATH>", "Read capability arguments from a file"}, {"--list", "List capabilities"}, {"--version", "Show protocol version"}}, {}},
-            {"index", "Inspect and select package index snapshots", {}, {}, {}, {
-                {"list", "List published index snapshots", {"ls"}, {{"name", "Optional index source", false}},
-                    {{"--json", "Machine-readable output"}}, {}},
-                {"use", "Pin an index source to a snapshot", {}, {{"name", "Index source", true}, {"version", "Snapshot version, or 'latest'", true}}, {}, {}},
-            }},
-            {"agent", "Agent integration", {}, {}, {}, {
-                {"skills", "List or show built-in skills", {}, {{"name", "Optional skill name", false}}, {}, {}},
-            }},
-            {"profile", "Manage profile configuration", {}, {}, {}, {
-                {"list", "List recorded generations", {}, {}, {}, {}},
-                {"commit", "Record the active generation", {}, {{"reason", "Optional reason", false}}, {}, {}},
-                {"rollback", "Restore a recorded generation", {}, {{"generation", "Generation number", true}}, {}, {}},
-            }},
-        },
-    };
-    return value;
-}
+const CommandSpec& root();
 
-const CommandSpec* find(std::span<const std::string_view> path) {
-    const CommandSpec* current = &root();
-    for (const auto part : path) {
-        const auto found = std::ranges::find_if(current->children,
-            [&](const CommandSpec& child) {
-                return child.name == part
-                    || std::ranges::find(child.aliases, part) != child.aliases.end();
-            });
-        if (found == current->children.end()) return nullptr;
-        current = &*found;
-    }
-    return current;
-}
+const CommandSpec* find(std::span<const std::string_view> path);
 
 struct ParsedManualArgs {
     std::vector<std::string> positional;
@@ -127,53 +49,21 @@ struct CliError {
 };
 
 // `-g, --global` / `--ttl <SECONDS>` -> {"-g", "--global"} / {"--ttl"}.
-std::vector<std::string_view> option_aliases(const OptionSpec& option) {
-    std::vector<std::string_view> aliases;
-    for (const auto piece : std::views::split(option.syntax, ',')) {
-        auto alias = std::string_view{piece.begin(), piece.end()};
-        while (!alias.empty() && alias.front() == ' ') alias.remove_prefix(1);
-        alias = alias.substr(0, alias.find_first_of(" <[="));
-        if (!alias.empty()) aliases.push_back(alias);
-    }
-    return aliases;
-}
+std::vector<std::string_view> option_aliases(const OptionSpec& option);
 
 // The subset of root's options every command accepts. Kept as a view over
 // root() rather than a second list so `--help`, the generated reference and
 // this predicate cannot disagree about what "global" means.
-const std::vector<const OptionSpec*>& global_options() {
-    static const std::vector<const OptionSpec*> value = [] {
-        std::vector<const OptionSpec*> options;
-        for (const auto& option : root().options) {
-            if (option.global) options.push_back(&option);
-        }
-        return options;
-    }();
-    return value;
-}
+const std::vector<const OptionSpec*>& global_options();
 
-bool is_global_option(std::string_view token) {
-    const auto name = token.substr(0, token.find('='));
-    for (const auto* option : global_options()) {
-        for (const auto alias : option_aliases(*option)) {
-            if (alias == name) return true;
-        }
-    }
-    return false;
-}
+bool is_global_option(std::string_view token);
 
 namespace detail_ {
 
 // Non-flag tokens from `from` onward. Used to decide whether an optional
 // value may eat the next token or whether a required positional still needs it.
 std::size_t free_tokens_(std::span<const std::string_view> argv,
-                         std::size_t from) {
-    std::size_t count = 0;
-    for (std::size_t i = from; i < argv.size(); ++i) {
-        if (!argv[i].starts_with('-')) ++count;
-    }
-    return count;
-}
+                         std::size_t from);
 
 std::expected<ParsedManualArgs, CliError> validate_(
     const CommandSpec& command,
@@ -182,171 +72,18 @@ std::expected<ParsedManualArgs, CliError> validate_(
     // `command.name` alone turns `xlings subos use` into `xlings use` -- a
     // different, existing command -- and `xlings self doctor` into
     // `xlings doctor`, which does not exist at all.
-    const std::string& path) {
-    if (!command.children.empty() && !argv.empty()
-        && !argv.front().starts_with('-')) {
-        if (const auto* child = find(std::array<std::string_view, 2>{
-                command.name, argv.front()})) {
-            return validate_(*child, argv.subspan(1),
-                             path + " " + std::string(argv.front()));
-        }
-        return std::unexpected(CliError{std::format(
-            "unknown subcommand for `{}`: {}", path, argv.front())});
-    }
-
-    const auto required = static_cast<std::size_t>(
-        std::ranges::count_if(command.arguments,
-            [](const auto& argument) { return argument.required; }));
-
-    ParsedManualArgs parsed;
-    for (std::size_t i = 0; i < argv.size(); ++i) {
-        const auto token = argv[i];
-        if (!token.starts_with('-')) {
-            parsed.positional.emplace_back(token);
-            continue;
-        }
-
-        const auto equals = token.find('=');
-        const auto optionName = token.substr(0, equals);
-        const OptionSpec* matched = nullptr;
-        for (const auto& option : command.options) {
-            for (const auto alias : option_aliases(option)) {
-                if (alias == optionName) { matched = &option; break; }
-            }
-            if (matched) break;
-        }
-        if (!matched) {
-            for (const auto* option : global_options()) {
-                for (const auto alias : option_aliases(*option)) {
-                    if (alias == optionName) { matched = option; break; }
-                }
-                if (matched) break;
-            }
-        }
-        if (!matched) {
-            return std::unexpected(CliError{std::format(
-                "unknown option for `{}`: {}", path, token)});
-        }
-        parsed.options.insert(std::string(optionName));
-
-        const bool requiresValue = matched->syntax.contains('<');
-        const bool optionalValue = matched->syntax.contains('[');
-        if (equals != std::string_view::npos) {
-            if (token.substr(equals + 1).empty()) {
-                return std::unexpected(CliError{std::format(
-                    "missing value for option: {}", optionName)});
-            }
-            continue;
-        }
-        if (requiresValue) {
-            if (i + 1 >= argv.size() || argv[i + 1].starts_with('-')) {
-                return std::unexpected(CliError{std::format(
-                    "missing value for option: {}", optionName)});
-            }
-            ++i;
-            continue;
-        }
-        if (optionalValue && i + 1 < argv.size()
-            && !argv[i + 1].starts_with('-')) {
-            // Take the next token as this option's value unless a required
-            // positional still needs it. Deciding by a whitelist of known
-            // values instead would mean every new shell kind, sandbox backend
-            // or storage mode the parser learns silently reappears here as a
-            // "surplus positional argument" -- which is exactly how
-            // `--shell powershell` became an exit-2 error while the parser
-            // that runs it accepted the word.
-            if (parsed.positional.size()
-                    + detail_::free_tokens_(argv, i + 2) >= required) {
-                ++i;
-            }
-        }
-    }
-
-    const bool variadic = !command.arguments.empty()
-        && command.arguments.back().variadic;
-    if (parsed.positional.size() < required) {
-        return std::unexpected(CliError{std::format(
-            "missing argument for `{}`", path)});
-    }
-    if (!variadic && parsed.positional.size() > command.arguments.size()) {
-        return std::unexpected(CliError{std::format(
-            "surplus positional argument for `{}`: {}", path,
-            parsed.positional[command.arguments.size()])});
-    }
-    return parsed;
-}
+    const std::string& path);
 
 }  // namespace detail_
 
 std::expected<ParsedManualArgs, CliError> validate_manual_argv(
     const CommandSpec& command,
-    std::span<const std::string_view> argv) {
-    return detail_::validate_(command, argv, "xlings " + command.name);
-}
-
-nlohmann::json help_json(const CommandSpec& command) {
-    nlohmann::json value;
-    value["name"] = command.name;
-    value["description"] = command.description;
-    value["arguments"] = nlohmann::json::array();
-    value["options"] = nlohmann::json::array();
-    value["subcommands"] = nlohmann::json::array();
-    for (const auto& argument : command.arguments) {
-        value["arguments"].push_back({{"name", argument.name},
-            {"description", argument.description}, {"required", argument.required},
-            {"variadic", argument.variadic}});
-    }
-    for (const auto& option : command.options) {
-        value["options"].push_back({{"syntax", option.syntax},
-                                     {"description", option.description},
-                                     {"global", option.global}});
-    }
-    for (const auto& child : command.children) {
-        value["subcommands"].push_back(help_json(child));
-    }
-    return value;
-}
+    std::span<const std::string_view> argv);
 
-nlohmann::json reference_json() { return help_json(root()); }
+nlohmann::json help_json(const CommandSpec& command);
 
-std::string agent_reference() {
-    // The global options come first and on their own. They used to be spelled
-    // out in every hand-written example (`xlings install <pkg> --yes --agent`);
-    // a per-command listing that skips the root node drops them entirely, and
-    // an agent reading only this section would never learn the two flags the
-    // rules above tell it to always pass.
-    std::string output = "GLOBAL OPTIONS — valid on every command\n";
-    for (const auto* option : global_options()) {
-        output += "  " + option->syntax + "\n    " + option->description + "\n";
-    }
-    output += "\n";
+nlohmann::json reference_json();
 
-    const auto append = [&](this const auto& self, const CommandSpec& command,
-                            std::string path) -> void {
-        if (command.name != "xlings") {
-            if (!path.empty()) path += " ";
-            path += command.name;
-            output += "  xlings " + path;
-            for (const auto& argument : command.arguments) {
-                output += argument.required ? " <" : " [";
-                output += argument.name;
-                output += argument.required ? ">" : "]";
-                if (argument.variadic) output += "...";
-            }
-            output += "\n    " + command.description + "\n";
-            if (!command.options.empty()) {
-                output += "    options: ";
-                for (std::size_t i = 0; i < command.options.size(); ++i) {
-                    if (i != 0) output += "; ";
-                    output += command.options[i].syntax;
-                }
-                output += "\n";
-            }
-        }
-        for (const auto& child : command.children) self(child, path);
-    };
-    append(root(), {});
-    return output;
-}
+std::string agent_reference();
 
 }  // namespace xlings::cli::spec
diff --git a/src/core/closure_check.cppm b/src/core/closure_check.cppm
index 31cb853c..36f5bb87 100644
--- a/src/core/closure_check.cppm
+++ b/src/core/closure_check.cppm
@@ -4,7 +4,6 @@ export module xlings.core.closure_check;
 
 import std;
 import xlings.platform;
-import xlings.core.log;
 import xlings.core.version_order;
 import xlings.core.elf_same_source;
 
diff --git a/src/core/cmdprocessor.cpp b/src/core/cmdprocessor.cpp
new file mode 100644
index 00000000..1cd20cb4
--- /dev/null
+++ b/src/core/cmdprocessor.cpp
@@ -0,0 +1,341 @@
+module;
+#include <cstdio>
+
+module xlings.core.cmdprocessor;
+
+import std;
+import xlings.core.log;
+import xlings.libs.json;
+import xlings.core.config;
+import xlings.core.subos;
+import xlings.platform;
+import xlings.runtime;
+import xlings.core.xself;
+import mcpplibs.xpkg.executor;
+
+namespace xlings::cmdprocessor {
+
+// Resolve the xmake project directory that contains xim task definition.
+// The xim task is defined in a xmake.lua that lives next to an xim/ directory
+// (release/installed layout).  The source tree keeps xim code under core/xim/
+// which is NOT a valid -P target; in that case we fall through to the default
+// installed home (~/.xlings) which always has the correct layout.
+std::filesystem::path find_xim_project_dir() {
+    namespace fs = std::filesystem;
+
+    auto is_xim_project = [](const fs::path& dir) {
+        return fs::exists(dir / "xim") && fs::exists(dir / "xmake.lua");
+    };
+
+    // 1. Prefer layout next to the running binary (multi-version / release package)
+    auto exePath = platform::get_executable_path();
+    if (!exePath.empty()) {
+        auto candidate = exePath.parent_path().parent_path();
+        if (is_xim_project(candidate)) {
+            return candidate;
+        }
+    }
+
+    // 2. $XLINGS_HOME (installed)
+    auto homeDir = Config::paths().homeDir;
+    if (is_xim_project(homeDir)) {
+        return homeDir;
+    }
+
+    // 3. Default fallback (~/.xlings) when homeDir is the source tree
+    auto defaultHome = std::filesystem::path(platform::get_home_dir()) / ".xlings";
+    if (is_xim_project(defaultHome)) {
+        return defaultHome;
+    }
+
+    return homeDir;
+}
+
+int xim_exec(const std::string& flags, int argc, char* argv[], int startIdx = 2) {
+    auto projectDir = find_xim_project_dir();
+    std::string cmd = "xmake xim -P \"" + projectDir.string() + "\"";
+    if (!flags.empty()) {
+        cmd += " " + flags;
+    }
+    cmd += " --";
+    for (int i = startIdx; i < argc; ++i) {
+        cmd += " ";
+        cmd += argv[i];
+    }
+    return platform::exec(cmd);
+}
+
+int xvm_exec(const std::string& subcommand, int argc, char* argv[], int startIdx = 2) {
+    std::string cmd = "xvm " + subcommand;
+    for (int i = startIdx; i < argc; ++i) {
+        cmd += " ";
+        cmd += argv[i];
+    }
+    return platform::exec(cmd);
+}
+
+std::filesystem::path find_project_xlings_json() {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+
+    auto cwd = fs::current_path(ec);
+    if (ec) return {};
+    auto homeDir = Config::paths().homeDir;
+
+    fs::path cur = cwd;
+    while (!cur.empty()) {
+        auto cfg = cur / ".xlings.json";
+        if (fs::exists(cfg, ec) && fs::is_regular_file(cfg, ec)) {
+            auto curNorm = fs::weakly_canonical(cur, ec);
+            if (!ec) {
+                auto homeNorm = fs::weakly_canonical(homeDir, ec);
+                if (!ec && curNorm == homeNorm) {
+                    // Skip global config at $XLINGS_HOME/.xlings.json
+                } else {
+                    return cfg;
+                }
+            } else {
+                return cfg;
+            }
+        }
+
+        auto parent = cur.parent_path();
+        if (parent == cur) break;
+        cur = parent;
+    }
+    return {};
+}
+
+std::filesystem::path find_project_legacy_xlings_lua() {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+
+    auto cwd = fs::current_path(ec);
+    if (ec) return {};
+    auto homeDir = Config::paths().homeDir;
+
+    fs::path cur = cwd;
+    while (!cur.empty()) {
+        auto cfg = cur / "config.xlings";
+        if (fs::exists(cfg, ec) && fs::is_regular_file(cfg, ec)) {
+            auto curNorm = fs::weakly_canonical(cur, ec);
+            if (!ec) {
+                auto homeNorm = fs::weakly_canonical(homeDir, ec);
+                if (!ec && curNorm == homeNorm) {
+                    // Skip global config under $XLINGS_HOME
+                } else {
+                    return cfg;
+                }
+            } else {
+                return cfg;
+            }
+        }
+
+        auto parent = cur.parent_path();
+        if (parent == cur) break;
+        cur = parent;
+    }
+    return {};
+}
+
+int install_targets_from_list(const std::vector<std::string>& targets) {
+    auto& p = Config::paths();
+    int rc = 0;
+    for (const auto& target : targets) {
+        if (target.empty()) continue;
+        std::string cmd = std::format(
+            "xmake xim -P \"{}\" -- {} -y",
+            p.homeDir.string(),
+            target
+        );
+        auto dep_rc = platform::exec(cmd);
+        if (dep_rc != 0) {
+            rc = dep_rc;
+            break;
+        }
+    }
+    return rc;
+}
+
+int install_from_legacy_config_xlings_via_xim(const std::filesystem::path& cfg) {
+    auto projectDir = find_xim_project_dir();
+    std::string cmd = "xmake xim -P \"" + projectDir.string() + "\" -- --install-config-xlings \"" + cfg.string() + "\" -y";
+    return platform::exec(cmd);
+}
+
+int install_from_project_config() {
+    auto cfg = find_project_xlings_json();
+    if (!cfg.empty()) {
+        nlohmann::json json;
+        try {
+            auto content = platform::read_file_to_string(cfg.string());
+            json = nlohmann::json::parse(content, nullptr, false);
+        } catch (...) {
+            json = nlohmann::json::object();
+        }
+        if (json.is_discarded() || !json.is_object()) {
+            log::error("Invalid JSON in {}", cfg.string());
+            return 1;
+        }
+        if (!json.contains("deps") || !json["deps"].is_array()) {
+            log::error("Missing or invalid `deps` array in {}", cfg.string());
+            return 1;
+        }
+
+        std::vector<std::string> targets;
+        for (const auto& dep : json["deps"]) {
+            if (!dep.is_string()) continue;
+            auto target = dep.get<std::string>();
+            if (!target.empty()) targets.push_back(std::move(target));
+        }
+        return install_targets_from_list(targets);
+    }
+
+    // Forward-compat for legacy project config.xlings (Lua):
+    // delegate loading/parsing/installing to xim (Lua runtime).
+    auto legacyCfg = find_project_legacy_xlings_lua();
+    if (!legacyCfg.empty()) {
+        return install_from_legacy_config_xlings_via_xim(legacyCfg);
+    }
+
+    std::println("Tip: create <project>/.xlings.json with deps (preferred), or use config.xlings xim table, or run `xlings install <package>`");
+    return 0;
+}
+
+CommandProcessor create_processor() {
+    return CommandProcessor{}
+        .add("install", "install package/tool",
+            [](int argc, char* argv[]) {
+                if (argc <= 2) {
+                    return install_from_project_config();
+                }
+                return xim_exec("", argc, argv);
+            },
+            "xlings install [package[@version]]")
+        .add("remove", "remove package/tool",
+            [](int argc, char* argv[]) {
+                return xim_exec("", argc, argv, 1);
+            },
+            "xlings remove <package>")
+        .add("update", "update package/tool",
+            [](int argc, char* argv[]) {
+                return xim_exec("", argc, argv, 1);
+            },
+            "xlings update <package>")
+        .add("search", "search for packages",
+            [](int argc, char* argv[]) {
+                return xim_exec("", argc, argv, 1);
+            },
+            "xlings search <keyword>")
+        .add("use", "switch version of a tool",
+            [](int argc, char* argv[]) {
+                if (argc < 3) {
+                    std::println("Usage: xlings use <target> [version]");
+                    return 1;
+                }
+                if (argc >= 4) {
+                    return xvm_exec("use", argc, argv);
+                }
+                return xvm_exec("list", argc, argv);
+            },
+            "xlings use <target> [version]")
+        .add("info", "show tool info",
+            [](int argc, char* argv[]) {
+                if (argc < 3) {
+                    std::println("Usage: xlings info <target>");
+                    return 1;
+                }
+                return xvm_exec("info", argc, argv);
+            },
+            "xlings info <target>")
+        .add("config", "show xlings configuration",
+            [](int, char**) {
+                Config::print_paths();
+                return 0;
+            })
+        .add("subos", "manage sub-os environments",
+            [](int argc, char* argv[]) {
+                EventStream stream;
+                return subos::run(argc, argv, stream);
+            },
+            "xlings subos <new|use|list|ls|remove|rm|info|i> [name]")
+        .add("script", "run xpkg script",
+            [](int argc, char* argv[]) {
+                if (argc < 3) {
+                    std::println("Usage: xlings script <script-file> [args...]");
+                    return 1;
+                }
+                namespace fs = std::filesystem;
+                fs::path scriptFile = argv[2];
+                auto execResult = mcpplibs::xpkg::create_executor(scriptFile);
+                if (!execResult) {
+                    log::error("failed to load script: {}", execResult.error());
+                    return 1;
+                }
+                mcpplibs::xpkg::ExecutionContext ctx;
+                ctx.platform = std::string(platform::OS_NAME);
+                ctx.bin_dir = Config::paths().binDir;
+                ctx.subos_sysrootdir = Config::paths().subosDir.string();
+                ctx.run_dir = fs::current_path();
+                ctx.xpkg_dir = Config::paths().dataDir / "xpkgs";
+                for (int i = 3; i < argc; ++i) {
+                    ctx.args.emplace_back(argv[i]);
+                }
+                auto result = execResult->run_script(ctx);
+                if (!result.success) {
+                    log::error("script error: {}", result.error);
+                    return 1;
+                }
+                return 0;
+            },
+            "xlings script <script-file> [args...]")
+        .add("self", "self management (init/update/config/clean/migrate)",
+            [](int argc, char* argv[]) {
+                EventStream stream;
+                return xself::run(argc, argv, stream);
+            },
+            "xlings self [init|update|config|clean [--dry-run]|migrate|help]");
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::cmdprocessor {
+
+CommandProcessor& CommandProcessor::add(std::string name, std::string description, std::function<int(int argc, char* argv[])> func, std::string usage) {
+    if (usage.empty()) usage = std::format("xlings {}", name);
+    commands_.push_back({std::move(name), std::move(description),
+                        std::move(usage), std::move(func)});
+    return *this;
+}
+
+int CommandProcessor::run(int argc, char* argv[]) {
+    if (argc <= 1) return print_help();
+
+    std::string cmd = argv[1];
+    if (cmd == "help" || cmd == "--help" || cmd == "-h" || cmd == "--version") {
+        return print_help();
+    }
+
+    for (const auto& c : commands_) {
+        if (c.name == cmd) return c.func(argc, argv);
+    }
+
+    log::error("Unknown command: {}", cmd);
+    std::println(stdout, "Use 'xlings help' for usage information");
+    return 1;
+}
+
+int CommandProcessor::print_help() const {
+    std::println(stdout, "xlings version: {}\n", Info::VERSION);
+    std::println(stdout, "Usage: $ xlings [command] [target] [options]\n");
+    std::println(stdout, "Commands:");
+    for (const auto& c : commands_) {
+        std::println(stdout, "\t {:12}\t{}", c.name, c.description);
+    }
+    return 0;
+}
+
+} // namespace xlings::cmdprocessor
diff --git a/src/core/cmdprocessor.cppm b/src/core/cmdprocessor.cppm
index f9f812ac..2c691433 100644
--- a/src/core/cmdprocessor.cppm
+++ b/src/core/cmdprocessor.cppm
@@ -2,11 +2,8 @@ export module xlings.core.cmdprocessor;
 
 import std;
 
-import xlings.core.log;
-import xlings.libs.json;
 import xlings.core.config;
 import xlings.core.subos;
-import xlings.platform;
 import xlings.runtime;
 import xlings.core.xself;
 import mcpplibs.xpkg.executor;
@@ -24,324 +21,16 @@ class CommandProcessor {
 public:
     CommandProcessor& add(std::string name, std::string description,
                           std::function<int(int argc, char* argv[])> func,
-                          std::string usage = "") {
-        if (usage.empty()) usage = std::format("xlings {}", name);
-        commands_.push_back({std::move(name), std::move(description),
-                            std::move(usage), std::move(func)});
-        return *this;
-    }
+                          std::string usage = "");
 
-    int run(int argc, char* argv[]) {
-        if (argc <= 1) return print_help();
+    int run(int argc, char* argv[]);
 
-        std::string cmd = argv[1];
-        if (cmd == "help" || cmd == "--help" || cmd == "-h" || cmd == "--version") {
-            return print_help();
-        }
-
-        for (const auto& c : commands_) {
-            if (c.name == cmd) return c.func(argc, argv);
-        }
-
-        log::error("Unknown command: {}", cmd);
-        std::println("Use 'xlings help' for usage information");
-        return 1;
-    }
-
-    int print_help() const {
-        std::println("xlings version: {}\n", Info::VERSION);
-        std::println("Usage: $ xlings [command] [target] [options]\n");
-        std::println("Commands:");
-        for (const auto& c : commands_) {
-            std::println("\t {:12}\t{}", c.name, c.description);
-        }
-        return 0;
-    }
+    int print_help() const;
 
 private:
     std::vector<CommandInfo> commands_;
 };
 
-// Resolve the xmake project directory that contains xim task definition.
-// The xim task is defined in a xmake.lua that lives next to an xim/ directory
-// (release/installed layout).  The source tree keeps xim code under core/xim/
-// which is NOT a valid -P target; in that case we fall through to the default
-// installed home (~/.xlings) which always has the correct layout.
-std::filesystem::path find_xim_project_dir() {
-    namespace fs = std::filesystem;
-
-    auto is_xim_project = [](const fs::path& dir) {
-        return fs::exists(dir / "xim") && fs::exists(dir / "xmake.lua");
-    };
-
-    // 1. Prefer layout next to the running binary (multi-version / release package)
-    auto exePath = platform::get_executable_path();
-    if (!exePath.empty()) {
-        auto candidate = exePath.parent_path().parent_path();
-        if (is_xim_project(candidate)) {
-            return candidate;
-        }
-    }
-
-    // 2. $XLINGS_HOME (installed)
-    auto homeDir = Config::paths().homeDir;
-    if (is_xim_project(homeDir)) {
-        return homeDir;
-    }
-
-    // 3. Default fallback (~/.xlings) when homeDir is the source tree
-    auto defaultHome = std::filesystem::path(platform::get_home_dir()) / ".xlings";
-    if (is_xim_project(defaultHome)) {
-        return defaultHome;
-    }
-
-    return homeDir;
-}
-
-int xim_exec(const std::string& flags, int argc, char* argv[], int startIdx = 2) {
-    auto projectDir = find_xim_project_dir();
-    std::string cmd = "xmake xim -P \"" + projectDir.string() + "\"";
-    if (!flags.empty()) {
-        cmd += " " + flags;
-    }
-    cmd += " --";
-    for (int i = startIdx; i < argc; ++i) {
-        cmd += " ";
-        cmd += argv[i];
-    }
-    return platform::exec(cmd);
-}
-
-int xvm_exec(const std::string& subcommand, int argc, char* argv[], int startIdx = 2) {
-    std::string cmd = "xvm " + subcommand;
-    for (int i = startIdx; i < argc; ++i) {
-        cmd += " ";
-        cmd += argv[i];
-    }
-    return platform::exec(cmd);
-}
-
-std::filesystem::path find_project_xlings_json() {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-
-    auto cwd = fs::current_path(ec);
-    if (ec) return {};
-    auto homeDir = Config::paths().homeDir;
-
-    fs::path cur = cwd;
-    while (!cur.empty()) {
-        auto cfg = cur / ".xlings.json";
-        if (fs::exists(cfg, ec) && fs::is_regular_file(cfg, ec)) {
-            auto curNorm = fs::weakly_canonical(cur, ec);
-            if (!ec) {
-                auto homeNorm = fs::weakly_canonical(homeDir, ec);
-                if (!ec && curNorm == homeNorm) {
-                    // Skip global config at $XLINGS_HOME/.xlings.json
-                } else {
-                    return cfg;
-                }
-            } else {
-                return cfg;
-            }
-        }
-
-        auto parent = cur.parent_path();
-        if (parent == cur) break;
-        cur = parent;
-    }
-    return {};
-}
-
-std::filesystem::path find_project_legacy_xlings_lua() {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-
-    auto cwd = fs::current_path(ec);
-    if (ec) return {};
-    auto homeDir = Config::paths().homeDir;
-
-    fs::path cur = cwd;
-    while (!cur.empty()) {
-        auto cfg = cur / "config.xlings";
-        if (fs::exists(cfg, ec) && fs::is_regular_file(cfg, ec)) {
-            auto curNorm = fs::weakly_canonical(cur, ec);
-            if (!ec) {
-                auto homeNorm = fs::weakly_canonical(homeDir, ec);
-                if (!ec && curNorm == homeNorm) {
-                    // Skip global config under $XLINGS_HOME
-                } else {
-                    return cfg;
-                }
-            } else {
-                return cfg;
-            }
-        }
-
-        auto parent = cur.parent_path();
-        if (parent == cur) break;
-        cur = parent;
-    }
-    return {};
-}
-
-static int install_targets_from_list(const std::vector<std::string>& targets) {
-    auto& p = Config::paths();
-    int rc = 0;
-    for (const auto& target : targets) {
-        if (target.empty()) continue;
-        std::string cmd = std::format(
-            "xmake xim -P \"{}\" -- {} -y",
-            p.homeDir.string(),
-            target
-        );
-        auto dep_rc = platform::exec(cmd);
-        if (dep_rc != 0) {
-            rc = dep_rc;
-            break;
-        }
-    }
-    return rc;
-}
-
-static int install_from_legacy_config_xlings_via_xim(const std::filesystem::path& cfg) {
-    auto projectDir = find_xim_project_dir();
-    std::string cmd = "xmake xim -P \"" + projectDir.string() + "\" -- --install-config-xlings \"" + cfg.string() + "\" -y";
-    return platform::exec(cmd);
-}
-
-int install_from_project_config() {
-    auto cfg = find_project_xlings_json();
-    if (!cfg.empty()) {
-        nlohmann::json json;
-        try {
-            auto content = platform::read_file_to_string(cfg.string());
-            json = nlohmann::json::parse(content, nullptr, false);
-        } catch (...) {
-            json = nlohmann::json::object();
-        }
-        if (json.is_discarded() || !json.is_object()) {
-            log::error("Invalid JSON in {}", cfg.string());
-            return 1;
-        }
-        if (!json.contains("deps") || !json["deps"].is_array()) {
-            log::error("Missing or invalid `deps` array in {}", cfg.string());
-            return 1;
-        }
-
-        std::vector<std::string> targets;
-        for (const auto& dep : json["deps"]) {
-            if (!dep.is_string()) continue;
-            auto target = dep.get<std::string>();
-            if (!target.empty()) targets.push_back(std::move(target));
-        }
-        return install_targets_from_list(targets);
-    }
-
-    // Forward-compat for legacy project config.xlings (Lua):
-    // delegate loading/parsing/installing to xim (Lua runtime).
-    auto legacyCfg = find_project_legacy_xlings_lua();
-    if (!legacyCfg.empty()) {
-        return install_from_legacy_config_xlings_via_xim(legacyCfg);
-    }
-
-    std::println("Tip: create <project>/.xlings.json with deps (preferred), or use config.xlings xim table, or run `xlings install <package>`");
-    return 0;
-}
-
-export CommandProcessor create_processor() {
-    return CommandProcessor{}
-        .add("install", "install package/tool",
-            [](int argc, char* argv[]) {
-                if (argc <= 2) {
-                    return install_from_project_config();
-                }
-                return xim_exec("", argc, argv);
-            },
-            "xlings install [package[@version]]")
-        .add("remove", "remove package/tool",
-            [](int argc, char* argv[]) {
-                return xim_exec("", argc, argv, 1);
-            },
-            "xlings remove <package>")
-        .add("update", "update package/tool",
-            [](int argc, char* argv[]) {
-                return xim_exec("", argc, argv, 1);
-            },
-            "xlings update <package>")
-        .add("search", "search for packages",
-            [](int argc, char* argv[]) {
-                return xim_exec("", argc, argv, 1);
-            },
-            "xlings search <keyword>")
-        .add("use", "switch version of a tool",
-            [](int argc, char* argv[]) {
-                if (argc < 3) {
-                    std::println("Usage: xlings use <target> [version]");
-                    return 1;
-                }
-                if (argc >= 4) {
-                    return xvm_exec("use", argc, argv);
-                }
-                return xvm_exec("list", argc, argv);
-            },
-            "xlings use <target> [version]")
-        .add("info", "show tool info",
-            [](int argc, char* argv[]) {
-                if (argc < 3) {
-                    std::println("Usage: xlings info <target>");
-                    return 1;
-                }
-                return xvm_exec("info", argc, argv);
-            },
-            "xlings info <target>")
-        .add("config", "show xlings configuration",
-            [](int, char**) {
-                Config::print_paths();
-                return 0;
-            })
-        .add("subos", "manage sub-os environments",
-            [](int argc, char* argv[]) {
-                EventStream stream;
-                return subos::run(argc, argv, stream);
-            },
-            "xlings subos <new|use|list|ls|remove|rm|info|i> [name]")
-        .add("script", "run xpkg script",
-            [](int argc, char* argv[]) {
-                if (argc < 3) {
-                    std::println("Usage: xlings script <script-file> [args...]");
-                    return 1;
-                }
-                namespace fs = std::filesystem;
-                fs::path scriptFile = argv[2];
-                auto execResult = mcpplibs::xpkg::create_executor(scriptFile);
-                if (!execResult) {
-                    log::error("failed to load script: {}", execResult.error());
-                    return 1;
-                }
-                mcpplibs::xpkg::ExecutionContext ctx;
-                ctx.platform = std::string(platform::OS_NAME);
-                ctx.bin_dir = Config::paths().binDir;
-                ctx.subos_sysrootdir = Config::paths().subosDir.string();
-                ctx.run_dir = fs::current_path();
-                ctx.xpkg_dir = Config::paths().dataDir / "xpkgs";
-                for (int i = 3; i < argc; ++i) {
-                    ctx.args.emplace_back(argv[i]);
-                }
-                auto result = execResult->run_script(ctx);
-                if (!result.success) {
-                    log::error("script error: {}", result.error);
-                    return 1;
-                }
-                return 0;
-            },
-            "xlings script <script-file> [args...]")
-        .add("self", "self management (init/update/config/clean/migrate)",
-            [](int argc, char* argv[]) {
-                EventStream stream;
-                return xself::run(argc, argv, stream);
-            },
-            "xlings self [init|update|config|clean [--dry-run]|migrate|help]");
-}
+export CommandProcessor create_processor();
 
 } // namespace xlings::cmdprocessor
diff --git a/src/core/common.cpp b/src/core/common.cpp
new file mode 100644
index 00000000..a5912aa1
--- /dev/null
+++ b/src/core/common.cpp
@@ -0,0 +1,24 @@
+module;
+
+module xlings.core.common;
+
+import std;
+import xlings.core.config;
+import xlings.core.xself;
+
+namespace xlings::common {
+
+void mirror_shim_to_global_bin(const fs::path& xlings_bin,
+                                      const std::string& shim_name) {
+    if (!Config::has_project_config()) return;
+    auto global_bin = Config::global_subos_bin_dir();
+    auto current_bin = Config::paths().binDir;
+    if (global_bin == current_bin) return;
+    fs::create_directories(global_bin);
+    auto dst = global_bin / shim_name;
+    if (!fs::exists(dst)) {
+        xself::create_shim(xlings_bin, dst);
+    }
+}
+
+}
diff --git a/src/core/common.cppm b/src/core/common.cppm
index e28071c8..03f67fe6 100644
--- a/src/core/common.cppm
+++ b/src/core/common.cppm
@@ -4,8 +4,6 @@ export module xlings.core.common;
 
 import std;
 
-import xlings.core.config;
-import xlings.core.xself;
 
 namespace xlings::common {
 
@@ -15,16 +13,6 @@ namespace fs = std::filesystem;
 // Project subos bin is not in PATH; global subos/current/bin is.
 // Only creates if missing — never overwrites existing global shims.
 export void mirror_shim_to_global_bin(const fs::path& xlings_bin,
-                                      const std::string& shim_name) {
-    if (!Config::has_project_config()) return;
-    auto global_bin = Config::global_subos_bin_dir();
-    auto current_bin = Config::paths().binDir;
-    if (global_bin == current_bin) return;
-    fs::create_directories(global_bin);
-    auto dst = global_bin / shim_name;
-    if (!fs::exists(dst)) {
-        xself::create_shim(xlings_bin, dst);
-    }
-}
+                                      const std::string& shim_name);
 
 } // namespace xlings::common
diff --git a/src/core/compact/git.cpp b/src/core/compact/git.cpp
new file mode 100644
index 00000000..68bf2bfb
--- /dev/null
+++ b/src/core/compact/git.cpp
@@ -0,0 +1,99 @@
+module xlings.core.compact.git;
+
+import std;
+import xlings.core.config;
+import xlings.core.log;
+import xlings.core.utils;
+import xlings.platform;
+
+namespace xlings::compact::git {
+
+std::string resolve_ca_bundle(const std::function<bool(const std::string&)>& exists) {
+    if (exists("/etc/ssl/cert.pem")) return {};
+    for (const char* f : {"/etc/ssl/certs/ca-certificates.crt",
+                          "/etc/pki/tls/certs/ca-bundle.crt",
+                          "/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem",
+                          "/etc/ssl/ca-bundle.pem"}) {
+        if (exists(f)) return f;
+    }
+    return {};
+}
+
+bool available() {
+    auto [rc, _] = platform::run_command_capture(detail_::command_({"--version"}));
+    return rc == 0;
+}
+
+bool ensure_available(EnsureMode mode) {
+    detail_::ensure_ca_env_();
+    detail_::prepend_current_bin_dir_();
+    if (available()) return true;
+
+    if (mode == EnsureMode::NeverInstall) return false;
+
+    if (detail_::env_flag_("XLINGS_NO_AUTO_INSTALL_GIT")) {
+        log::error("git is required, but automatic Git installation is disabled. "
+                   "Run: xlings install xim:git -y");
+        return false;
+    }
+
+    if (!detail_::bootstrap_git_()) return false;
+
+    if (available()) return true;
+
+    log::error("git is still unavailable after installing xim:git. "
+               "Run: xlings install xim:git -y");
+    return false;
+}
+
+Result capture(const std::vector<std::string>& args, EnsureMode mode) {
+    if (!ensure_available(mode)) {
+        return {1, "git is required but unavailable"};
+    }
+    auto [rc, output] = platform::run_command_capture(detail_::command_(args));
+    return {rc, output};
+}
+
+int exec(const std::vector<std::string>& args, EnsureMode mode) {
+    if (!ensure_available(mode)) return 1;
+    return platform::exec(detail_::command_(args));
+}
+
+platform::ProcessHandle spawn(const std::vector<std::string>& args, EnsureMode mode) {
+    if (!ensure_available(mode)) return {};
+    return platform::spawn_command(detail_::command_(args));
+}
+
+Result clone_shallow(const std::string& url,
+                     const std::filesystem::path& dest,
+                     bool recursive) {
+    std::vector<std::string> args = {"clone", "--depth", "1"};
+    if (recursive) args.push_back("--recursive");
+    args.push_back("--quiet");
+    args.push_back(url);
+    args.push_back(dest.string());
+    return capture(args);
+}
+
+Result pull_ff_only(const std::filesystem::path& repo) {
+    return capture({"-C", repo.string(), "pull", "--ff-only"});
+}
+
+Result set_origin(const std::filesystem::path& repo, const std::string& url) {
+    return capture({"-C", repo.string(), "remote", "set-url", "origin", url});
+}
+
+Result fetch_reset_origin_head(const std::filesystem::path& repo) {
+    auto fetch = capture({"-C", repo.string(), "fetch", "origin"});
+    if (fetch.rc != 0) return fetch;
+
+    auto reset = capture({"-C", repo.string(), "reset", "--hard", "origin/HEAD"});
+    if (!fetch.output.empty() && !reset.output.empty()) {
+        reset.output = fetch.output + "\n" + reset.output;
+    } else if (!fetch.output.empty()) {
+        reset.output = fetch.output;
+    }
+    return reset;
+}
+
+}
diff --git a/src/core/compact/git.cppm b/src/core/compact/git.cppm
index b7805cd0..1c366025 100644
--- a/src/core/compact/git.cppm
+++ b/src/core/compact/git.cppm
@@ -35,16 +35,7 @@ enum class EnsureMode {
 // explicit CURLOPT_CAINFO (SSL_CERT_FILE / CURL_CA_BUNDLE / GIT_SSL_CAPATH
 // all lose). Returns "" when the built-in default exists or no known bundle
 // is found. Pure; existence probe injected for tests.
-std::string resolve_ca_bundle(const std::function<bool(const std::string&)>& exists) {
-    if (exists("/etc/ssl/cert.pem")) return {};
-    for (const char* f : {"/etc/ssl/certs/ca-certificates.crt",
-                          "/etc/pki/tls/certs/ca-bundle.crt",
-                          "/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem",
-                          "/etc/ssl/ca-bundle.pem"}) {
-        if (exists(f)) return f;
-    }
-    return {};
-}
+std::string resolve_ca_bundle(const std::function<bool(const std::string&)>& exists);
 
 namespace detail_ {
 
@@ -168,84 +159,27 @@ inline bool bootstrap_git_() {
 
 } // namespace detail_
 
-bool available() {
-    auto [rc, _] = platform::run_command_capture(detail_::command_({"--version"}));
-    return rc == 0;
-}
-
-bool ensure_available(EnsureMode mode = EnsureMode::AutoInstall) {
-    detail_::ensure_ca_env_();
-    detail_::prepend_current_bin_dir_();
-    if (available()) return true;
-
-    if (mode == EnsureMode::NeverInstall) return false;
-
-    if (detail_::env_flag_("XLINGS_NO_AUTO_INSTALL_GIT")) {
-        log::error("git is required, but automatic Git installation is disabled. "
-                   "Run: xlings install xim:git -y");
-        return false;
-    }
-
-    if (!detail_::bootstrap_git_()) return false;
-
-    if (available()) return true;
+bool available();
 
-    log::error("git is still unavailable after installing xim:git. "
-               "Run: xlings install xim:git -y");
-    return false;
-}
+bool ensure_available(EnsureMode mode = EnsureMode::AutoInstall);
 
 Result capture(const std::vector<std::string>& args,
-               EnsureMode mode = EnsureMode::AutoInstall) {
-    if (!ensure_available(mode)) {
-        return {1, "git is required but unavailable"};
-    }
-    auto [rc, output] = platform::run_command_capture(detail_::command_(args));
-    return {rc, output};
-}
+               EnsureMode mode = EnsureMode::AutoInstall);
 
 int exec(const std::vector<std::string>& args,
-         EnsureMode mode = EnsureMode::AutoInstall) {
-    if (!ensure_available(mode)) return 1;
-    return platform::exec(detail_::command_(args));
-}
+         EnsureMode mode = EnsureMode::AutoInstall);
 
 platform::ProcessHandle spawn(const std::vector<std::string>& args,
-                              EnsureMode mode = EnsureMode::AutoInstall) {
-    if (!ensure_available(mode)) return {};
-    return platform::spawn_command(detail_::command_(args));
-}
+                              EnsureMode mode = EnsureMode::AutoInstall);
 
 Result clone_shallow(const std::string& url,
                      const std::filesystem::path& dest,
-                     bool recursive) {
-    std::vector<std::string> args = {"clone", "--depth", "1"};
-    if (recursive) args.push_back("--recursive");
-    args.push_back("--quiet");
-    args.push_back(url);
-    args.push_back(dest.string());
-    return capture(args);
-}
+                     bool recursive);
 
-Result pull_ff_only(const std::filesystem::path& repo) {
-    return capture({"-C", repo.string(), "pull", "--ff-only"});
-}
-
-Result set_origin(const std::filesystem::path& repo, const std::string& url) {
-    return capture({"-C", repo.string(), "remote", "set-url", "origin", url});
-}
+Result pull_ff_only(const std::filesystem::path& repo);
 
-Result fetch_reset_origin_head(const std::filesystem::path& repo) {
-    auto fetch = capture({"-C", repo.string(), "fetch", "origin"});
-    if (fetch.rc != 0) return fetch;
+Result set_origin(const std::filesystem::path& repo, const std::string& url);
 
-    auto reset = capture({"-C", repo.string(), "reset", "--hard", "origin/HEAD"});
-    if (!fetch.output.empty() && !reset.output.empty()) {
-        reset.output = fetch.output + "\n" + reset.output;
-    } else if (!fetch.output.empty()) {
-        reset.output = fetch.output;
-    }
-    return reset;
-}
+Result fetch_reset_origin_head(const std::filesystem::path& repo);
 
 } // namespace xlings::compact::git
diff --git a/src/core/compact/xself.cpp b/src/core/compact/xself.cpp
new file mode 100644
index 00000000..b4630aee
--- /dev/null
+++ b/src/core/compact/xself.cpp
@@ -0,0 +1,110 @@
+// Cross-version compatibility shim collection.
+//
+// Each compat feature lives in its own `vX_Y_Z` sub-namespace so the
+// version it dates from is visible at every call site, and so a clean
+// removal is a one-shot operation:
+//
+//   1. Bump the codebase past the removal target.
+//   2. Delete the matching `namespace vX_Y_Z { ... }` block in this file.
+//   3. Rebuild — every reference to `xself::compat::vX_Y_Z::*` surfaces as
+//      a hard build error. Delete the call and any surrounding
+//      `COMPAT(X.Y.Z → drop in A.B.C)` marker comment. No grep needed.
+//
+// "Compat" here is a deliberately broad bucket: it covers both
+//   * one-shot migrations  (legacy alias shim cleanup — really expires)
+//   * permanent self-heal  (profile auto-upgrade — keeps paying off as
+//                           the embedded resource version evolves)
+// The `removal_target` line in each block tells you which is which.
+module xlings.core.xself.compat;
+
+import std;
+import xlings.core.log;
+import xlings.platform;
+import xlings.core.xself.profile_resources;
+
+namespace xlings::xself::compat {
+
+namespace v0_4_8 {
+
+bool is_legacy_alias_symlink_to_bootstrap(const fs::path& path,
+                                          const fs::path& canonical_bootstrap)
+{
+    std::error_code ec;
+    if (!fs::is_symlink(path, ec)) return false;
+    ec.clear();
+    auto target = fs::weakly_canonical(path, ec);
+    if (ec) return false;
+    return target == canonical_bootstrap;
+}
+
+void cleanup_legacy_alias_shims(const fs::path& bin_dir,
+                                const fs::path& bootstrap_path) {
+    std::error_code ec;
+    auto canonical_bootstrap = fs::weakly_canonical(bootstrap_path, ec);
+    if (ec) return;
+
+    std::string ext = bootstrap_path.extension().string();
+    for (auto name : LEGACY_ALIAS_NAMES) {
+        auto path = bin_dir / (std::string(name) + ext);
+        if (!is_legacy_alias_symlink_to_bootstrap(path, canonical_bootstrap))
+            continue;
+        ec.clear();
+        fs::remove(path, ec);
+        log::debug("[migrate] removed legacy alias shim: {}", path.string());
+    }
+}
+
+bool report_deprecated_alias_if_match(std::string_view program_name) {
+    for (auto& [alias, suggestion] : DEPRECATED_ALIASES) {
+        if (alias == program_name) {
+            std::println(std::cerr,
+                "[error] `{}` was removed in 0.4.8. Use `{}` instead.",
+                alias, suggestion);
+            std::println(std::cerr,
+                "        Run `xlings self doctor --fix` to clean up "
+                "leftover shortcuts.");
+            return true;
+        }
+    }
+    return false;
+}
+
+}
+
+namespace v0_4_17 {
+
+void auto_upgrade_profiles_if_stale(const fs::path& home_dir) {
+    if (home_dir.empty()) return;
+
+    auto config_dir = home_dir / "config" / "shell";
+    std::error_code ec;
+    if (!fs::is_directory(config_dir, ec)) return;
+
+    struct Slot {
+        const char*       filename;
+        std::string_view  bytes;
+    };
+    const Slot slots[] = {
+        { "xlings-profile.sh",   profile_resources::bash_sh },
+        { "xlings-profile.fish", profile_resources::fish    },
+        { "xlings-profile.ps1",  profile_resources::pwsh    },
+    };
+
+    for (auto& s : slots) {
+        auto path = config_dir / s.filename;
+        if (!detail_::needs_profile_upgrade(path, profile_resources::kVersion))
+            continue;
+        try {
+            platform::write_string_to_file(path.string(), std::string(s.bytes));
+            log::debug("[compat] upgraded {} to profile version {}",
+                       path.string(), profile_resources::kVersion);
+        } catch (...) {
+            // Profile upgrade is opportunistic — failure shouldn't block
+            // the actual command the user invoked.
+        }
+    }
+}
+
+}
+
+}
diff --git a/src/core/compact/xself.cppm b/src/core/compact/xself.cppm
index ded0e869..b8992d13 100644
--- a/src/core/compact/xself.cppm
+++ b/src/core/compact/xself.cppm
@@ -18,7 +18,6 @@
 export module xlings.core.xself.compat;
 
 import std;
-import xlings.core.log;
 import xlings.platform;
 import xlings.core.xself.profile_resources;
 
@@ -212,84 +211,19 @@ inline constexpr std::string_view kSchemaForm = "subos workspace = {active, inst
 namespace v0_4_8 {
 
 bool is_legacy_alias_symlink_to_bootstrap(const fs::path& path,
-                                          const fs::path& canonical_bootstrap)
-{
-    std::error_code ec;
-    if (!fs::is_symlink(path, ec)) return false;
-    ec.clear();
-    auto target = fs::weakly_canonical(path, ec);
-    if (ec) return false;
-    return target == canonical_bootstrap;
-}
+                                          const fs::path& canonical_bootstrap);
 
 void cleanup_legacy_alias_shims(const fs::path& bin_dir,
-                                const fs::path& bootstrap_path) {
-    std::error_code ec;
-    auto canonical_bootstrap = fs::weakly_canonical(bootstrap_path, ec);
-    if (ec) return;
-
-    std::string ext = bootstrap_path.extension().string();
-    for (auto name : LEGACY_ALIAS_NAMES) {
-        auto path = bin_dir / (std::string(name) + ext);
-        if (!is_legacy_alias_symlink_to_bootstrap(path, canonical_bootstrap))
-            continue;
-        ec.clear();
-        fs::remove(path, ec);
-        log::debug("[migrate] removed legacy alias shim: {}", path.string());
-    }
-}
+                                const fs::path& bootstrap_path);
 
-bool report_deprecated_alias_if_match(std::string_view program_name) {
-    for (auto& [alias, suggestion] : DEPRECATED_ALIASES) {
-        if (alias == program_name) {
-            std::println(std::cerr,
-                "[error] `{}` was removed in 0.4.8. Use `{}` instead.",
-                alias, suggestion);
-            std::println(std::cerr,
-                "        Run `xlings self doctor --fix` to clean up "
-                "leftover shortcuts.");
-            return true;
-        }
-    }
-    return false;
-}
+bool report_deprecated_alias_if_match(std::string_view program_name);
 
 } // namespace v0_4_8
 
 
 namespace v0_4_17 {
 
-void auto_upgrade_profiles_if_stale(const fs::path& home_dir) {
-    if (home_dir.empty()) return;
-
-    auto config_dir = home_dir / "config" / "shell";
-    std::error_code ec;
-    if (!fs::is_directory(config_dir, ec)) return;
-
-    struct Slot {
-        const char*       filename;
-        std::string_view  bytes;
-    };
-    const Slot slots[] = {
-        { "xlings-profile.sh",   profile_resources::bash_sh },
-        { "xlings-profile.fish", profile_resources::fish    },
-        { "xlings-profile.ps1",  profile_resources::pwsh    },
-    };
-
-    for (auto& s : slots) {
-        auto path = config_dir / s.filename;
-        if (!detail_::needs_profile_upgrade(path, profile_resources::kVersion))
-            continue;
-        try {
-            platform::write_string_to_file(path.string(), std::string(s.bytes));
-            log::debug("[compat] upgraded {} to profile version {}",
-                       path.string(), profile_resources::kVersion);
-        } catch (...) {
-            // Profile upgrade is opportunistic — failure shouldn't block
-            // the actual command the user invoked.
-        }
-    }
-}
+void auto_upgrade_profiles_if_stale(const fs::path& home_dir);
 
 } // namespace v0_4_17
 
diff --git a/src/core/config.cpp b/src/core/config.cpp
new file mode 100644
index 00000000..c0d95ed5
--- /dev/null
+++ b/src/core/config.cpp
@@ -0,0 +1,1229 @@
+module;
+#include <cstdio>
+
+module xlings.core.config;
+
+import std;
+import xlings.libs.json;
+import xlings.core.log;
+import xlings.platform;
+import xlings.core.utils;
+import xlings.libs.tinyhttps;
+import xlings.core.xvm.types;
+import xlings.core.xvm.db;
+
+namespace xlings {
+
+void capture_ambient_home_env() {
+    if (detail_::ambientHomeCaptured_) return;   // first call wins
+    detail_::ambientHomeCaptured_ = true;
+    if (const char* v = std::getenv("XLINGS_HOME"); v != nullptr && *v != '\0') {
+        detail_::ambientHome_ = std::string(v);
+    }
+}
+
+const std::optional<std::string>& ambient_home_env() {
+    return detail_::ambientHome_;
+}
+
+std::vector<IndexRepo> parse_index_repos_json(const nlohmann::json& json,
+                                                     const std::string& mirror) {
+    std::vector<IndexRepo> out;
+    if (!json.contains("index_repos") || !json["index_repos"].is_array()) return out;
+    for (auto it = json["index_repos"].begin(); it != json["index_repos"].end(); ++it) {
+        if (!it->is_object() || !it->contains("name") || !it->contains("url")) continue;
+        IndexRepo repo;
+        repo.name = (*it)["name"].get<std::string>();
+        repo.url  = (*it)["url"].get<std::string>();
+        if (repo.name.empty() || repo.url.empty()) continue;
+        if (it->contains("artifact")) {
+            auto& a = (*it)["artifact"];
+            std::string base;
+            if (a.is_string()) base = a.get<std::string>();
+            else if (a.is_object()) {
+                std::string key = mirror.empty() ? "GLOBAL" : mirror;
+                if (a.contains(key) && a[key].is_string()) base = a[key].get<std::string>();
+                else if (a.contains("GLOBAL") && a["GLOBAL"].is_string())
+                    base = a["GLOBAL"].get<std::string>();
+            }
+            base = utils::trim_string(base);
+            while (base.size() > 1 && base.ends_with('/')) base.pop_back();
+            repo.artifactBase = base;
+        }
+        if (it->contains("source") && (*it)["source"].is_string())
+            repo.source = (*it)["source"].get<std::string>();
+        // Not validated: the version namespace belongs to the index publisher,
+        // and xlings should not have an opinion about its shape.
+        if (it->contains("version") && (*it)["version"].is_string())
+            repo.version = (*it)["version"].get<std::string>();
+        out.push_back(std::move(repo));
+    }
+    return out;
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings {
+
+void Config::override_home(const std::filesystem::path& home) {
+    home_override_() = home;
+}
+
+std::optional<std::filesystem::path>& Config::home_override_() {
+    static std::optional<std::filesystem::path> v;
+    return v;
+}
+
+std::vector<IndexRepo> Config::default_global_index_repos_(const std::string& mirror) {
+    std::string url = "https://github.com/openxlings/xim-pkgindex.git";
+    if (mirror == "CN") {
+        url = "https://gitee.com/sunrisepeak/xim-pkgindex.git";
+    }
+    return { IndexRepo{std::string(DEFAULT_INDEX_REPO_NAME), url} };
+}
+
+MirrorServerMap Config::default_resource_servers_() {
+    return {
+        { "GLOBAL", { "https://github.com/xlings-res" } },
+        { "CN", { "https://gitcode.com/xlings-res" } },
+    };
+}
+
+std::string Config::resolve_index_base_(const nlohmann::json& json, const std::string& mirror) {
+    if (!json.contains("xim") || !json["xim"].is_object()) return {};
+    auto& xim = json["xim"];
+    if (!xim.contains("index-base")) return {};
+    auto& ib = xim["index-base"];
+    if (ib.is_string()) return ib.get<std::string>();
+    if (ib.is_object()) {
+        std::string key = mirror.empty() ? "GLOBAL" : mirror;
+        if (ib.contains(key) && ib[key].is_string()) return ib[key].get<std::string>();
+        if (ib.contains("GLOBAL") && ib["GLOBAL"].is_string()) return ib["GLOBAL"].get<std::string>();
+    }
+    return {};
+}
+
+std::vector<std::string> Config::parse_server_list_(const nlohmann::json& value) {
+    std::vector<std::string> servers;
+    auto append_server = [&](std::string server) {
+        server = utils::trim_string(server);
+        while (server.size() > 1 && server.ends_with('/')) {
+            server.pop_back();
+        }
+        if (server.empty()) return;
+        if (std::ranges::find(servers, server) == servers.end()) {
+            servers.push_back(std::move(server));
+        }
+    };
+
+    if (value.is_string()) {
+        append_server(value.get<std::string>());
+    } else if (value.is_array()) {
+        for (auto& item : value) {
+            if (item.is_string()) append_server(item.get<std::string>());
+        }
+    }
+    return servers;
+}
+
+void Config::merge_resource_servers_into_(MirrorServerMap& dst, const MirrorServerMap& src) {
+    for (auto& [mirror, servers] : src) {
+        if (!servers.empty()) dst[mirror] = servers;
+    }
+}
+
+void Config::load_resource_servers_from_json_(const nlohmann::json& json,
+                                                 MirrorServerMap& out) {
+    out.clear();
+
+    auto normalize_key = [](std::string key) {
+        key = utils::trim_string(key);
+        if (key == "default" || key == "DEFAULT" || key == "_default") return std::string("DEFAULT");
+        return key;
+    };
+
+    auto load_object = [&](const nlohmann::json& obj) {
+        if (!obj.is_object()) return;
+        for (auto it = obj.begin(); it != obj.end(); ++it) {
+            auto servers = parse_server_list_(it.value());
+            if (!servers.empty()) out[normalize_key(it.key())] = std::move(servers);
+        }
+    };
+
+    auto load_default_list = [&](const nlohmann::json& value) {
+        auto servers = parse_server_list_(value);
+        if (!servers.empty()) out["DEFAULT"] = std::move(servers);
+    };
+
+    if (json.contains("XLINGS_RES")) {
+        if (json["XLINGS_RES"].is_object()) {
+            load_object(json["XLINGS_RES"]);
+        } else {
+            load_default_list(json["XLINGS_RES"]);
+        }
+    }
+
+    // Backward compatibility for older config shapes.
+    if (out.empty()) {
+        if (json.contains("resource_server")) {
+            load_default_list(json["resource_server"]);
+        }
+
+        if (json.contains("resource_servers")) {
+            if (json["resource_servers"].is_object()) {
+                load_object(json["resource_servers"]);
+            } else {
+                load_default_list(json["resource_servers"]);
+            }
+        }
+
+        if (json.contains("res_servers")) {
+            if (json["res_servers"].is_object()) {
+                load_object(json["res_servers"]);
+            } else {
+                load_default_list(json["res_servers"]);
+            }
+        }
+
+        if (json.contains("xim") && json["xim"].is_object()) {
+            auto& xim = json["xim"];
+            if (xim.contains("mirrors") && xim["mirrors"].is_object()) {
+                auto& mirrors = xim["mirrors"];
+                if (mirrors.contains("res-server")) {
+                    load_object(mirrors["res-server"]);
+                }
+            }
+        }
+    }
+}
+
+xvm::SubosWorkspace Config::load_workspace_from_file_(const std::filesystem::path& path) {
+    namespace fs = std::filesystem;
+    if (!fs::exists(path)) return {};
+    try {
+        auto content = platform::read_file_to_string(path.string());
+        auto json = nlohmann::json::parse(content, nullptr, false);
+        if (!json.is_discarded() && json.contains("workspace") && json["workspace"].is_object()) {
+            return xvm::subos_workspace_from_json(json["workspace"]);
+        }
+    } catch (...) {}
+    return {};
+}
+
+std::string Config::load_project_subos_name_(const nlohmann::json& json) {
+    if (json.contains("subos") && json["subos"].is_string()) {
+        auto val = json["subos"].get<std::string>();
+        if (!val.empty()) return val;
+    }
+    if (json.contains("projectSubos") && json["projectSubos"].is_string()) {
+        auto val = json["projectSubos"].get<std::string>();
+        if (!val.empty()) return val;
+    }
+    return {};
+}
+
+void Config::merge_versions_into_(xvm::VersionDB& dst, const xvm::VersionDB& src) {
+    for (auto& [target, info] : src) {
+        auto& dstInfo = dst[target];
+        if (dstInfo.type.empty() && !info.type.empty())
+            dstInfo.type = info.type;
+        if (dstInfo.filename.empty() && !info.filename.empty())
+            dstInfo.filename = info.filename;
+        for (auto& [ver, vdata] : info.versions) {
+            dstInfo.versions[ver] = vdata;
+        }
+        for (auto& [name, vermap] : info.bindings) {
+            for (auto& [ver, value] : vermap) {
+                dstInfo.bindings[name][ver] = value;
+            }
+        }
+    }
+}
+
+void Config::merge_workspace_into_(xvm::Workspace& dst, const xvm::Workspace& src) {
+    for (auto& [target, version] : src) {
+        dst[target] = version;
+    }
+}
+
+std::string Config::effective_mirror_name_(std::string_view mirror,
+                                              std::string_view fallback) {
+    auto name = std::string(mirror.empty() ? fallback : mirror);
+    if (name.empty()) return "GLOBAL";
+    return name;
+}
+
+std::vector<std::string> Config::workspace_targets_from_workspace_(const xvm::Workspace& ws) {
+    std::vector<std::string> targets;
+    targets.reserve(ws.size());
+    for (auto& [name, version] : ws) {
+        if (name.empty()) continue;
+        if (version.empty()) {
+            targets.push_back(name);
+        } else {
+            targets.push_back(name + "@" + version);
+        }
+    }
+    return targets;
+}
+
+[[nodiscard]] std::filesystem::path Config::project_data_dir_() const {
+    return projectDir_.empty() ? std::filesystem::path{} : projectDir_ / ".xlings" / "data";
+}
+
+[[nodiscard]] std::filesystem::path Config::project_home_dir_() const {
+    return projectDir_.empty() ? std::filesystem::path{} : projectDir_ / ".xlings";
+}
+
+[[nodiscard]] std::filesystem::path Config::project_state_path_() const {
+    auto homeDir = project_home_dir_();
+    if (homeDir.empty()) return {};
+    return homeDir / ".xlings.json";
+}
+
+[[nodiscard]] std::filesystem::path Config::project_manifest_path_() const {
+    return projectDir_.empty() ? std::filesystem::path{} : projectDir_ / ".xlings.json";
+}
+
+[[nodiscard]] std::filesystem::path Config::project_subos_dir_() const {
+    if (projectDir_.empty()) return {};
+    if (!projectSubosName_.empty()) return projectDir_ / ".xlings" / "subos" / projectSubosName_;
+    if (projectSubosMode_ == ProjectSubosMode::Anonymous) return projectDir_ / ".xlings" / "subos" / "_";
+    return {};
+}
+
+[[nodiscard]] std::filesystem::path Config::global_subos_dir_() const {
+    auto activeSubos = utils::get_env_or_default(
+        "XLINGS_ACTIVE_SUBOS");
+    if (activeSubos.empty()) {
+        activeSubos = globalActiveSubos_;
+    }
+    return paths_.homeDir / "subos" / activeSubos;
+}
+
+[[nodiscard]] std::vector<std::string> Config::lookup_resource_servers_in_(const MirrorServerMap& source, std::string_view mirror) {
+    auto key = effective_mirror_name_(mirror, "GLOBAL");
+    if (auto it = source.find(key); it != source.end() && !it->second.empty()) {
+        return it->second;
+    }
+    if (auto it = source.find("DEFAULT"); it != source.end() && !it->second.empty()) {
+        return it->second;
+    }
+    return {};
+}
+
+[[nodiscard]] std::vector<std::string> Config::candidate_resource_servers_for_(std::string_view mirror) const {
+    auto key = effective_mirror_name_(mirror, mirror_);
+
+    auto project = lookup_resource_servers_in_(projectResourceServers_, key);
+    if (!project.empty()) return project;
+
+    auto global = lookup_resource_servers_in_(globalResourceServers_, key);
+    if (!global.empty()) return global;
+
+    auto defaults = lookup_resource_servers_in_(default_resource_servers_(), key);
+    if (!defaults.empty()) return defaults;
+
+    auto fallback = lookup_resource_servers_in_(default_resource_servers_(), "GLOBAL");
+    if (!fallback.empty()) return fallback;
+    return {};
+}
+
+[[nodiscard]] std::vector<std::string> Config::all_resource_servers_for_(std::string_view mirror) const {
+    auto servers = candidate_resource_servers_for_(mirror);
+    auto key = effective_mirror_name_(mirror, mirror_);
+
+    std::set<std::string> seen(servers.begin(), servers.end());
+    auto append_other_regions = [&](const MirrorServerMap& source) {
+        // unordered_map: sort the keys so the fallback order is the same
+        // on every run and every machine.
+        std::vector<std::string> regions;
+        for (const auto& [region, _] : source) {
+            if (region != key) regions.push_back(region);
+        }
+        std::ranges::sort(regions);
+        for (const auto& region : regions) {
+            for (const auto& server : source.at(region)) {
+                if (seen.insert(server).second) servers.push_back(server);
+            }
+        }
+    };
+    append_other_regions(projectResourceServers_);
+    append_other_regions(globalResourceServers_);
+    append_other_regions(default_resource_servers_());
+    return servers;
+}
+
+double Config::probe_resource_server_latency_(const std::string& server) {
+    return tinyhttps::probe_latency(server, 2000);
+}
+
+[[nodiscard]] std::string Config::selected_resource_server_for_(std::string_view mirror) const {
+    auto key = effective_mirror_name_(mirror, mirror_);
+    {
+        std::scoped_lock lock(resourceServerMutex_);
+        if (auto it = selectedResourceServerCache_.find(key);
+            it != selectedResourceServerCache_.end()) {
+            return it->second;
+        }
+    }
+
+    auto candidates = candidate_resource_servers_for_(key);
+    if (candidates.empty()) return {};
+
+    auto selected = candidates.front();
+    if (candidates.size() > 1) {
+        double bestLatency = std::numeric_limits<double>::infinity();
+        for (auto& candidate : candidates) {
+            auto latency = probe_resource_server_latency_(candidate);
+            if (latency < bestLatency) {
+                bestLatency = latency;
+                selected = candidate;
+            }
+            if (std::isfinite(latency) && latency <= 0.1) {
+                selected = candidate;
+                break;
+            }
+        }
+    }
+
+    {
+        std::scoped_lock lock(resourceServerMutex_);
+        selectedResourceServerCache_[key] = selected;
+    }
+    return selected;
+}
+
+[[nodiscard]] SubosScope Config::resolve_subos_scope_() const {
+    // An explicit override wins over everything, including a project
+    // config. It exists for the case where a command must act on a subos
+    // it just created rather than on the one the user is standing in —
+    // `subos new --runtime` installing what it declared.
+    if (!activeSubosOverride_.empty()) {
+        return {activeSubosOverride_,
+                paths_.homeDir / "subos" / activeSubosOverride_};
+    }
+    const bool useProject = hasProjectConfig_ && !forceGlobalScope_;
+    if (useProject && projectSubosMode_ == ProjectSubosMode::Named
+        && !projectSubosName_.empty()) {
+        return {projectSubosName_, project_subos_dir_()};
+    }
+    if (useProject && projectSubosMode_ == ProjectSubosMode::Anonymous) {
+        return {"_", project_subos_dir_()};
+    }
+    auto name = utils::get_env_or_default("XLINGS_ACTIVE_SUBOS");
+    if (name.empty()) name = globalActiveSubos_;
+    return {name, paths_.homeDir / "subos" / name};
+}
+
+void Config::update_effective_paths_() {
+    auto scope = resolve_subos_scope_();
+    paths_.activeSubos = std::move(scope.name);
+    paths_.subosDir = std::move(scope.root);
+    paths_.binDir = paths_.subosDir / "bin";
+    paths_.libDir = paths_.subosDir / "lib";
+}
+
+Config::Config() {
+    namespace fs = std::filesystem;
+
+    auto envHome = utils::get_env_or_default("XLINGS_HOME");
+    if (auto& anchored = home_override_(); anchored && !anchored->empty()) {
+        // Owner-anchored shim dispatch: the dispatch home was chosen
+        // before Config construction (main.cpp → resolve_dispatch_home).
+        paths_.homeDir = *anchored;
+    } else if (!envHome.empty()) {
+        paths_.homeDir = envHome;
+    } else {
+        auto exePath   = platform::get_executable_path();
+        auto exeParent = exePath.parent_path();
+        auto candidate = exeParent.parent_path();
+        auto hasRootConfig = !exePath.empty() && fs::exists(candidate / ".xlings.json");
+        constexpr auto kBinName = (platform::OS_NAME == "windows")
+            ? "bin/xlings.exe" : "bin/xlings";
+        auto hasRootBin = !exePath.empty() && fs::exists(candidate / kBinName);
+
+        bool isSelfContained = hasRootConfig && hasRootBin;
+        if constexpr (platform::OS_NAME == "windows") {
+            // Windows: shims are hardlinks/copies (not symlinks), so
+            // get_executable_path() returns the shim path inside a subos
+            // dir (e.g. ~/.xlings/subos/current/bin/xlings.exe). That
+            // directory has both .xlings.json and bin/xlings.exe, falsely
+            // matching the selfContained pattern. Disambiguate by checking
+            // json content: real home/selfContained config always has both
+            // "version" and "activeSubos"; subos config only has workspace.
+            if (isSelfContained) {
+                try {
+                    auto cfg = platform::read_file_to_string(
+                        (candidate / ".xlings.json").string());
+                    auto j = nlohmann::json::parse(cfg, nullptr, false);
+                    isSelfContained = !j.is_discarded()
+                        && j.contains("version")
+                        && j.contains("activeSubos");
+                } catch (...) { isSelfContained = false; }
+            }
+        }
+        if (isSelfContained) {
+            paths_.homeDir       = candidate;
+            paths_.selfContained = true;
+        } else {
+            paths_.homeDir = fs::path(platform::get_home_dir()) / ".xlings";
+        }
+    }
+
+    auto configPath = paths_.homeDir / ".xlings.json";
+    if (fs::exists(configPath)) {
+        try {
+            auto content = platform::read_file_to_string(configPath.string());
+            auto json    = nlohmann::json::parse(content, nullptr, false);
+            if (!json.is_discarded()) {
+                if (json.contains("activeSubos") && json["activeSubos"].is_string()) {
+                    auto val = json["activeSubos"].get<std::string>();
+                    if (!val.empty()) globalActiveSubos_ = val;
+                }
+                if (json.contains("mirror") && json["mirror"].is_string())
+                    mirror_ = json["mirror"].get<std::string>();
+                if (json.contains("lang") && json["lang"].is_string())
+                    lang_ = json["lang"].get<std::string>();
+                // Load global versions
+                load_global_versions_from_json_(json);
+                globalIndexRepos_ = parse_index_repos_json(json, mirror_);
+                load_resource_servers_from_json_(json, globalResourceServers_);
+                if (auto v = resolve_index_base_(json, mirror_); !v.empty()) indexBase_ = v;
+            }
+        } catch (...) {}
+    }
+    if (globalIndexRepos_.empty()) {
+        globalIndexRepos_ = default_global_index_repos_(mirror_);
+    } else {
+        // Ensure the default index repo is always present when user
+        // defines custom index_repos (e.g. adding "ros2").  Without
+        // this, user-defined repos replace the default and packages
+        // in the primary index (like "python") become unfindable.
+        auto defaults = default_global_index_repos_(mirror_);
+        for (auto& def : defaults) {
+            bool found = false;
+            for (auto& repo : globalIndexRepos_) {
+                if (repo.name == def.name) { found = true; break; }
+            }
+            if (!found) {
+                globalIndexRepos_.insert(globalIndexRepos_.begin(), std::move(def));
+            }
+        }
+    }
+
+    paths_.dataDir  = paths_.homeDir / "data";
+    update_effective_paths_();
+
+    log::debug("config: home={}, selfContained={}", paths_.homeDir.string(), paths_.selfContained);
+
+    // Load subos workspace from the path resolved by
+    // update_effective_paths_, which honors XLINGS_ACTIVE_SUBOS env
+    // overrides. Using `globalActiveSubos_` directly here (a snapshot
+    // of `~/.xlings.json activeSubos`) would silently load the wrong
+    // subos's workspace whenever the user is in a spawned subos shell
+    // with XLINGS_ACTIVE_SUBOS set, which then corrupts that subos
+    // when `xvm use` writes back through save_workspace().
+    load_global_workspace_();
+
+    // Load project-level config (walk up from cwd)
+    load_project_config_();
+    update_effective_paths_();
+}
+
+void Config::load_project_config_from_dir_(const std::filesystem::path& dir) {
+    namespace fs = std::filesystem;
+    auto cfg = dir / ".xlings.json";
+    log::debug("config: loading project config from {}", cfg.string());
+    try {
+        auto content = platform::read_file_to_string(cfg.string());
+        auto json = nlohmann::json::parse(content, nullptr, false);
+        if (!json.is_discarded()) {
+            // Build-deps-only files (e.g. xlings's own repo-root
+            // /.xlings.json declaring CI dependencies) opt out of
+            // project mode by setting `"projectScope": false`. This
+            // lets `xlings install` from the repo root still read
+            // the `workspace` field, but skips project-subos
+            // activation, project-state writes, and the project_dir
+            // env-export that downstream shims would otherwise pick
+            // up. Search continues upward as if this file weren't here.
+            //
+            // TODO(2026-): this flag is a workaround for the
+            // chicken-and-egg of "xlings's own repo wants to declare
+            // build deps via .xlings.json without becoming a
+            // managed xlings project". Cleaner long-term options:
+            //
+            //   1. Embrace project mode at the repo root: rewrite
+            //      tests / dev workflow to assume the xlings repo
+            //      IS a managed project; drop this flag entirely.
+            //   2. Add `xlings env` / `xlings config --pkgdir <name>`
+            //      so CI doesn't need to assume payload paths or
+            //      hand-export toolchain env vars at all — the
+            //      installed-subos PATH + xmake auto-detect already
+            //      cover it for the common case (see CI workflows
+            //      that drop --sdk/--cross thanks to musl-gcc's
+            //      gcc-flavor shims), but cross-compile / non-default
+            //      toolchain selections still need explicit values.
+            //   3. Split: keep `.xlings.json` for `xlings install`
+            //      workspace reads, but introduce a separate
+            //      schema-level marker (e.g. top-level
+            //      `"kind": "build-deps"`) checked here.
+            //
+            // Track these in a single follow-up issue once the CI
+            // self-host PR has soaked in.
+            if (json.contains("projectScope") &&
+                json["projectScope"].is_boolean() &&
+                !json["projectScope"].get<bool>()) {
+                log::debug("config: skipping {} (projectScope=false)", cfg.string());
+                return;
+            }
+            projectDir_ = dir;
+            hasProjectConfig_ = true;
+            // Export project dir so child processes (shims, os.execute)
+            // can find project workspace even when CWD changes.
+            platform::set_env_variable("XLINGS_PROJECT_DIR", dir.string());
+            // Project-level mirror/lang override global
+            if (json.contains("mirror") && json["mirror"].is_string())
+                mirror_ = json["mirror"].get<std::string>();
+            if (json.contains("lang") && json["lang"].is_string())
+                lang_ = json["lang"].get<std::string>();
+            if (json.contains("workspace") && json["workspace"].is_object()) {
+                projectWorkspace_ = xvm::workspace_from_json(json["workspace"]);
+            }
+            projectIndexRepos_ = parse_index_repos_json(json, mirror_);
+            load_resource_servers_from_json_(json, projectResourceServers_);
+            if (auto v = resolve_index_base_(json, mirror_); !v.empty()) indexBase_ = v;  // project overrides global
+            projectSubosName_ = load_project_subos_name_(json);
+
+            auto projectStatePath = project_state_path_();
+            nlohmann::json projectStateJson;
+            bool hasProjectStateJson = false;
+            if (!projectStatePath.empty() && fs::exists(projectStatePath)) {
+                try {
+                    auto stateContent = platform::read_file_to_string(projectStatePath.string());
+                    projectStateJson = nlohmann::json::parse(stateContent, nullptr, false);
+                    hasProjectStateJson = !projectStateJson.is_discarded() && projectStateJson.is_object();
+                } catch (...) {
+                    hasProjectStateJson = false;
+                }
+            }
+
+            if (hasProjectStateJson && projectStateJson.contains("versions") &&
+                projectStateJson["versions"].is_object()) {
+                projectVersions_ = xvm::versions_from_json(projectStateJson["versions"]);
+            } else if (json.contains("versions") && json["versions"].is_object()) {
+                projectVersions_ = xvm::versions_from_json(json["versions"]);
+            }
+
+            if (!projectSubosName_.empty()) {
+                projectSubosMode_ = ProjectSubosMode::Named;
+                auto sws = load_workspace_from_file_(project_subos_dir_() / ".xlings.json");
+                projectSubosWorkspace_ = std::move(sws.active);
+                projectSubosInstalled_ = std::move(sws.installed);
+            } else {
+                projectSubosMode_ = ProjectSubosMode::Anonymous;
+                if (hasProjectStateJson && projectStateJson.contains("workspace") &&
+                    projectStateJson["workspace"].is_object()) {
+                    auto sws = xvm::subos_workspace_from_json(projectStateJson["workspace"]);
+                    projectSubosWorkspace_ = std::move(sws.active);
+                    projectSubosInstalled_ = std::move(sws.installed);
+                } else {
+                    auto sws = load_workspace_from_file_(project_subos_dir_() / ".xlings.json");
+                    projectSubosWorkspace_ = std::move(sws.active);
+                    projectSubosInstalled_ = std::move(sws.installed);
+                }
+            }
+        }
+    } catch (...) {}
+}
+
+void Config::load_project_config_() {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+
+    fs::path startDir = fs::current_path(ec);
+    if (ec) return;
+
+    auto homeNorm = fs::weakly_canonical(paths_.homeDir, ec);
+
+    // Walk cwd → root, looking for a `.xlings.json` that activates project
+    // mode. A file with `projectScope: false` is "deps-manifest only" — it
+    // declares deps for `xlings install` but does NOT mean its directory is
+    // a project root (e.g. xlings's own repo uses this to install build
+    // deps without making the repo look like a user project to nested
+    // commands). load_project_config_from_dir_ honors that opt-out by
+    // returning without setting hasProjectConfig_.
+    //
+    // Critical: when from_dir_ skips a projectScope:false file, we must
+    // NOT early-return — that would hide the real project from any
+    // subprocess whose cwd traversal happens to hit such a file before
+    // reaching the actual project. Instead, continue walking up; if no
+    // real project is found in the rest of the walk, the env-var fallback
+    // below picks it up (the parent xlings exports XLINGS_PROJECT_DIR
+    // whenever it loads a real project, so subprocesses can recover the
+    // intended project context even when their cwd is outside the project
+    // tree).
+    // 0.4.20+: xlings-home boundary detection.
+    //
+    // A directory that contains BOTH `.xlings.json` and a `subos/`
+    // sibling directory is an xlings home (ours or some other one) —
+    // never a user project. Project layouts have their state under
+    // `.xlings/subos/`, NOT a bare `subos/` at the same level as
+    // the manifest. Stop walking at any such boundary.
+    //
+    // Without this, a nested xlings home (e.g. mcpp packaged under
+    // ~/.xlings/data/xpkgs/<repo>-x-mcpp/<ver>/registry/, where the
+    // inner xlings sets XLINGS_HOME to the registry dir) would see
+    // its CWD walk skip the inner home (homeNorm match), continue
+    // upward through the package layers, and ultimately mis-load the
+    // OUTER ~/.xlings/.xlings.json as if it were a user project root.
+    // That polluted projectDir_ with the outer home and routed every
+    // subsequent install/shim/workspace path into a phantom
+    // ~/.xlings/.xlings/{subos,data,...} tree disjoint from where
+    // mcpp's recipe actually puts its files.
+    //
+    // The boundary check subsumes the previous `curNorm != homeNorm`
+    // gate: our own home also matches the signature, so the break
+    // covers it. Any directory that "looks like" an xlings home
+    // (regardless of whose) terminates the project walk.
+    auto looks_like_xlings_home = [&](const fs::path& dir) {
+        std::error_code lec;
+        return fs::is_directory(dir / "subos", lec);
+    };
+
+    fs::path cur = startDir;
+    while (!cur.empty()) {
+        auto cfg = cur / ".xlings.json";
+        if (fs::exists(cfg, ec) && fs::is_regular_file(cfg, ec)) {
+            if (looks_like_xlings_home(cur)) {
+                break;                              // hit an xlings home — never project
+            }
+            load_project_config_from_dir_(cur);
+            if (hasProjectConfig_) return;          // real project loaded
+            // else: projectScope:false skip — keep walking, then env fallback
+        }
+        auto parent = cur.parent_path();
+        if (parent == cur) break;
+        cur = parent;
+    }
+
+    // CWD traversal did not find project config (either no .xlings.json
+    // at all, or only projectScope:false ones) — check XLINGS_PROJECT_DIR
+    // env var as a last resort.
+    if (!hasProjectConfig_) {
+        auto env_project = utils::get_env_or_default("XLINGS_PROJECT_DIR");
+        if (!env_project.empty()) {
+            auto dir = fs::path(env_project);
+            auto cfgFile = dir / ".xlings.json";
+            if (fs::exists(cfgFile, ec) && fs::is_regular_file(cfgFile, ec)) {
+                // Same xlings-home boundary check as the CWD walk:
+                // an env-var pointing at any xlings home (ours or a
+                // different one) is rejected, since project mode
+                // would derive paths that don't match the home's
+                // actual layout.
+                if (!looks_like_xlings_home(dir)) {
+                    load_project_config_from_dir_(dir);
+                }
+            }
+        }
+    }
+}
+
+void Config::load_global_versions_from_json_(const nlohmann::json& json) {
+    if (json.contains("versions") && json["versions"].is_object()) {
+        globalVersions_ = xvm::versions_from_json(json["versions"]);
+    } else {
+        globalVersions_.clear();
+    }
+}
+
+void Config::load_global_workspace_() {
+    auto subosConfigPath =
+        paths_.homeDir / "subos" / paths_.activeSubos / ".xlings.json";
+    auto sws = load_workspace_from_file_(subosConfigPath);
+    globalWorkspace_ = std::move(sws.active);
+    globalInstalled_ = std::move(sws.installed);
+}
+
+void Config::reload_state_() {
+    namespace fs = std::filesystem;
+    auto configPath = paths_.homeDir / ".xlings.json";
+    if (fs::exists(configPath)) {
+        try {
+            auto content = platform::read_file_to_string(configPath.string());
+            auto json = nlohmann::json::parse(content, nullptr, false);
+            if (!json.is_discarded()) load_global_versions_from_json_(json);
+        } catch (...) {}
+    } else {
+        globalVersions_.clear();
+    }
+    load_global_workspace_();
+    if (hasProjectConfig_) load_project_config_();
+    update_effective_paths_();
+}
+
+[[nodiscard]] std::vector<std::string> Config::workspace_install_targets(const xvm::Workspace& ws) {
+    return workspace_targets_from_workspace_(ws);
+}
+
+[[nodiscard]] xvm::VersionDB Config::merged_versions(const xvm::VersionDB& globalVersions,
+                                                        const xvm::VersionDB& projectVersions) {
+    auto db = globalVersions;
+    merge_versions_into_(db, projectVersions);
+    return db;
+}
+
+[[nodiscard]] xvm::Workspace Config::merged_workspace(const xvm::Workspace& globalWorkspace,
+                                                         const xvm::Workspace& projectWorkspace,
+                                                         const xvm::Workspace& projectSubosWorkspace,
+                                                         ProjectSubosMode mode) {
+    if (mode == ProjectSubosMode::Named) {
+        auto ws = projectWorkspace;
+        merge_workspace_into_(ws, projectSubosWorkspace);
+        return ws;
+    }
+
+    if (mode == ProjectSubosMode::Anonymous) {
+        auto ws = globalWorkspace;
+        merge_workspace_into_(ws, projectWorkspace);
+        merge_workspace_into_(ws, projectSubosWorkspace);
+        return ws;
+    }
+
+    return globalWorkspace;
+}
+
+void Config::reload_state() { instance_().reload_state_(); }
+
+[[nodiscard]] const Config::PathInfo& Config::paths() { return instance_().paths_; }
+
+[[nodiscard]] std::string Config::display_path(
+            const std::filesystem::path& p) {
+    const auto& home = paths().homeDir;
+    if (home.empty()) return p.string();
+    // lexically_relative rather than a string prefix test: it compares
+    // whole components, so a sibling `.xlings-backup` cannot match, and
+    // it resolves `..` on the way. A prefix test needed both of those
+    // bolted on by hand, and the hand-rolled version also normalized the
+    // separators of paths it was supposed to return untouched -- on
+    // Windows `/usr/lib` came back as `\usr\lib`, breaking the one
+    // promise this function makes about paths outside the home.
+    const auto rel = p.lexically_normal()
+                      .lexically_relative(home.lexically_normal());
+    if (rel.empty() || *rel.begin() == "..") return p.string();
+    if (rel == std::filesystem::path(".")) return "@xlings";
+    return (std::filesystem::path("@xlings") / rel).string();
+}
+
+[[nodiscard]] std::string Config::display_path(const std::string& p) {
+    return display_path(std::filesystem::path{p});
+}
+
+[[nodiscard]] const std::string& Config::mirror() { return instance_().mirror_; }
+
+[[nodiscard]] const std::string& Config::lang() { return instance_().lang_; }
+
+[[nodiscard]] std::vector<std::string> Config::resource_servers(std::string_view mirror) {
+    return instance_().candidate_resource_servers_for_(mirror);
+}
+
+[[nodiscard]] std::vector<std::string> Config::resource_servers_with_cross_region(std::string_view mirror) {
+    return instance_().all_resource_servers_for_(mirror);
+}
+
+[[nodiscard]] std::string Config::resource_server(std::string_view mirror) {
+    return instance_().selected_resource_server_for_(mirror);
+}
+
+[[nodiscard]] std::string Config::index_base() { return instance_().indexBase_; }
+
+[[nodiscard]] xvm::VersionDB Config::versions() {
+    auto& self = instance_();
+    return merged_versions(self.globalVersions_, self.projectVersions_);
+}
+
+[[nodiscard]] xvm::VersionDB& Config::versions_mut() {
+    auto& self = instance_();
+    if (self.forceGlobalScope_ || !self.hasProjectConfig_) return self.globalVersions_;
+    return self.projectVersions_;
+}
+
+[[nodiscard]] const xvm::VersionDB& Config::global_versions() { return instance_().globalVersions_; }
+
+[[nodiscard]] const xvm::VersionDB& Config::project_versions() { return instance_().projectVersions_; }
+
+[[nodiscard]] std::filesystem::path Config::global_data_dir() {
+    return instance_().paths_.dataDir;
+}
+
+[[nodiscard]] std::filesystem::path Config::project_data_dir() {
+    return instance_().project_data_dir_();
+}
+
+[[nodiscard]] std::filesystem::path Config::project_home_dir() {
+    return instance_().project_home_dir_();
+}
+
+[[nodiscard]] std::filesystem::path Config::project_state_path() {
+    return instance_().project_state_path_();
+}
+
+[[nodiscard]] std::filesystem::path Config::project_manifest_path() {
+    return instance_().project_manifest_path_();
+}
+
+[[nodiscard]] std::filesystem::path Config::effective_data_dir() {
+    auto& self = instance_();
+    if (self.hasProjectConfig_ && !self.projectDir_.empty() && !self.projectIndexRepos_.empty()) {
+        return self.project_data_dir_();
+    }
+    return self.paths_.dataDir;
+}
+
+[[nodiscard]] const std::vector<IndexRepo>& Config::global_index_repos() {
+    return instance_().globalIndexRepos_;
+}
+
+[[nodiscard]] const std::vector<IndexRepo>& Config::project_index_repos() {
+    return instance_().projectIndexRepos_;
+}
+
+[[nodiscard]] const std::vector<IndexRepo>& Config::index_repos() {
+    auto& self = instance_();
+    if (self.hasProjectConfig_ && !self.projectIndexRepos_.empty()) {
+        return self.projectIndexRepos_;
+    }
+    return self.globalIndexRepos_;
+}
+
+[[nodiscard]] std::filesystem::path Config::repo_dir_for(const IndexRepo& repo,
+                                                            bool projectScope) {
+    auto root = projectScope ? project_data_dir() : global_data_dir();
+    auto dirName = repo.name == DEFAULT_INDEX_REPO_NAME ? DEFAULT_INDEX_REPO_DIR : repo.name;
+    return root / dirName;
+}
+
+[[nodiscard]] std::filesystem::path Config::resolve_repo_source(const IndexRepo& repo,
+                                                                   bool projectScope) {
+    namespace fs = std::filesystem;
+    auto value = repo.url;
+    if (value.rfind("file://", 0) == 0) {
+        value.erase(0, 7);
+#ifdef _WIN32
+        // file:///C:/path → /C:/path after erase; strip leading '/' before drive letter
+        if (value.size() >= 3 && value[0] == '/' && std::isalpha(static_cast<unsigned char>(value[1])) && value[2] == ':') {
+            value.erase(0, 1);
+        }
+#endif
+        return fs::path(value).lexically_normal();
+    }
+    if (value.find("://") != std::string::npos) {
+        return {};
+    }
+
+    fs::path source(value);
+    if (source.is_absolute()) return source.lexically_normal();
+
+    auto base = projectScope ? project_dir() : paths().homeDir;
+    if (base.empty()) return source.lexically_normal();
+    return (base / source).lexically_normal();
+}
+
+[[nodiscard]] bool Config::is_local_repo_source(const IndexRepo& repo,
+                                                   bool projectScope) {
+    return !resolve_repo_source(repo, projectScope).empty();
+}
+
+[[nodiscard]] const std::filesystem::path& Config::project_dir() {
+    return instance_().projectDir_;
+}
+
+[[nodiscard]] ProjectSubosMode Config::project_subos_mode() {
+    return instance_().projectSubosMode_;
+}
+
+[[nodiscard]] const std::string& Config::project_subos_name() {
+    return instance_().projectSubosName_;
+}
+
+[[nodiscard]] xvm::Workspace Config::effective_workspace() {
+    auto& self = instance_();
+    // `-g` means "act on the home, not on this project" -- and that has to
+    // include which workspace is authoritative, not only which directory
+    // the artifacts land in. Honoring it for paths alone is how
+    // `install -g` wrote a shim into the home's subos while `remove -g`
+    // asked the project's workspace whether the package was there, got
+    // "no", and stopped: the same package, present and absent at once,
+    // depending on which half of the scope you read.
+    if (!self.hasProjectConfig_ || self.forceGlobalScope_) {
+        return self.globalWorkspace_;
+    }
+    return merged_workspace(self.globalWorkspace_,
+                            self.projectWorkspace_,
+                            self.projectSubosWorkspace_,
+                            self.projectSubosMode_);
+}
+
+[[nodiscard]] const xvm::Workspace& Config::workspace() {
+    auto& self = instance_();
+    if (self.forceGlobalScope_ || !self.hasProjectConfig_) return self.globalWorkspace_;
+    if (self.projectSubosMode_ == ProjectSubosMode::Named ||
+        self.projectSubosMode_ == ProjectSubosMode::Anonymous) return self.projectSubosWorkspace_;
+    return self.projectWorkspace_;
+}
+
+[[nodiscard]] xvm::Workspace& Config::workspace_mut() {
+    auto& self = instance_();
+    if (self.forceGlobalScope_ || !self.hasProjectConfig_) return self.globalWorkspace_;
+    if (self.projectSubosMode_ == ProjectSubosMode::Named ||
+        self.projectSubosMode_ == ProjectSubosMode::Anonymous) return self.projectSubosWorkspace_;
+    return self.projectWorkspace_;
+}
+
+[[nodiscard]] const xvm::WorkspaceInstalled& Config::workspace_installed() {
+    auto& self = instance_();
+    if (self.forceGlobalScope_ || !self.hasProjectConfig_) return self.globalInstalled_;
+    if (self.projectSubosMode_ == ProjectSubosMode::Named ||
+        self.projectSubosMode_ == ProjectSubosMode::Anonymous) return self.projectSubosInstalled_;
+    return self.globalInstalled_;
+}
+
+[[nodiscard]] xvm::WorkspaceInstalled& Config::workspace_installed_mut() {
+    auto& self = instance_();
+    if (self.forceGlobalScope_ || !self.hasProjectConfig_) return self.globalInstalled_;
+    if (self.projectSubosMode_ == ProjectSubosMode::Named ||
+        self.projectSubosMode_ == ProjectSubosMode::Anonymous) return self.projectSubosInstalled_;
+    return self.globalInstalled_;
+}
+
+[[nodiscard]] bool Config::has_project_config() { return instance_().hasProjectConfig_; }
+
+void Config::set_force_global_scope(bool force) {
+    auto& self = instance_();
+    if (self.forceGlobalScope_ == force) return;
+    self.forceGlobalScope_ = force;
+    self.update_effective_paths_();
+}
+
+std::string Config::set_active_subos_override(std::string name) {
+    auto& self = instance_();
+    auto previous = self.activeSubosOverride_;
+    if (previous == name) return previous;
+    self.activeSubosOverride_ = std::move(name);
+    // reload_state_, not just update_effective_paths_: the paths are
+    // derived state but so is the WORKSPACE, and that one is read by the
+    // activation path. Recomputing only the paths put a package in the
+    // right subos and then reported it absent, because the two readers
+    // were looking at different subos.
+    self.reload_state_();
+    return previous;
+}
+
+std::filesystem::path Config::subos_dir(const std::string& name) {
+    return instance_().paths_.homeDir / "subos" / name;
+}
+
+[[nodiscard]] std::filesystem::path Config::global_subos_dir() {
+    return instance_().global_subos_dir_();
+}
+
+[[nodiscard]] std::filesystem::path Config::global_subos_bin_dir() {
+    return global_subos_dir() / "bin";
+}
+
+[[nodiscard]] std::filesystem::path Config::xvm_artifact_subos_dir() {
+    return instance_().resolve_subos_scope_().root;
+}
+
+[[nodiscard]] SubosScope Config::subos_scope() {
+    return instance_().resolve_subos_scope_();
+}
+
+std::vector<std::string> Config::list_subos_names() {
+    std::vector<std::string> names;
+    auto dir = instance_().paths_.homeDir / "subos";
+    if (!std::filesystem::exists(dir)) return names;
+    for (auto& entry : platform::dir_entries(dir)) {
+        if (entry.is_directory()) {
+            auto name = entry.path().filename().string();
+            if (name != "current") names.push_back(name);
+        }
+    }
+    std::ranges::sort(names);
+    return names;
+}
+
+void Config::save_versions() {
+    namespace fs = std::filesystem;
+    auto& self = instance_();
+    bool useGlobal = self.forceGlobalScope_ || !self.hasProjectConfig_ || self.projectDir_.empty();
+    auto configPath = useGlobal
+        ? self.paths_.homeDir / ".xlings.json"
+        : self.project_state_path_();
+
+    if (!useGlobal) {
+        auto projectHomeDir = self.project_home_dir_();
+        if (!projectHomeDir.empty()) fs::create_directories(projectHomeDir);
+    }
+
+    nlohmann::json json;
+    if (fs::exists(configPath)) {
+        try {
+            auto content = platform::read_file_to_string(configPath.string());
+            json = nlohmann::json::parse(content, nullptr, false);
+            if (json.is_discarded()) json = nlohmann::json::object();
+        } catch (...) { json = nlohmann::json::object(); }
+    }
+
+    auto& versions = useGlobal ? self.globalVersions_ : self.projectVersions_;
+    json["versions"] = xvm::versions_to_json(versions);
+    platform::write_string_to_file(configPath.string(), json.dump(2));
+}
+
+[[nodiscard]] std::string Config::recorded_client_version() {
+    namespace fs = std::filesystem;
+    auto configPath = instance_().paths_.homeDir / ".xlings.json";
+    if (!fs::exists(configPath)) return {};
+    try {
+        auto content = platform::read_file_to_string(configPath.string());
+        auto json = nlohmann::json::parse(content, nullptr, false);
+        if (json.is_discarded() || !json.is_object()) return {};
+        auto it = json.find("version");
+        if (it == json.end() || !it->is_string()) return {};
+        return it->get<std::string>();
+    } catch (...) { return {}; }
+}
+
+void Config::record_client_version(const std::string& version) {
+    namespace fs = std::filesystem;
+    auto configPath = instance_().paths_.homeDir / ".xlings.json";
+    nlohmann::json json = nlohmann::json::object();
+    if (fs::exists(configPath)) {
+        try {
+            auto content = platform::read_file_to_string(configPath.string());
+            json = nlohmann::json::parse(content, nullptr, false);
+            if (json.is_discarded() || !json.is_object()) {
+                // Refuse to replace a file we could not parse. Overwriting
+                // it here would trade a stale version field for a lost
+                // versions DB.
+                return;
+            }
+        } catch (...) { return; }
+    }
+    json["version"] = version;
+    platform::write_string_to_file(configPath.string(), json.dump(2));
+}
+
+void Config::save_workspace() {
+    namespace fs = std::filesystem;
+    auto& self = instance_();
+    bool useProject = self.hasProjectConfig_ && !self.forceGlobalScope_;
+    fs::path subosConfigPath;
+    if (useProject &&
+        self.projectSubosMode_ == ProjectSubosMode::Named) {
+        auto projSubosDir = self.project_subos_dir_();
+        fs::create_directories(projSubosDir);
+        fs::create_directories(projSubosDir / "bin");
+        fs::create_directories(projSubosDir / "lib");
+        fs::create_directories(projSubosDir / "usr");
+        fs::create_directories(projSubosDir / "generations");
+        subosConfigPath = projSubosDir / ".xlings.json";
+    } else if (useProject &&
+               self.projectSubosMode_ == ProjectSubosMode::Anonymous) {
+        auto projSubosDir = self.project_subos_dir_();
+        auto projectHomeDir = self.project_home_dir_();
+        if (!projectHomeDir.empty()) fs::create_directories(projectHomeDir);
+        fs::create_directories(projSubosDir);
+        fs::create_directories(projSubosDir / "bin");
+        fs::create_directories(projSubosDir / "lib");
+        fs::create_directories(projSubosDir / "usr");
+        fs::create_directories(projSubosDir / "generations");
+        subosConfigPath = self.project_state_path_();
+    } else if (useProject && !self.projectDir_.empty()) {
+        auto projectHomeDir = self.project_home_dir_();
+        if (!projectHomeDir.empty()) fs::create_directories(projectHomeDir);
+        subosConfigPath = self.project_state_path_();
+    } else {
+        // useProject=false here — either no project config, or
+        // forceGlobalScope_ override is on (e.g. `xlings install -g`).
+        // Both paths mean "act on global scope, ignore project mode".
+        //
+        // We must NOT use paths_.activeSubos directly: when the user
+        // is inside an anonymous-project directory, paths_.activeSubos
+        // was set to "_" by update_effective_paths_ (the anonymous
+        // marker) and stays "_" even after forceGlobalScope_ flips
+        // useProject to false. Writing to `~/.xlings/subos/_/.xlings.json`
+        // (a directory that doesn't exist) then fails the workspace
+        // save — surfaced as `Failed to write file` during
+        // `xlings self install`'s patchelf-runtime-dep step (which
+        // spawns `xlings install -g`) when the user happens to run
+        // self install from inside an xlings repo / project tree.
+        //
+        // Resolve the same global-scope subos root used by XVM
+        // filesystem effects.
+        subosConfigPath =
+            self.global_subos_dir_() / ".xlings.json";
+    }
+
+    // XLINGS_HOME is a supported explicit scope, not proof that `self
+    // init` has already run. A first package install into a cold home
+    // reaches this writer after the payload is complete; create the state
+    // directory before persisting installed/active ownership so success
+    // is never followed by a spurious write failure (issue #471).
+    fs::create_directories(subosConfigPath.parent_path());
+
+    nlohmann::json json;
+    if (fs::exists(subosConfigPath)) {
+        try {
+            auto content = platform::read_file_to_string(subosConfigPath.string());
+            json = nlohmann::json::parse(content, nullptr, false);
+            if (json.is_discarded()) json = nlohmann::json::object();
+        } catch (...) { json = nlohmann::json::object(); }
+    }
+
+    // All four destination paths above target subos-side files
+    // (named project subos, anonymous project subos / state file, or
+    // global subos directory). The user-authored project manifest
+    // (`<proj>/.xlings.json`) is read-only from save_workspace's
+    // perspective and never reached here. So we always emit the
+    // 0.4.19+ C2 form via subos_workspace_to_json — backward-compat
+    // for legacy string-form values is in the *read* path
+    // (subos_workspace_from_json).
+    xvm::SubosWorkspace sws;
+    if (useProject &&
+        (self.projectSubosMode_ == ProjectSubosMode::Named ||
+         self.projectSubosMode_ == ProjectSubosMode::Anonymous)) {
+        sws.active = self.projectSubosWorkspace_;
+        sws.installed = self.projectSubosInstalled_;
+    } else if (useProject) {
+        // Reachable only via the third save-path branch above (project
+        // mode without a subos mode, currently unreachable in practice
+        // because load_project_config_from_dir_ always forces
+        // Anonymous when subos is unset). Write the project manifest
+        // workspace through with no installed[] info.
+        sws.active = self.projectWorkspace_;
+    } else {
+        sws.active = self.globalWorkspace_;
+        sws.installed = self.globalInstalled_;
+    }
+    json["workspace"] = xvm::subos_workspace_to_json(sws);
+    platform::write_string_to_file(subosConfigPath.string(), json.dump(2));
+}
+
+void Config::print_paths() {
+    auto& p = paths();
+    std::println(stdout, "XLINGS_HOME:     {}", p.homeDir.string());
+    std::println(stdout, "XLINGS_DATA:     {}", display_path(p.dataDir));
+    if (has_project_config() && !project_index_repos().empty()) {
+        std::println(stdout, "XLINGS_DATA_PROJECT: {}", display_path(project_data_dir()));
+    }
+    std::println(stdout, "XLINGS_SUBOS:    {}", display_path(p.subosDir));
+    std::println(stdout, "  activeSubos:   {}", p.activeSubos);
+    std::println(stdout, "  selfContained: {}", p.selfContained);
+    std::println(stdout, "  bin:           {}", display_path(p.binDir));
+}
+
+} // namespace xlings
diff --git a/src/core/config.cppm b/src/core/config.cppm
index 779c4ca7..fbd9839c 100644
--- a/src/core/config.cppm
+++ b/src/core/config.cppm
@@ -3,9 +3,6 @@ export module xlings.core.config;
 import std;
 
 import xlings.libs.json;
-import xlings.core.log;
-import xlings.platform;
-import xlings.core.utils;
 import xlings.libs.tinyhttps;
 import xlings.core.xvm.types;
 import xlings.core.xvm.db;
@@ -13,7 +10,7 @@ import xlings.core.xvm.db;
 namespace xlings {
 
 export struct Info {
-    static constexpr std::string_view VERSION = "2026.8.11.2";
+    static constexpr std::string_view VERSION = "2026.8.13.1";
     static constexpr std::string_view REPO = "https://github.com/openxlings/xlings";
 };
 
@@ -39,17 +36,9 @@ inline std::optional<std::string> ambientHome_;
 inline bool ambientHomeCaptured_ { false };
 }  // namespace detail_
 
-export void capture_ambient_home_env() {
-    if (detail_::ambientHomeCaptured_) return;   // first call wins
-    detail_::ambientHomeCaptured_ = true;
-    if (const char* v = std::getenv("XLINGS_HOME"); v != nullptr && *v != '\0') {
-        detail_::ambientHome_ = std::string(v);
-    }
-}
+export void capture_ambient_home_env();
 
-export const std::optional<std::string>& ambient_home_env() {
-    return detail_::ambientHome_;
-}
+export const std::optional<std::string>& ambient_home_env();
 
 export struct IndexRepo {
     std::string name;
@@ -68,39 +57,7 @@ export struct IndexRepo {
 // against `mirror` with GLOBAL fallback. `source` optionally overrides the
 // global index source for this repo only.
 export std::vector<IndexRepo> parse_index_repos_json(const nlohmann::json& json,
-                                                     const std::string& mirror) {
-    std::vector<IndexRepo> out;
-    if (!json.contains("index_repos") || !json["index_repos"].is_array()) return out;
-    for (auto it = json["index_repos"].begin(); it != json["index_repos"].end(); ++it) {
-        if (!it->is_object() || !it->contains("name") || !it->contains("url")) continue;
-        IndexRepo repo;
-        repo.name = (*it)["name"].get<std::string>();
-        repo.url  = (*it)["url"].get<std::string>();
-        if (repo.name.empty() || repo.url.empty()) continue;
-        if (it->contains("artifact")) {
-            auto& a = (*it)["artifact"];
-            std::string base;
-            if (a.is_string()) base = a.get<std::string>();
-            else if (a.is_object()) {
-                std::string key = mirror.empty() ? "GLOBAL" : mirror;
-                if (a.contains(key) && a[key].is_string()) base = a[key].get<std::string>();
-                else if (a.contains("GLOBAL") && a["GLOBAL"].is_string())
-                    base = a["GLOBAL"].get<std::string>();
-            }
-            base = utils::trim_string(base);
-            while (base.size() > 1 && base.ends_with('/')) base.pop_back();
-            repo.artifactBase = base;
-        }
-        if (it->contains("source") && (*it)["source"].is_string())
-            repo.source = (*it)["source"].get<std::string>();
-        // Not validated: the version namespace belongs to the index publisher,
-        // and xlings should not have an opinion about its shape.
-        if (it->contains("version") && (*it)["version"].is_string())
-            repo.version = (*it)["version"].get<std::string>();
-        out.push_back(std::move(repo));
-    }
-    return out;
-}
+                                                     const std::string& mirror);
 
 using MirrorServerMap = std::unordered_map<std::string, std::vector<std::string>>;
 
@@ -139,15 +96,10 @@ public:
     // dispatch home BEFORE first Config use. main.cpp calls this for shim
     // invocations only — the xlings CLI keeps the env-first resolution.
     // Has no effect once the singleton is constructed.
-    static void override_home(const std::filesystem::path& home) {
-        home_override_() = home;
-    }
+    static void override_home(const std::filesystem::path& home);
 
 private:
-    static std::optional<std::filesystem::path>& home_override_() {
-        static std::optional<std::filesystem::path> v;
-        return v;
-    }
+    static std::optional<std::filesystem::path>& home_override_();
 
     PathInfo paths_;
     std::string mirror_;
@@ -181,270 +133,57 @@ private:
     static constexpr std::string_view DEFAULT_INDEX_REPO_NAME = "xim";
     static constexpr std::string_view DEFAULT_INDEX_REPO_DIR = "xim-pkgindex";
 
-    static std::vector<IndexRepo> default_global_index_repos_(const std::string& mirror) {
-        std::string url = "https://github.com/openxlings/xim-pkgindex.git";
-        if (mirror == "CN") {
-            url = "https://gitee.com/sunrisepeak/xim-pkgindex.git";
-        }
-        return { IndexRepo{std::string(DEFAULT_INDEX_REPO_NAME), url} };
-    }
+    static std::vector<IndexRepo> default_global_index_repos_(const std::string& mirror);
 
-    static MirrorServerMap default_resource_servers_() {
-        return {
-            { "GLOBAL", { "https://github.com/xlings-res" } },
-            { "CN", { "https://gitcode.com/xlings-res" } },
-        };
-    }
+    static MirrorServerMap default_resource_servers_();
 
     // Resolve xim.index-base from a config json. Accepts a flat string or a
     // region object {"GLOBAL":"...","CN":"..."}. Lets a deployment point the
     // index pointer+artifact at a self-hosted server without code changes.
-    static std::string resolve_index_base_(const nlohmann::json& json, const std::string& mirror) {
-        if (!json.contains("xim") || !json["xim"].is_object()) return {};
-        auto& xim = json["xim"];
-        if (!xim.contains("index-base")) return {};
-        auto& ib = xim["index-base"];
-        if (ib.is_string()) return ib.get<std::string>();
-        if (ib.is_object()) {
-            std::string key = mirror.empty() ? "GLOBAL" : mirror;
-            if (ib.contains(key) && ib[key].is_string()) return ib[key].get<std::string>();
-            if (ib.contains("GLOBAL") && ib["GLOBAL"].is_string()) return ib["GLOBAL"].get<std::string>();
-        }
-        return {};
-    }
+    static std::string resolve_index_base_(const nlohmann::json& json, const std::string& mirror);
 
-    static std::vector<std::string> parse_server_list_(const nlohmann::json& value) {
-        std::vector<std::string> servers;
-        auto append_server = [&](std::string server) {
-            server = utils::trim_string(server);
-            while (server.size() > 1 && server.ends_with('/')) {
-                server.pop_back();
-            }
-            if (server.empty()) return;
-            if (std::ranges::find(servers, server) == servers.end()) {
-                servers.push_back(std::move(server));
-            }
-        };
-
-        if (value.is_string()) {
-            append_server(value.get<std::string>());
-        } else if (value.is_array()) {
-            for (auto& item : value) {
-                if (item.is_string()) append_server(item.get<std::string>());
-            }
-        }
-        return servers;
-    }
+    static std::vector<std::string> parse_server_list_(const nlohmann::json& value);
 
-    static void merge_resource_servers_into_(MirrorServerMap& dst, const MirrorServerMap& src) {
-        for (auto& [mirror, servers] : src) {
-            if (!servers.empty()) dst[mirror] = servers;
-        }
-    }
+    static void merge_resource_servers_into_(MirrorServerMap& dst, const MirrorServerMap& src);
 
     static void load_resource_servers_from_json_(const nlohmann::json& json,
-                                                 MirrorServerMap& out) {
-        out.clear();
-
-        auto normalize_key = [](std::string key) {
-            key = utils::trim_string(key);
-            if (key == "default" || key == "DEFAULT" || key == "_default") return std::string("DEFAULT");
-            return key;
-        };
-
-        auto load_object = [&](const nlohmann::json& obj) {
-            if (!obj.is_object()) return;
-            for (auto it = obj.begin(); it != obj.end(); ++it) {
-                auto servers = parse_server_list_(it.value());
-                if (!servers.empty()) out[normalize_key(it.key())] = std::move(servers);
-            }
-        };
-
-        auto load_default_list = [&](const nlohmann::json& value) {
-            auto servers = parse_server_list_(value);
-            if (!servers.empty()) out["DEFAULT"] = std::move(servers);
-        };
-
-        if (json.contains("XLINGS_RES")) {
-            if (json["XLINGS_RES"].is_object()) {
-                load_object(json["XLINGS_RES"]);
-            } else {
-                load_default_list(json["XLINGS_RES"]);
-            }
-        }
-
-        // Backward compatibility for older config shapes.
-        if (out.empty()) {
-            if (json.contains("resource_server")) {
-                load_default_list(json["resource_server"]);
-            }
-
-            if (json.contains("resource_servers")) {
-                if (json["resource_servers"].is_object()) {
-                    load_object(json["resource_servers"]);
-                } else {
-                    load_default_list(json["resource_servers"]);
-                }
-            }
-
-            if (json.contains("res_servers")) {
-                if (json["res_servers"].is_object()) {
-                    load_object(json["res_servers"]);
-                } else {
-                    load_default_list(json["res_servers"]);
-                }
-            }
-
-            if (json.contains("xim") && json["xim"].is_object()) {
-                auto& xim = json["xim"];
-                if (xim.contains("mirrors") && xim["mirrors"].is_object()) {
-                    auto& mirrors = xim["mirrors"];
-                    if (mirrors.contains("res-server")) {
-                        load_object(mirrors["res-server"]);
-                    }
-                }
-            }
-        }
-    }
+                                                 MirrorServerMap& out);
 
     // Read a subos `.xlings.json` workspace section. Returns the new
     // SubosWorkspace bundle so callers get both `active` (Workspace) and
     // `installed[]` (WorkspaceInstalled). Legacy string-form values still
     // parse cleanly — installed[] just stays empty until the next save
     // re-emits the file in C2 form.
-    static xvm::SubosWorkspace load_workspace_from_file_(const std::filesystem::path& path) {
-        namespace fs = std::filesystem;
-        if (!fs::exists(path)) return {};
-        try {
-            auto content = platform::read_file_to_string(path.string());
-            auto json = nlohmann::json::parse(content, nullptr, false);
-            if (!json.is_discarded() && json.contains("workspace") && json["workspace"].is_object()) {
-                return xvm::subos_workspace_from_json(json["workspace"]);
-            }
-        } catch (...) {}
-        return {};
-    }
+    static xvm::SubosWorkspace load_workspace_from_file_(const std::filesystem::path& path);
 
-    static std::string load_project_subos_name_(const nlohmann::json& json) {
-        if (json.contains("subos") && json["subos"].is_string()) {
-            auto val = json["subos"].get<std::string>();
-            if (!val.empty()) return val;
-        }
-        if (json.contains("projectSubos") && json["projectSubos"].is_string()) {
-            auto val = json["projectSubos"].get<std::string>();
-            if (!val.empty()) return val;
-        }
-        return {};
-    }
+    static std::string load_project_subos_name_(const nlohmann::json& json);
 
-    static void merge_versions_into_(xvm::VersionDB& dst, const xvm::VersionDB& src) {
-        for (auto& [target, info] : src) {
-            auto& dstInfo = dst[target];
-            if (dstInfo.type.empty() && !info.type.empty())
-                dstInfo.type = info.type;
-            if (dstInfo.filename.empty() && !info.filename.empty())
-                dstInfo.filename = info.filename;
-            for (auto& [ver, vdata] : info.versions) {
-                dstInfo.versions[ver] = vdata;
-            }
-            for (auto& [name, vermap] : info.bindings) {
-                for (auto& [ver, value] : vermap) {
-                    dstInfo.bindings[name][ver] = value;
-                }
-            }
-        }
-    }
+    static void merge_versions_into_(xvm::VersionDB& dst, const xvm::VersionDB& src);
 
-    static void merge_workspace_into_(xvm::Workspace& dst, const xvm::Workspace& src) {
-        for (auto& [target, version] : src) {
-            dst[target] = version;
-        }
-    }
+    static void merge_workspace_into_(xvm::Workspace& dst, const xvm::Workspace& src);
 
     static std::string effective_mirror_name_(std::string_view mirror,
-                                              std::string_view fallback) {
-        auto name = std::string(mirror.empty() ? fallback : mirror);
-        if (name.empty()) return "GLOBAL";
-        return name;
-    }
+                                              std::string_view fallback);
 
-    static std::vector<std::string> workspace_targets_from_workspace_(const xvm::Workspace& ws) {
-        std::vector<std::string> targets;
-        targets.reserve(ws.size());
-        for (auto& [name, version] : ws) {
-            if (name.empty()) continue;
-            if (version.empty()) {
-                targets.push_back(name);
-            } else {
-                targets.push_back(name + "@" + version);
-            }
-        }
-        return targets;
-    }
+    static std::vector<std::string> workspace_targets_from_workspace_(const xvm::Workspace& ws);
 
-    [[nodiscard]] std::filesystem::path project_data_dir_() const {
-        return projectDir_.empty() ? std::filesystem::path{} : projectDir_ / ".xlings" / "data";
-    }
+    [[nodiscard]] std::filesystem::path project_data_dir_() const;
 
-    [[nodiscard]] std::filesystem::path project_home_dir_() const {
-        return projectDir_.empty() ? std::filesystem::path{} : projectDir_ / ".xlings";
-    }
+    [[nodiscard]] std::filesystem::path project_home_dir_() const;
 
-    [[nodiscard]] std::filesystem::path project_state_path_() const {
-        auto homeDir = project_home_dir_();
-        if (homeDir.empty()) return {};
-        return homeDir / ".xlings.json";
-    }
+    [[nodiscard]] std::filesystem::path project_state_path_() const;
 
-    [[nodiscard]] std::filesystem::path project_manifest_path_() const {
-        return projectDir_.empty() ? std::filesystem::path{} : projectDir_ / ".xlings.json";
-    }
+    [[nodiscard]] std::filesystem::path project_manifest_path_() const;
 
-    [[nodiscard]] std::filesystem::path project_subos_dir_() const {
-        if (projectDir_.empty()) return {};
-        if (!projectSubosName_.empty()) return projectDir_ / ".xlings" / "subos" / projectSubosName_;
-        if (projectSubosMode_ == ProjectSubosMode::Anonymous) return projectDir_ / ".xlings" / "subos" / "_";
-        return {};
-    }
+    [[nodiscard]] std::filesystem::path project_subos_dir_() const;
 
-    [[nodiscard]] std::filesystem::path global_subos_dir_() const {
-        auto activeSubos = utils::get_env_or_default(
-            "XLINGS_ACTIVE_SUBOS");
-        if (activeSubos.empty()) {
-            activeSubos = globalActiveSubos_;
-        }
-        return paths_.homeDir / "subos" / activeSubos;
-    }
+    [[nodiscard]] std::filesystem::path global_subos_dir_() const;
 
     [[nodiscard]] static std::vector<std::string>
-    lookup_resource_servers_in_(const MirrorServerMap& source, std::string_view mirror) {
-        auto key = effective_mirror_name_(mirror, "GLOBAL");
-        if (auto it = source.find(key); it != source.end() && !it->second.empty()) {
-            return it->second;
-        }
-        if (auto it = source.find("DEFAULT"); it != source.end() && !it->second.empty()) {
-            return it->second;
-        }
-        return {};
-    }
+    lookup_resource_servers_in_(const MirrorServerMap& source, std::string_view mirror);
 
     [[nodiscard]] std::vector<std::string>
-    candidate_resource_servers_for_(std::string_view mirror) const {
-        auto key = effective_mirror_name_(mirror, mirror_);
-
-        auto project = lookup_resource_servers_in_(projectResourceServers_, key);
-        if (!project.empty()) return project;
-
-        auto global = lookup_resource_servers_in_(globalResourceServers_, key);
-        if (!global.empty()) return global;
-
-        auto defaults = lookup_resource_servers_in_(default_resource_servers_(), key);
-        if (!defaults.empty()) return defaults;
-
-        auto fallback = lookup_resource_servers_in_(default_resource_servers_(), "GLOBAL");
-        if (!fallback.empty()) return fallback;
-        return {};
-    }
+    candidate_resource_servers_for_(std::string_view mirror) const;
 
     // Every resource server worth trying: this region's candidates first, then
     // every other region's, deduplicated.
@@ -463,70 +202,11 @@ private:
     // ever tried after every same-region one has failed, so nobody in CN
     // starts pulling from GitHub while GitCode is serving.
     [[nodiscard]] std::vector<std::string>
-    all_resource_servers_for_(std::string_view mirror) const {
-        auto servers = candidate_resource_servers_for_(mirror);
-        auto key = effective_mirror_name_(mirror, mirror_);
-
-        std::set<std::string> seen(servers.begin(), servers.end());
-        auto append_other_regions = [&](const MirrorServerMap& source) {
-            // unordered_map: sort the keys so the fallback order is the same
-            // on every run and every machine.
-            std::vector<std::string> regions;
-            for (const auto& [region, _] : source) {
-                if (region != key) regions.push_back(region);
-            }
-            std::ranges::sort(regions);
-            for (const auto& region : regions) {
-                for (const auto& server : source.at(region)) {
-                    if (seen.insert(server).second) servers.push_back(server);
-                }
-            }
-        };
-        append_other_regions(projectResourceServers_);
-        append_other_regions(globalResourceServers_);
-        append_other_regions(default_resource_servers_());
-        return servers;
-    }
+    all_resource_servers_for_(std::string_view mirror) const;
 
-    static double probe_resource_server_latency_(const std::string& server) {
-        return tinyhttps::probe_latency(server, 2000);
-    }
+    static double probe_resource_server_latency_(const std::string& server);
 
-    [[nodiscard]] std::string selected_resource_server_for_(std::string_view mirror) const {
-        auto key = effective_mirror_name_(mirror, mirror_);
-        {
-            std::scoped_lock lock(resourceServerMutex_);
-            if (auto it = selectedResourceServerCache_.find(key);
-                it != selectedResourceServerCache_.end()) {
-                return it->second;
-            }
-        }
-
-        auto candidates = candidate_resource_servers_for_(key);
-        if (candidates.empty()) return {};
-
-        auto selected = candidates.front();
-        if (candidates.size() > 1) {
-            double bestLatency = std::numeric_limits<double>::infinity();
-            for (auto& candidate : candidates) {
-                auto latency = probe_resource_server_latency_(candidate);
-                if (latency < bestLatency) {
-                    bestLatency = latency;
-                    selected = candidate;
-                }
-                if (std::isfinite(latency) && latency <= 0.1) {
-                    selected = candidate;
-                    break;
-                }
-            }
-        }
-
-        {
-            std::scoped_lock lock(resourceServerMutex_);
-            selectedResourceServerCache_[key] = selected;
-        }
-        return selected;
-    }
+    [[nodiscard]] std::string selected_resource_server_for_(std::string_view mirror) const;
 
     // The ONE answer to "which subos is this process acting on".
     //
@@ -551,356 +231,19 @@ private:
     // read `paths()`, i.e. the first. Installing into one subos and cleaning
     // another is not a bug that can be fixed at a call site; it is what having
     // two authorities means.
-    [[nodiscard]] SubosScope resolve_subos_scope_() const {
-        // An explicit override wins over everything, including a project
-        // config. It exists for the case where a command must act on a subos
-        // it just created rather than on the one the user is standing in —
-        // `subos new --runtime` installing what it declared.
-        if (!activeSubosOverride_.empty()) {
-            return {activeSubosOverride_,
-                    paths_.homeDir / "subos" / activeSubosOverride_};
-        }
-        const bool useProject = hasProjectConfig_ && !forceGlobalScope_;
-        if (useProject && projectSubosMode_ == ProjectSubosMode::Named
-            && !projectSubosName_.empty()) {
-            return {projectSubosName_, project_subos_dir_()};
-        }
-        if (useProject && projectSubosMode_ == ProjectSubosMode::Anonymous) {
-            return {"_", project_subos_dir_()};
-        }
-        auto name = utils::get_env_or_default("XLINGS_ACTIVE_SUBOS");
-        if (name.empty()) name = globalActiveSubos_;
-        return {name, paths_.homeDir / "subos" / name};
-    }
+    [[nodiscard]] SubosScope resolve_subos_scope_() const;
 
-    void update_effective_paths_() {
-        auto scope = resolve_subos_scope_();
-        paths_.activeSubos = std::move(scope.name);
-        paths_.subosDir = std::move(scope.root);
-        paths_.binDir = paths_.subosDir / "bin";
-        paths_.libDir = paths_.subosDir / "lib";
-    }
+    void update_effective_paths_();
 
-    Config() {
-        namespace fs = std::filesystem;
-
-        auto envHome = utils::get_env_or_default("XLINGS_HOME");
-        if (auto& anchored = home_override_(); anchored && !anchored->empty()) {
-            // Owner-anchored shim dispatch: the dispatch home was chosen
-            // before Config construction (main.cpp → resolve_dispatch_home).
-            paths_.homeDir = *anchored;
-        } else if (!envHome.empty()) {
-            paths_.homeDir = envHome;
-        } else {
-            auto exePath   = platform::get_executable_path();
-            auto exeParent = exePath.parent_path();
-            auto candidate = exeParent.parent_path();
-            auto hasRootConfig = !exePath.empty() && fs::exists(candidate / ".xlings.json");
-            constexpr auto kBinName = (platform::OS_NAME == "windows")
-                ? "bin/xlings.exe" : "bin/xlings";
-            auto hasRootBin = !exePath.empty() && fs::exists(candidate / kBinName);
-
-            bool isSelfContained = hasRootConfig && hasRootBin;
-            if constexpr (platform::OS_NAME == "windows") {
-                // Windows: shims are hardlinks/copies (not symlinks), so
-                // get_executable_path() returns the shim path inside a subos
-                // dir (e.g. ~/.xlings/subos/current/bin/xlings.exe). That
-                // directory has both .xlings.json and bin/xlings.exe, falsely
-                // matching the selfContained pattern. Disambiguate by checking
-                // json content: real home/selfContained config always has both
-                // "version" and "activeSubos"; subos config only has workspace.
-                if (isSelfContained) {
-                    try {
-                        auto cfg = platform::read_file_to_string(
-                            (candidate / ".xlings.json").string());
-                        auto j = nlohmann::json::parse(cfg, nullptr, false);
-                        isSelfContained = !j.is_discarded()
-                            && j.contains("version")
-                            && j.contains("activeSubos");
-                    } catch (...) { isSelfContained = false; }
-                }
-            }
-            if (isSelfContained) {
-                paths_.homeDir       = candidate;
-                paths_.selfContained = true;
-            } else {
-                paths_.homeDir = fs::path(platform::get_home_dir()) / ".xlings";
-            }
-        }
-
-        auto configPath = paths_.homeDir / ".xlings.json";
-        if (fs::exists(configPath)) {
-            try {
-                auto content = platform::read_file_to_string(configPath.string());
-                auto json    = nlohmann::json::parse(content, nullptr, false);
-                if (!json.is_discarded()) {
-                    if (json.contains("activeSubos") && json["activeSubos"].is_string()) {
-                        auto val = json["activeSubos"].get<std::string>();
-                        if (!val.empty()) globalActiveSubos_ = val;
-                    }
-                    if (json.contains("mirror") && json["mirror"].is_string())
-                        mirror_ = json["mirror"].get<std::string>();
-                    if (json.contains("lang") && json["lang"].is_string())
-                        lang_ = json["lang"].get<std::string>();
-                    // Load global versions
-                    load_global_versions_from_json_(json);
-                    globalIndexRepos_ = parse_index_repos_json(json, mirror_);
-                    load_resource_servers_from_json_(json, globalResourceServers_);
-                    if (auto v = resolve_index_base_(json, mirror_); !v.empty()) indexBase_ = v;
-                }
-            } catch (...) {}
-        }
-        if (globalIndexRepos_.empty()) {
-            globalIndexRepos_ = default_global_index_repos_(mirror_);
-        } else {
-            // Ensure the default index repo is always present when user
-            // defines custom index_repos (e.g. adding "ros2").  Without
-            // this, user-defined repos replace the default and packages
-            // in the primary index (like "python") become unfindable.
-            auto defaults = default_global_index_repos_(mirror_);
-            for (auto& def : defaults) {
-                bool found = false;
-                for (auto& repo : globalIndexRepos_) {
-                    if (repo.name == def.name) { found = true; break; }
-                }
-                if (!found) {
-                    globalIndexRepos_.insert(globalIndexRepos_.begin(), std::move(def));
-                }
-            }
-        }
-
-        paths_.dataDir  = paths_.homeDir / "data";
-        update_effective_paths_();
-
-        log::debug("config: home={}, selfContained={}", paths_.homeDir.string(), paths_.selfContained);
-
-        // Load subos workspace from the path resolved by
-        // update_effective_paths_, which honors XLINGS_ACTIVE_SUBOS env
-        // overrides. Using `globalActiveSubos_` directly here (a snapshot
-        // of `~/.xlings.json activeSubos`) would silently load the wrong
-        // subos's workspace whenever the user is in a spawned subos shell
-        // with XLINGS_ACTIVE_SUBOS set, which then corrupts that subos
-        // when `xvm use` writes back through save_workspace().
-        load_global_workspace_();
-
-        // Load project-level config (walk up from cwd)
-        load_project_config_();
-        update_effective_paths_();
-    }
+    Config();
 
-    void load_project_config_from_dir_(const std::filesystem::path& dir) {
-        namespace fs = std::filesystem;
-        auto cfg = dir / ".xlings.json";
-        log::debug("config: loading project config from {}", cfg.string());
-        try {
-            auto content = platform::read_file_to_string(cfg.string());
-            auto json = nlohmann::json::parse(content, nullptr, false);
-            if (!json.is_discarded()) {
-                // Build-deps-only files (e.g. xlings's own repo-root
-                // /.xlings.json declaring CI dependencies) opt out of
-                // project mode by setting `"projectScope": false`. This
-                // lets `xlings install` from the repo root still read
-                // the `workspace` field, but skips project-subos
-                // activation, project-state writes, and the project_dir
-                // env-export that downstream shims would otherwise pick
-                // up. Search continues upward as if this file weren't here.
-                //
-                // TODO(2026-): this flag is a workaround for the
-                // chicken-and-egg of "xlings's own repo wants to declare
-                // build deps via .xlings.json without becoming a
-                // managed xlings project". Cleaner long-term options:
-                //
-                //   1. Embrace project mode at the repo root: rewrite
-                //      tests / dev workflow to assume the xlings repo
-                //      IS a managed project; drop this flag entirely.
-                //   2. Add `xlings env` / `xlings config --pkgdir <name>`
-                //      so CI doesn't need to assume payload paths or
-                //      hand-export toolchain env vars at all — the
-                //      installed-subos PATH + xmake auto-detect already
-                //      cover it for the common case (see CI workflows
-                //      that drop --sdk/--cross thanks to musl-gcc's
-                //      gcc-flavor shims), but cross-compile / non-default
-                //      toolchain selections still need explicit values.
-                //   3. Split: keep `.xlings.json` for `xlings install`
-                //      workspace reads, but introduce a separate
-                //      schema-level marker (e.g. top-level
-                //      `"kind": "build-deps"`) checked here.
-                //
-                // Track these in a single follow-up issue once the CI
-                // self-host PR has soaked in.
-                if (json.contains("projectScope") &&
-                    json["projectScope"].is_boolean() &&
-                    !json["projectScope"].get<bool>()) {
-                    log::debug("config: skipping {} (projectScope=false)", cfg.string());
-                    return;
-                }
-                projectDir_ = dir;
-                hasProjectConfig_ = true;
-                // Export project dir so child processes (shims, os.execute)
-                // can find project workspace even when CWD changes.
-                platform::set_env_variable("XLINGS_PROJECT_DIR", dir.string());
-                // Project-level mirror/lang override global
-                if (json.contains("mirror") && json["mirror"].is_string())
-                    mirror_ = json["mirror"].get<std::string>();
-                if (json.contains("lang") && json["lang"].is_string())
-                    lang_ = json["lang"].get<std::string>();
-                if (json.contains("workspace") && json["workspace"].is_object()) {
-                    projectWorkspace_ = xvm::workspace_from_json(json["workspace"]);
-                }
-                projectIndexRepos_ = parse_index_repos_json(json, mirror_);
-                load_resource_servers_from_json_(json, projectResourceServers_);
-                if (auto v = resolve_index_base_(json, mirror_); !v.empty()) indexBase_ = v;  // project overrides global
-                projectSubosName_ = load_project_subos_name_(json);
-
-                auto projectStatePath = project_state_path_();
-                nlohmann::json projectStateJson;
-                bool hasProjectStateJson = false;
-                if (!projectStatePath.empty() && fs::exists(projectStatePath)) {
-                    try {
-                        auto stateContent = platform::read_file_to_string(projectStatePath.string());
-                        projectStateJson = nlohmann::json::parse(stateContent, nullptr, false);
-                        hasProjectStateJson = !projectStateJson.is_discarded() && projectStateJson.is_object();
-                    } catch (...) {
-                        hasProjectStateJson = false;
-                    }
-                }
-
-                if (hasProjectStateJson && projectStateJson.contains("versions") &&
-                    projectStateJson["versions"].is_object()) {
-                    projectVersions_ = xvm::versions_from_json(projectStateJson["versions"]);
-                } else if (json.contains("versions") && json["versions"].is_object()) {
-                    projectVersions_ = xvm::versions_from_json(json["versions"]);
-                }
-
-                if (!projectSubosName_.empty()) {
-                    projectSubosMode_ = ProjectSubosMode::Named;
-                    auto sws = load_workspace_from_file_(project_subos_dir_() / ".xlings.json");
-                    projectSubosWorkspace_ = std::move(sws.active);
-                    projectSubosInstalled_ = std::move(sws.installed);
-                } else {
-                    projectSubosMode_ = ProjectSubosMode::Anonymous;
-                    if (hasProjectStateJson && projectStateJson.contains("workspace") &&
-                        projectStateJson["workspace"].is_object()) {
-                        auto sws = xvm::subos_workspace_from_json(projectStateJson["workspace"]);
-                        projectSubosWorkspace_ = std::move(sws.active);
-                        projectSubosInstalled_ = std::move(sws.installed);
-                    } else {
-                        auto sws = load_workspace_from_file_(project_subos_dir_() / ".xlings.json");
-                        projectSubosWorkspace_ = std::move(sws.active);
-                        projectSubosInstalled_ = std::move(sws.installed);
-                    }
-                }
-            }
-        } catch (...) {}
-    }
+    void load_project_config_from_dir_(const std::filesystem::path& dir);
 
-    void load_project_config_() {
-        namespace fs = std::filesystem;
-        std::error_code ec;
-
-        fs::path startDir = fs::current_path(ec);
-        if (ec) return;
-
-        auto homeNorm = fs::weakly_canonical(paths_.homeDir, ec);
-
-        // Walk cwd → root, looking for a `.xlings.json` that activates project
-        // mode. A file with `projectScope: false` is "deps-manifest only" — it
-        // declares deps for `xlings install` but does NOT mean its directory is
-        // a project root (e.g. xlings's own repo uses this to install build
-        // deps without making the repo look like a user project to nested
-        // commands). load_project_config_from_dir_ honors that opt-out by
-        // returning without setting hasProjectConfig_.
-        //
-        // Critical: when from_dir_ skips a projectScope:false file, we must
-        // NOT early-return — that would hide the real project from any
-        // subprocess whose cwd traversal happens to hit such a file before
-        // reaching the actual project. Instead, continue walking up; if no
-        // real project is found in the rest of the walk, the env-var fallback
-        // below picks it up (the parent xlings exports XLINGS_PROJECT_DIR
-        // whenever it loads a real project, so subprocesses can recover the
-        // intended project context even when their cwd is outside the project
-        // tree).
-        // 0.4.20+: xlings-home boundary detection.
-        //
-        // A directory that contains BOTH `.xlings.json` and a `subos/`
-        // sibling directory is an xlings home (ours or some other one) —
-        // never a user project. Project layouts have their state under
-        // `.xlings/subos/`, NOT a bare `subos/` at the same level as
-        // the manifest. Stop walking at any such boundary.
-        //
-        // Without this, a nested xlings home (e.g. mcpp packaged under
-        // ~/.xlings/data/xpkgs/<repo>-x-mcpp/<ver>/registry/, where the
-        // inner xlings sets XLINGS_HOME to the registry dir) would see
-        // its CWD walk skip the inner home (homeNorm match), continue
-        // upward through the package layers, and ultimately mis-load the
-        // OUTER ~/.xlings/.xlings.json as if it were a user project root.
-        // That polluted projectDir_ with the outer home and routed every
-        // subsequent install/shim/workspace path into a phantom
-        // ~/.xlings/.xlings/{subos,data,...} tree disjoint from where
-        // mcpp's recipe actually puts its files.
-        //
-        // The boundary check subsumes the previous `curNorm != homeNorm`
-        // gate: our own home also matches the signature, so the break
-        // covers it. Any directory that "looks like" an xlings home
-        // (regardless of whose) terminates the project walk.
-        auto looks_like_xlings_home = [&](const fs::path& dir) {
-            std::error_code lec;
-            return fs::is_directory(dir / "subos", lec);
-        };
-
-        fs::path cur = startDir;
-        while (!cur.empty()) {
-            auto cfg = cur / ".xlings.json";
-            if (fs::exists(cfg, ec) && fs::is_regular_file(cfg, ec)) {
-                if (looks_like_xlings_home(cur)) {
-                    break;                              // hit an xlings home — never project
-                }
-                load_project_config_from_dir_(cur);
-                if (hasProjectConfig_) return;          // real project loaded
-                // else: projectScope:false skip — keep walking, then env fallback
-            }
-            auto parent = cur.parent_path();
-            if (parent == cur) break;
-            cur = parent;
-        }
-
-        // CWD traversal did not find project config (either no .xlings.json
-        // at all, or only projectScope:false ones) — check XLINGS_PROJECT_DIR
-        // env var as a last resort.
-        if (!hasProjectConfig_) {
-            auto env_project = utils::get_env_or_default("XLINGS_PROJECT_DIR");
-            if (!env_project.empty()) {
-                auto dir = fs::path(env_project);
-                auto cfgFile = dir / ".xlings.json";
-                if (fs::exists(cfgFile, ec) && fs::is_regular_file(cfgFile, ec)) {
-                    // Same xlings-home boundary check as the CWD walk:
-                    // an env-var pointing at any xlings home (ours or a
-                    // different one) is rejected, since project mode
-                    // would derive paths that don't match the home's
-                    // actual layout.
-                    if (!looks_like_xlings_home(dir)) {
-                        load_project_config_from_dir_(dir);
-                    }
-                }
-            }
-        }
-    }
+    void load_project_config_();
 
-    void load_global_versions_from_json_(const nlohmann::json& json) {
-        if (json.contains("versions") && json["versions"].is_object()) {
-            globalVersions_ = xvm::versions_from_json(json["versions"]);
-        } else {
-            globalVersions_.clear();
-        }
-    }
+    void load_global_versions_from_json_(const nlohmann::json& json);
 
-    void load_global_workspace_() {
-        auto subosConfigPath =
-            paths_.homeDir / "subos" / paths_.activeSubos / ".xlings.json";
-        auto sws = load_workspace_from_file_(subosConfigPath);
-        globalWorkspace_ = std::move(sws.active);
-        globalInstalled_ = std::move(sws.installed);
-    }
+    void load_global_workspace_();
 
     // Re-read the mutable state layers from disk.
     //
@@ -915,22 +258,7 @@ private:
     // Mirror, language and index-repo resolution stay as they were resolved
     // at startup -- re-deriving those mid-command would change behavior
     // under the user rather than protect it.
-    void reload_state_() {
-        namespace fs = std::filesystem;
-        auto configPath = paths_.homeDir / ".xlings.json";
-        if (fs::exists(configPath)) {
-            try {
-                auto content = platform::read_file_to_string(configPath.string());
-                auto json = nlohmann::json::parse(content, nullptr, false);
-                if (!json.is_discarded()) load_global_versions_from_json_(json);
-            } catch (...) {}
-        } else {
-            globalVersions_.clear();
-        }
-        load_global_workspace_();
-        if (hasProjectConfig_) load_project_config_();
-        update_effective_paths_();
-    }
+    void reload_state_();
 
     static Config& instance_() {
         static Config inst;
@@ -938,43 +266,22 @@ private:
     }
 
 public:
-    [[nodiscard]] static std::vector<std::string> workspace_install_targets(const xvm::Workspace& ws) {
-        return workspace_targets_from_workspace_(ws);
-    }
+    [[nodiscard]] static std::vector<std::string> workspace_install_targets(const xvm::Workspace& ws);
 
     [[nodiscard]] static xvm::VersionDB merged_versions(const xvm::VersionDB& globalVersions,
-                                                        const xvm::VersionDB& projectVersions) {
-        auto db = globalVersions;
-        merge_versions_into_(db, projectVersions);
-        return db;
-    }
+                                                        const xvm::VersionDB& projectVersions);
 
     [[nodiscard]] static xvm::Workspace merged_workspace(const xvm::Workspace& globalWorkspace,
                                                          const xvm::Workspace& projectWorkspace,
                                                          const xvm::Workspace& projectSubosWorkspace,
-                                                         ProjectSubosMode mode) {
-        if (mode == ProjectSubosMode::Named) {
-            auto ws = projectWorkspace;
-            merge_workspace_into_(ws, projectSubosWorkspace);
-            return ws;
-        }
-
-        if (mode == ProjectSubosMode::Anonymous) {
-            auto ws = globalWorkspace;
-            merge_workspace_into_(ws, projectWorkspace);
-            merge_workspace_into_(ws, projectSubosWorkspace);
-            return ws;
-        }
-
-        return globalWorkspace;
-    }
+                                                         ProjectSubosMode mode);
 
     // Re-read versions/workspace/project state from disk. Call after taking
     // the state lock so a command operates on what is actually stored rather
     // than on the snapshot taken at process start.
-    static void reload_state() { instance_().reload_state_(); }
+    static void reload_state();
 
-    [[nodiscard]] static const PathInfo& paths() { return instance_().paths_; }
+    [[nodiscard]] static const PathInfo& paths();
 
     // Render a path for a human: anything under the xlings home shows as
     // `@xlings/...` instead of its absolute form.
@@ -992,44 +299,21 @@ public:
     // A path outside the home is returned unchanged: substituting a prefix
     // that does not apply would be a lie about where the file is.
     [[nodiscard]] static std::string display_path(
-            const std::filesystem::path& p) {
-        const auto& home = paths().homeDir;
-        if (home.empty()) return p.string();
-        // lexically_relative rather than a string prefix test: it compares
-        // whole components, so a sibling `.xlings-backup` cannot match, and
-        // it resolves `..` on the way. A prefix test needed both of those
-        // bolted on by hand, and the hand-rolled version also normalized the
-        // separators of paths it was supposed to return untouched -- on
-        // Windows `/usr/lib` came back as `\usr\lib`, breaking the one
-        // promise this function makes about paths outside the home.
-        const auto rel = p.lexically_normal()
-                          .lexically_relative(home.lexically_normal());
-        if (rel.empty() || *rel.begin() == "..") return p.string();
-        if (rel == std::filesystem::path(".")) return "@xlings";
-        return (std::filesystem::path("@xlings") / rel).string();
-    }
+            const std::filesystem::path& p);
 
-    [[nodiscard]] static std::string display_path(const std::string& p) {
-        return display_path(std::filesystem::path{p});
-    }
-    [[nodiscard]] static const std::string& mirror() { return instance_().mirror_; }
-    [[nodiscard]] static const std::string& lang() { return instance_().lang_; }
-    [[nodiscard]] static std::vector<std::string> resource_servers(std::string_view mirror = {}) {
-        return instance_().candidate_resource_servers_for_(mirror);
-    }
+    [[nodiscard]] static std::string display_path(const std::string& p);
+    [[nodiscard]] static const std::string& mirror();
+    [[nodiscard]] static const std::string& lang();
+    [[nodiscard]] static std::vector<std::string> resource_servers(std::string_view mirror = {});
     // Same list, extended with the other regions' servers as a last resort.
     // Use this for download fallbacks; `resource_servers()` remains the
     // "where should this region be pointed" answer used for selection.
     [[nodiscard]] static std::vector<std::string>
-    resource_servers_with_cross_region(std::string_view mirror = {}) {
-        return instance_().all_resource_servers_for_(mirror);
-    }
-    [[nodiscard]] static std::string resource_server(std::string_view mirror = {}) {
-        return instance_().selected_resource_server_for_(mirror);
-    }
+    resource_servers_with_cross_region(std::string_view mirror = {});
+    [[nodiscard]] static std::string resource_server(std::string_view mirror = {});
     // xim.index-base override (env XLINGS_INDEX_BASE_URL takes precedence in the
     // caller). Empty => default xlings-res raw-pointer + release-artifact path.
-    [[nodiscard]] static std::string index_base() { return instance_().indexBase_; }
+    [[nodiscard]] static std::string index_base();
 
     // Returns BY VALUE -- global and project state are merged into a fresh
     // map, so there is no long-lived object to hand out a reference to.
@@ -1041,131 +325,47 @@ public:
     // `xlings remove glibc` SIGSEGV'd on the musl-static release build and
     // threw bad_alloc on a glibc one, reported 2026-07-28 and present since
     // the fallback was written.
-    [[nodiscard]] static xvm::VersionDB versions() {
-        auto& self = instance_();
-        return merged_versions(self.globalVersions_, self.projectVersions_);
-    }
-    [[nodiscard]] static xvm::VersionDB& versions_mut() {
-        auto& self = instance_();
-        if (self.forceGlobalScope_ || !self.hasProjectConfig_) return self.globalVersions_;
-        return self.projectVersions_;
-    }
-    [[nodiscard]] static const xvm::VersionDB& global_versions() { return instance_().globalVersions_; }
-    [[nodiscard]] static const xvm::VersionDB& project_versions() { return instance_().projectVersions_; }
+    [[nodiscard]] static xvm::VersionDB versions();
+    [[nodiscard]] static xvm::VersionDB& versions_mut();
+    [[nodiscard]] static const xvm::VersionDB& global_versions();
+    [[nodiscard]] static const xvm::VersionDB& project_versions();
 
     // Effective data dir: project-local if project config exists, otherwise global
-    [[nodiscard]] static std::filesystem::path global_data_dir() {
-        return instance_().paths_.dataDir;
-    }
+    [[nodiscard]] static std::filesystem::path global_data_dir();
 
-    [[nodiscard]] static std::filesystem::path project_data_dir() {
-        return instance_().project_data_dir_();
-    }
+    [[nodiscard]] static std::filesystem::path project_data_dir();
 
-    [[nodiscard]] static std::filesystem::path project_home_dir() {
-        return instance_().project_home_dir_();
-    }
+    [[nodiscard]] static std::filesystem::path project_home_dir();
 
-    [[nodiscard]] static std::filesystem::path project_state_path() {
-        return instance_().project_state_path_();
-    }
+    [[nodiscard]] static std::filesystem::path project_state_path();
 
-    [[nodiscard]] static std::filesystem::path project_manifest_path() {
-        return instance_().project_manifest_path_();
-    }
+    [[nodiscard]] static std::filesystem::path project_manifest_path();
 
-    [[nodiscard]] static std::filesystem::path effective_data_dir() {
-        auto& self = instance_();
-        if (self.hasProjectConfig_ && !self.projectDir_.empty() && !self.projectIndexRepos_.empty()) {
-            return self.project_data_dir_();
-        }
-        return self.paths_.dataDir;
-    }
+    [[nodiscard]] static std::filesystem::path effective_data_dir();
 
-    [[nodiscard]] static const std::vector<IndexRepo>& global_index_repos() {
-        return instance_().globalIndexRepos_;
-    }
+    [[nodiscard]] static const std::vector<IndexRepo>& global_index_repos();
 
-    [[nodiscard]] static const std::vector<IndexRepo>& project_index_repos() {
-        return instance_().projectIndexRepos_;
-    }
+    [[nodiscard]] static const std::vector<IndexRepo>& project_index_repos();
 
-    [[nodiscard]] static const std::vector<IndexRepo>& index_repos() {
-        auto& self = instance_();
-        if (self.hasProjectConfig_ && !self.projectIndexRepos_.empty()) {
-            return self.projectIndexRepos_;
-        }
-        return self.globalIndexRepos_;
-    }
+    [[nodiscard]] static const std::vector<IndexRepo>& index_repos();
 
     [[nodiscard]] static std::filesystem::path repo_dir_for(const IndexRepo& repo,
-                                                            bool projectScope) {
-        auto root = projectScope ? project_data_dir() : global_data_dir();
-        auto dirName = repo.name == DEFAULT_INDEX_REPO_NAME ? DEFAULT_INDEX_REPO_DIR : repo.name;
-        return root / dirName;
-    }
+                                                            bool projectScope);
 
     [[nodiscard]] static std::filesystem::path resolve_repo_source(const IndexRepo& repo,
-                                                                   bool projectScope) {
-        namespace fs = std::filesystem;
-        auto value = repo.url;
-        if (value.rfind("file://", 0) == 0) {
-            value.erase(0, 7);
-#ifdef _WIN32
-            // file:///C:/path → /C:/path after erase; strip leading '/' before drive letter
-            if (value.size() >= 3 && value[0] == '/' && std::isalpha(static_cast<unsigned char>(value[1])) && value[2] == ':') {
-                value.erase(0, 1);
-            }
-#endif
-            return fs::path(value).lexically_normal();
-        }
-        if (value.find("://") != std::string::npos) {
-            return {};
-        }
-
-        fs::path source(value);
-        if (source.is_absolute()) return source.lexically_normal();
-
-        auto base = projectScope ? project_dir() : paths().homeDir;
-        if (base.empty()) return source.lexically_normal();
-        return (base / source).lexically_normal();
-    }
+                                                                   bool projectScope);
 
     [[nodiscard]] static bool is_local_repo_source(const IndexRepo& repo,
-                                                   bool projectScope) {
-        return !resolve_repo_source(repo, projectScope).empty();
-    }
+                                                   bool projectScope);
 
-    [[nodiscard]] static const std::filesystem::path& project_dir() {
-        return instance_().projectDir_;
-    }
+    [[nodiscard]] static const std::filesystem::path& project_dir();
 
-    [[nodiscard]] static ProjectSubosMode project_subos_mode() {
-        return instance_().projectSubosMode_;
-    }
+    [[nodiscard]] static ProjectSubosMode project_subos_mode();
 
-    [[nodiscard]] static const std::string& project_subos_name() {
-        return instance_().projectSubosName_;
-    }
+    [[nodiscard]] static const std::string& project_subos_name();
 
     // Get effective workspace: project overrides subos
-    [[nodiscard]] static xvm::Workspace effective_workspace() {
-        auto& self = instance_();
-        // `-g` means "act on the home, not on this project" -- and that has to
-        // include which workspace is authoritative, not only which directory
-        // the artifacts land in. Honoring it for paths alone is how
-        // `install -g` wrote a shim into the home's subos while `remove -g`
-        // asked the project's workspace whether the package was there, got
-        // "no", and stopped: the same package, present and absent at once,
-        // depending on which half of the scope you read.
-        if (!self.hasProjectConfig_ || self.forceGlobalScope_) {
-            return self.globalWorkspace_;
-        }
-        return merged_workspace(self.globalWorkspace_,
-                                self.projectWorkspace_,
-                                self.projectSubosWorkspace_,
-                                self.projectSubosMode_);
-    }
+    [[nodiscard]] static xvm::Workspace effective_workspace();
 
     // INVARIANT: a reader and its writer must resolve to the SAME map.
     //
@@ -1178,140 +378,52 @@ public:
     //
     // The two bodies are therefore identical on purpose. If one grows a
     // condition, the other has to grow it too.
-    [[nodiscard]] static const xvm::Workspace& workspace() {
-        auto& self = instance_();
-        if (self.forceGlobalScope_ || !self.hasProjectConfig_) return self.globalWorkspace_;
-        if (self.projectSubosMode_ == ProjectSubosMode::Named ||
-            self.projectSubosMode_ == ProjectSubosMode::Anonymous) return self.projectSubosWorkspace_;
-        return self.projectWorkspace_;
-    }
-    [[nodiscard]] static xvm::Workspace& workspace_mut() {
-        auto& self = instance_();
-        if (self.forceGlobalScope_ || !self.hasProjectConfig_) return self.globalWorkspace_;
-        if (self.projectSubosMode_ == ProjectSubosMode::Named ||
-            self.projectSubosMode_ == ProjectSubosMode::Anonymous) return self.projectSubosWorkspace_;
-        return self.projectWorkspace_;
-    }
+    [[nodiscard]] static const xvm::Workspace& workspace();
+    [[nodiscard]] static xvm::Workspace& workspace_mut();
 
     // Read access to per-subos installed[] sets, paired with the
     // workspace returned by workspace()/workspace_mut(). Only meaningful
     // for subos-side writes (project manifest path returns an empty
     // installed map since the project file format has no installed).
     // Same invariant as workspace()/workspace_mut() above, same reason.
-    [[nodiscard]] static const xvm::WorkspaceInstalled& workspace_installed() {
-        auto& self = instance_();
-        if (self.forceGlobalScope_ || !self.hasProjectConfig_) return self.globalInstalled_;
-        if (self.projectSubosMode_ == ProjectSubosMode::Named ||
-            self.projectSubosMode_ == ProjectSubosMode::Anonymous) return self.projectSubosInstalled_;
-        return self.globalInstalled_;
-    }
-    [[nodiscard]] static xvm::WorkspaceInstalled& workspace_installed_mut() {
-        auto& self = instance_();
-        if (self.forceGlobalScope_ || !self.hasProjectConfig_) return self.globalInstalled_;
-        if (self.projectSubosMode_ == ProjectSubosMode::Named ||
-            self.projectSubosMode_ == ProjectSubosMode::Anonymous) return self.projectSubosInstalled_;
-        return self.globalInstalled_;
-    }
-    [[nodiscard]] static bool has_project_config() { return instance_().hasProjectConfig_; }
+    [[nodiscard]] static const xvm::WorkspaceInstalled& workspace_installed();
+    [[nodiscard]] static xvm::WorkspaceInstalled& workspace_installed_mut();
+    [[nodiscard]] static bool has_project_config();
 
     // Force all version/workspace writes to go to global scope.
     // Used by `install -g` to ensure tools are available outside project context.
     // Recomputes the cached paths: `-g` changes which subos this process acts
     // on, and paths_ is derived from that. Without the recompute the flag was
     // honored by one reader and ignored by another for the rest of the run.
-    static void set_force_global_scope(bool force) {
-        auto& self = instance_();
-        if (self.forceGlobalScope_ == force) return;
-        self.forceGlobalScope_ = force;
-        self.update_effective_paths_();
-    }
+    static void set_force_global_scope(bool force);
 
     // Act on a named subos for the rest of this call, then hand back the
     // previous override so the caller can restore it. Same recompute as the
     // scope flag above and for the same reason: paths_ is derived state, and
     // a setter that does not refresh it is honored by one reader and ignored
     // by the next.
-    static std::string set_active_subos_override(std::string name) {
-        auto& self = instance_();
-        auto previous = self.activeSubosOverride_;
-        if (previous == name) return previous;
-        self.activeSubosOverride_ = std::move(name);
-        // reload_state_, not just update_effective_paths_: the paths are
-        // derived state but so is the WORKSPACE, and that one is read by the
-        // activation path. Recomputing only the paths put a package in the
-        // right subos and then reported it absent, because the two readers
-        // were looking at different subos.
-        self.reload_state_();
-        return previous;
-    }
+    static std::string set_active_subos_override(std::string name);
 
-    static std::filesystem::path subos_dir(const std::string& name) {
-        return instance_().paths_.homeDir / "subos" / name;
-    }
+    static std::filesystem::path subos_dir(const std::string& name);
 
-    [[nodiscard]] static std::filesystem::path global_subos_dir() {
-        return instance_().global_subos_dir_();
-    }
+    [[nodiscard]] static std::filesystem::path global_subos_dir();
 
-    [[nodiscard]] static std::filesystem::path global_subos_bin_dir() {
-        return global_subos_dir() / "bin";
-    }
+    [[nodiscard]] static std::filesystem::path global_subos_bin_dir();
 
     // Kept as a name because ~40 call sites read it, but it is no longer a
     // second implementation -- it is the single resolver, live. See
     // resolve_subos_scope_ for why there is exactly one.
     [[nodiscard]] static std::filesystem::path
-    xvm_artifact_subos_dir() {
-        return instance_().resolve_subos_scope_().root;
-    }
+    xvm_artifact_subos_dir();
 
     // The same answer as a value: name and root together, so a caller that
     // needs both cannot pick them from two different resolutions.
-    [[nodiscard]] static SubosScope subos_scope() {
-        return instance_().resolve_subos_scope_();
-    }
+    [[nodiscard]] static SubosScope subos_scope();
 
-    static std::vector<std::string> list_subos_names() {
-        std::vector<std::string> names;
-        auto dir = instance_().paths_.homeDir / "subos";
-        if (!std::filesystem::exists(dir)) return names;
-        for (auto& entry : platform::dir_entries(dir)) {
-            if (entry.is_directory()) {
-                auto name = entry.path().filename().string();
-                if (name != "current") names.push_back(name);
-            }
-        }
-        std::ranges::sort(names);
-        return names;
-    }
+    static std::vector<std::string> list_subos_names();
 
     // Save .xlings.json versions section (project-local if project config exists)
-    static void save_versions() {
-        namespace fs = std::filesystem;
-        auto& self = instance_();
-        bool useGlobal = self.forceGlobalScope_ || !self.hasProjectConfig_ || self.projectDir_.empty();
-        auto configPath = useGlobal
-            ? self.paths_.homeDir / ".xlings.json"
-            : self.project_state_path_();
-
-        if (!useGlobal) {
-            auto projectHomeDir = self.project_home_dir_();
-            if (!projectHomeDir.empty()) fs::create_directories(projectHomeDir);
-        }
-
-        nlohmann::json json;
-        if (fs::exists(configPath)) {
-            try {
-                auto content = platform::read_file_to_string(configPath.string());
-                json = nlohmann::json::parse(content, nullptr, false);
-                if (json.is_discarded()) json = nlohmann::json::object();
-            } catch (...) { json = nlohmann::json::object(); }
-        }
-
-        auto& versions = useGlobal ? self.globalVersions_ : self.projectVersions_;
-        json["versions"] = xvm::versions_to_json(versions);
-        platform::write_string_to_file(configPath.string(), json.dump(2));
-    }
+    static void save_versions();
 
     // Which xlings set this home up.
     //
@@ -1321,152 +433,17 @@ public:
     // xlings@latest as an ordinary package -- left it reading the previous
     // version forever. The field is what tells a user their packages predate
     // their client, so a stale one is worse than none.
-    [[nodiscard]] static std::string recorded_client_version() {
-        namespace fs = std::filesystem;
-        auto configPath = instance_().paths_.homeDir / ".xlings.json";
-        if (!fs::exists(configPath)) return {};
-        try {
-            auto content = platform::read_file_to_string(configPath.string());
-            auto json = nlohmann::json::parse(content, nullptr, false);
-            if (json.is_discarded() || !json.is_object()) return {};
-            auto it = json.find("version");
-            if (it == json.end() || !it->is_string()) return {};
-            return it->get<std::string>();
-        } catch (...) { return {}; }
-    }
+    [[nodiscard]] static std::string recorded_client_version();
 
     // Read-modify-write of the single field, deliberately: the file also
     // holds the xvm versions DB and the user's config, and this is called
     // from a command that has not necessarily loaded either.
-    static void record_client_version(const std::string& version) {
-        namespace fs = std::filesystem;
-        auto configPath = instance_().paths_.homeDir / ".xlings.json";
-        nlohmann::json json = nlohmann::json::object();
-        if (fs::exists(configPath)) {
-            try {
-                auto content = platform::read_file_to_string(configPath.string());
-                json = nlohmann::json::parse(content, nullptr, false);
-                if (json.is_discarded() || !json.is_object()) {
-                    // Refuse to replace a file we could not parse. Overwriting
-                    // it here would trade a stale version field for a lost
-                    // versions DB.
-                    return;
-                }
-            } catch (...) { return; }
-        }
-        json["version"] = version;
-        platform::write_string_to_file(configPath.string(), json.dump(2));
-    }
+    static void record_client_version(const std::string& version);
 
     // Save current subos workspace (project-local if project config exists)
-    static void save_workspace() {
-        namespace fs = std::filesystem;
-        auto& self = instance_();
-        bool useProject = self.hasProjectConfig_ && !self.forceGlobalScope_;
-        fs::path subosConfigPath;
-        if (useProject &&
-            self.projectSubosMode_ == ProjectSubosMode::Named) {
-            auto projSubosDir = self.project_subos_dir_();
-            fs::create_directories(projSubosDir);
-            fs::create_directories(projSubosDir / "bin");
-            fs::create_directories(projSubosDir / "lib");
-            fs::create_directories(projSubosDir / "usr");
-            fs::create_directories(projSubosDir / "generations");
-            subosConfigPath = projSubosDir / ".xlings.json";
-        } else if (useProject &&
-                   self.projectSubosMode_ == ProjectSubosMode::Anonymous) {
-            auto projSubosDir = self.project_subos_dir_();
-            auto projectHomeDir = self.project_home_dir_();
-            if (!projectHomeDir.empty()) fs::create_directories(projectHomeDir);
-            fs::create_directories(projSubosDir);
-            fs::create_directories(projSubosDir / "bin");
-            fs::create_directories(projSubosDir / "lib");
-            fs::create_directories(projSubosDir / "usr");
-            fs::create_directories(projSubosDir / "generations");
-            subosConfigPath = self.project_state_path_();
-        } else if (useProject && !self.projectDir_.empty()) {
-            auto projectHomeDir = self.project_home_dir_();
-            if (!projectHomeDir.empty()) fs::create_directories(projectHomeDir);
-            subosConfigPath = self.project_state_path_();
-        } else {
-            // useProject=false here — either no project config, or
-            // forceGlobalScope_ override is on (e.g. `xlings install -g`).
-            // Both paths mean "act on global scope, ignore project mode".
-            //
-            // We must NOT use paths_.activeSubos directly: when the user
-            // is inside an anonymous-project directory, paths_.activeSubos
-            // was set to "_" by update_effective_paths_ (the anonymous
-            // marker) and stays "_" even after forceGlobalScope_ flips
-            // useProject to false. Writing to `~/.xlings/subos/_/.xlings.json`
-            // (a directory that doesn't exist) then fails the workspace
-            // save — surfaced as `Failed to write file` during
-            // `xlings self install`'s patchelf-runtime-dep step (which
-            // spawns `xlings install -g`) when the user happens to run
-            // self install from inside an xlings repo / project tree.
-            //
-            // Resolve the same global-scope subos root used by XVM
-            // filesystem effects.
-            subosConfigPath =
-                self.global_subos_dir_() / ".xlings.json";
-        }
-
-        // XLINGS_HOME is a supported explicit scope, not proof that `self
-        // init` has already run. A first package install into a cold home
-        // reaches this writer after the payload is complete; create the state
-        // directory before persisting installed/active ownership so success
-        // is never followed by a spurious write failure (issue #471).
-        fs::create_directories(subosConfigPath.parent_path());
-
-        nlohmann::json json;
-        if (fs::exists(subosConfigPath)) {
-            try {
-                auto content = platform::read_file_to_string(subosConfigPath.string());
-                json = nlohmann::json::parse(content, nullptr, false);
-                if (json.is_discarded()) json = nlohmann::json::object();
-            } catch (...) { json = nlohmann::json::object(); }
-        }
-
-        // All four destination paths above target subos-side files
-        // (named project subos, anonymous project subos / state file, or
-        // global subos directory). The user-authored project manifest
-        // (`<proj>/.xlings.json`) is read-only from save_workspace's
-        // perspective and never reached here. So we always emit the
-        // 0.4.19+ C2 form via subos_workspace_to_json — backward-compat
-        // for legacy string-form values is in the *read* path
-        // (subos_workspace_from_json).
-        xvm::SubosWorkspace sws;
-        if (useProject &&
-            (self.projectSubosMode_ == ProjectSubosMode::Named ||
-             self.projectSubosMode_ == ProjectSubosMode::Anonymous)) {
-            sws.active = self.projectSubosWorkspace_;
-            sws.installed = self.projectSubosInstalled_;
-        } else if (useProject) {
-            // Reachable only via the third save-path branch above (project
-            // mode without a subos mode, currently unreachable in practice
-            // because load_project_config_from_dir_ always forces
-            // Anonymous when subos is unset). Write the project manifest
-            // workspace through with no installed[] info.
-            sws.active = self.projectWorkspace_;
-        } else {
-            sws.active = self.globalWorkspace_;
-            sws.installed = self.globalInstalled_;
-        }
-        json["workspace"] = xvm::subos_workspace_to_json(sws);
-        platform::write_string_to_file(subosConfigPath.string(), json.dump(2));
-    }
+    static void save_workspace();
 
-    static void print_paths() {
-        auto& p = paths();
-        std::println("XLINGS_HOME:     {}", p.homeDir.string());
-        std::println("XLINGS_DATA:     {}", display_path(p.dataDir));
-        if (has_project_config() && !project_index_repos().empty()) {
-            std::println("XLINGS_DATA_PROJECT: {}", display_path(project_data_dir()));
-        }
-        std::println("XLINGS_SUBOS:    {}", display_path(p.subosDir));
-        std::println("  activeSubos:   {}", p.activeSubos);
-        std::println("  selfContained: {}", p.selfContained);
-        std::println("  bin:           {}", display_path(p.binDir));
-    }
+    static void print_paths();
 };
 
 } // namespace xlings
diff --git a/src/core/entry_binary.cpp b/src/core/entry_binary.cpp
new file mode 100644
index 00000000..50ac3bc9
--- /dev/null
+++ b/src/core/entry_binary.cpp
@@ -0,0 +1,103 @@
+// What `$XLINGS_HOME/bin/xlings` actually is -- one reader.
+//
+// WHY THIS FILE EXISTS
+//
+// The entry binary is not a copy that drifts by accident. It is written on
+// purpose, by `xlings use xlings <v>` and by the install-time equivalent
+// (xvm/commands.cppm's self-replace, installer.cppm's twin): switching the
+// `xlings` package physically replaces the bootstrap file, because main.cpp
+// short-circuits the multicall names and would otherwise keep running the old
+// code while the workspace claimed otherwise.
+//
+// Every shim in the home reaches that one file -- `subos/<s>/bin/<tool>` is a
+// link to it -- so its version decides how EVERY tool in the home is
+// dispatched. Measured on a real home: the entry was replaced with a June
+// build, which predated `${XLINGS_DYNAMIC_SUBOS_DIR}`, so gcc's alias reached
+// a shell as `--sysroot=` and the whole toolchain quietly stopped being
+// self-contained. The first visible symptom was `cannot find crt1.o`, three
+// layers away from anything mentioning xlings.
+//
+// What was missing was not the writer. It was that nobody ever compared the
+// entry against what the home believed was active -- so a divergence created
+// in one command could persist indefinitely with every channel reporting
+// health.
+//
+// WHY IT RUNS THE BINARY INSTEAD OF READING A RECORD
+//
+// The home records a version in `.xlings.json` and the versions database
+// records an active binding. Both are records, and this check exists precisely
+// because a record and the file it describes can disagree. Checking a record
+// against another record cannot see that. Asking the file costs one process
+// (~60ms, measured) and is the only answer that cannot be stale.
+module xlings.core.entry_binary;
+
+import std;
+import xlings.core.log;
+import xlings.core.version_order;
+import xlings.platform;
+
+namespace xlings::entry_binary {
+
+fs::path path_of(const fs::path& homeDir) {
+#ifdef _WIN32
+    auto p = homeDir / "bin" / "xlings.exe";
+    if (!fs::exists(p)) p = homeDir / "xlings.exe";
+#else
+    auto p = homeDir / "bin" / "xlings";
+    if (!fs::exists(p)) p = homeDir / "xlings";
+#endif
+    return p;
+}
+
+std::string version_of(const fs::path& entry) {
+    std::error_code ec;
+    if (!fs::exists(entry, ec) || ec) return {};
+    auto [rc, out] = platform::run_command_capture(
+        platform::shell_quote(entry.string()) + " --version 2>&1");
+    if (rc != 0) return {};
+    // `xlings <version>` -- take the last whitespace-delimited token of the
+    // first non-empty line. Tolerant on purpose: a future banner change must
+    // degrade to "no observation", not to a wrong observation.
+    std::string_view text { out };
+    auto nl = text.find('\n');
+    auto line = text.substr(0, nl == std::string_view::npos ? text.size() : nl);
+    while (!line.empty() && (line.back() == '\r' || line.back() == ' ')) {
+        line.remove_suffix(1);
+    }
+    auto sp = line.rfind(' ');
+    if (sp == std::string_view::npos) return {};
+    auto token = std::string(line.substr(sp + 1));
+    // A version starts with a digit. Anything else -- an error message, a
+    // usage line -- is not an observation of a version.
+    if (token.empty() || !std::isdigit(static_cast<unsigned char>(token[0])))
+        return {};
+    return token;
+}
+
+bool replace_with(const fs::path& payloadBinary, const fs::path& entry,
+                  std::string_view coordinate, std::string_view toVersion) {
+    // Read BEFORE the swap: afterwards the old version is unrecoverable, and
+    // "we changed something, we cannot say from what" is not a report.
+    const auto before = version_of(entry);
+    if (!platform::atomic_replace_executable(payloadBinary, entry)) {
+        log::warn("[xlings] could not replace the entry binary {} <- {}",
+                  entry.string(), payloadBinary.string());
+        return false;
+    }
+    if (before.empty() || before == toVersion) {
+        log::debug("[xlings] entry binary -> {} ({})", toVersion, coordinate);
+        return true;
+    }
+    if (version_order::compare(toVersion, before) < 0) {
+        log::warn("[xlings] entry binary DOWNGRADED {} -> {} ({})",
+                  before, toVersion, coordinate);
+        log::warn("  every shim in this home dispatches through it; an older "
+                  "client may not understand records a newer index wrote");
+        return true;
+    }
+    log::info("[xlings] entry binary {} -> {} ({})", before, toVersion,
+              coordinate);
+    return true;
+}
+
+}
diff --git a/src/core/entry_binary.cppm b/src/core/entry_binary.cppm
index 07dd56cc..1981ebfc 100644
--- a/src/core/entry_binary.cppm
+++ b/src/core/entry_binary.cppm
@@ -33,9 +33,6 @@ export module xlings.core.entry_binary;
 
 import std;
 
-import xlings.core.log;
-import xlings.core.version_order;
-import xlings.platform;
 
 export namespace xlings::entry_binary {
 
@@ -44,45 +41,13 @@ namespace fs = std::filesystem;
 // The bootstrap file of a home. Mirrors the resolution in xvm/commands.cppm's
 // self-replace, including its fallback, so the reader and the writer cannot
 // disagree about which file is the entry.
-fs::path path_of(const fs::path& homeDir) {
-#ifdef _WIN32
-    auto p = homeDir / "bin" / "xlings.exe";
-    if (!fs::exists(p)) p = homeDir / "xlings.exe";
-#else
-    auto p = homeDir / "bin" / "xlings";
-    if (!fs::exists(p)) p = homeDir / "xlings";
-#endif
-    return p;
-}
+fs::path path_of(const fs::path& homeDir);
 
 // The version that file reports when asked. Empty when it is absent, cannot
 // run, or answers in a shape we do not recognise -- all three are "no
 // observation", never "version 0". A caller must not turn an empty string into
 // a verdict; see the doctor finding that consumes this.
-std::string version_of(const fs::path& entry) {
-    std::error_code ec;
-    if (!fs::exists(entry, ec) || ec) return {};
-    auto [rc, out] = platform::run_command_capture(
-        platform::shell_quote(entry.string()) + " --version 2>&1");
-    if (rc != 0) return {};
-    // `xlings <version>` -- take the last whitespace-delimited token of the
-    // first non-empty line. Tolerant on purpose: a future banner change must
-    // degrade to "no observation", not to a wrong observation.
-    std::string_view text { out };
-    auto nl = text.find('\n');
-    auto line = text.substr(0, nl == std::string_view::npos ? text.size() : nl);
-    while (!line.empty() && (line.back() == '\r' || line.back() == ' ')) {
-        line.remove_suffix(1);
-    }
-    auto sp = line.rfind(' ');
-    if (sp == std::string_view::npos) return {};
-    auto token = std::string(line.substr(sp + 1));
-    // A version starts with a digit. Anything else -- an error message, a
-    // usage line -- is not an observation of a version.
-    if (token.empty() || !std::isdigit(static_cast<unsigned char>(token[0])))
-        return {};
-    return token;
-}
+std::string version_of(const fs::path& entry);
 
 // Replace the entry binary, and say what changed.
 //
@@ -99,29 +64,6 @@ std::string version_of(const fs::path& entry) {
 // happen. The standing divergence is doctor's job; this is the moment it is
 // created.
 bool replace_with(const fs::path& payloadBinary, const fs::path& entry,
-                  std::string_view coordinate, std::string_view toVersion) {
-    // Read BEFORE the swap: afterwards the old version is unrecoverable, and
-    // "we changed something, we cannot say from what" is not a report.
-    const auto before = version_of(entry);
-    if (!platform::atomic_replace_executable(payloadBinary, entry)) {
-        log::warn("[xlings] could not replace the entry binary {} <- {}",
-                  entry.string(), payloadBinary.string());
-        return false;
-    }
-    if (before.empty() || before == toVersion) {
-        log::debug("[xlings] entry binary -> {} ({})", toVersion, coordinate);
-        return true;
-    }
-    if (version_order::compare(toVersion, before) < 0) {
-        log::warn("[xlings] entry binary DOWNGRADED {} -> {} ({})",
-                  before, toVersion, coordinate);
-        log::warn("  every shim in this home dispatches through it; an older "
-                  "client may not understand records a newer index wrote");
-        return true;
-    }
-    log::info("[xlings] entry binary {} -> {} ({})", before, toVersion,
-              coordinate);
-    return true;
-}
+                  std::string_view coordinate, std::string_view toVersion);
 
 }  // namespace xlings::entry_binary
diff --git a/src/core/home_config.cpp b/src/core/home_config.cpp
new file mode 100644
index 00000000..db79a117
--- /dev/null
+++ b/src/core/home_config.cpp
@@ -0,0 +1,48 @@
+module xlings.core.home_config;
+
+import std;
+import xlings.libs.json;
+import xlings.platform;
+import xlings.core.xvm.lock;
+
+namespace xlings {
+
+std::filesystem::path home_config_path(const std::filesystem::path& home) {
+    return home / ".xlings.json";
+}
+
+nlohmann::json read_home_config(const std::filesystem::path& home) {
+    const auto path = home_config_path(home);
+    std::error_code ec;
+    if (!std::filesystem::exists(path, ec) || ec) return nlohmann::json::object();
+    try {
+        auto content = platform::read_file_to_string(path.string());
+        auto parsed = nlohmann::json::parse(content, nullptr, false);
+        if (parsed.is_discarded() || !parsed.is_object()) {
+            return nlohmann::json::object();
+        }
+        return parsed;
+    } catch (...) {
+        return nlohmann::json::object();
+    }
+}
+
+std::expected<bool, std::string> update_home_config(const std::filesystem::path& home, const std::function<bool(nlohmann::json&)>& mutate, std::chrono::milliseconds timeout) {
+    auto lock = xvm::acquire_state_lock(home, timeout);
+    if (!lock) return std::unexpected(lock.error());
+
+    auto json = read_home_config(home);
+    if (!mutate(json)) return false;
+
+    try {
+        platform::write_string_to_file(
+            home_config_path(home).string(), json.dump(2));
+    } catch (const std::exception& e) {
+        return std::unexpected(std::format(
+            "failed to write {}: {}",
+            home_config_path(home).string(), e.what()));
+    }
+    return true;
+}
+
+}
diff --git a/src/core/home_config.cppm b/src/core/home_config.cppm
index d6c3613d..6d40e87b 100644
--- a/src/core/home_config.cppm
+++ b/src/core/home_config.cppm
@@ -3,7 +3,6 @@ export module xlings.core.home_config;
 import std;
 
 import xlings.libs.json;
-import xlings.platform;
 import xlings.core.xvm.lock;
 
 // Serialized read-modify-write of `<home>/.xlings.json`.
@@ -52,29 +51,13 @@ import xlings.core.xvm.lock;
 // last-writer-wins behavior.
 export namespace xlings {
 
-std::filesystem::path home_config_path(const std::filesystem::path& home) {
-    return home / ".xlings.json";
-}
+std::filesystem::path home_config_path(const std::filesystem::path& home);
 
 // Parse `<home>/.xlings.json`, or an empty object if it is absent, empty,
 // unreadable or malformed. Matches what every hand-rolled reader in the tree
 // did before this module existed: a corrupt config is treated as no config
 // rather than failing the command.
-nlohmann::json read_home_config(const std::filesystem::path& home) {
-    const auto path = home_config_path(home);
-    std::error_code ec;
-    if (!std::filesystem::exists(path, ec) || ec) return nlohmann::json::object();
-    try {
-        auto content = platform::read_file_to_string(path.string());
-        auto parsed = nlohmann::json::parse(content, nullptr, false);
-        if (parsed.is_discarded() || !parsed.is_object()) {
-            return nlohmann::json::object();
-        }
-        return parsed;
-    } catch (...) {
-        return nlohmann::json::object();
-    }
-}
+nlohmann::json read_home_config(const std::filesystem::path& home);
 
 // Apply `mutate` to a freshly-read `<home>/.xlings.json` while holding the
 // home-wide state lock, then write it back.
@@ -91,22 +74,6 @@ nlohmann::json read_home_config(const std::filesystem::path& home) {
 std::expected<bool, std::string> update_home_config(
         const std::filesystem::path& home,
         const std::function<bool(nlohmann::json&)>& mutate,
-        std::chrono::milliseconds timeout = xvm::default_lock_timeout()) {
-    auto lock = xvm::acquire_state_lock(home, timeout);
-    if (!lock) return std::unexpected(lock.error());
-
-    auto json = read_home_config(home);
-    if (!mutate(json)) return false;
-
-    try {
-        platform::write_string_to_file(
-            home_config_path(home).string(), json.dump(2));
-    } catch (const std::exception& e) {
-        return std::unexpected(std::format(
-            "failed to write {}: {}",
-            home_config_path(home).string(), e.what()));
-    }
-    return true;
-}
+        std::chrono::milliseconds timeout = xvm::default_lock_timeout());
 
 }  // namespace xlings
diff --git a/src/core/i18n.cpp b/src/core/i18n.cpp
new file mode 100644
index 00000000..eae1aaaf
--- /dev/null
+++ b/src/core/i18n.cpp
@@ -0,0 +1,34 @@
+module xlings.core.i18n;
+
+import std;
+import xlings.platform;
+
+namespace xlings::i18n {
+
+std::string gLang_;
+
+void set_language(const std::string& lang) {
+    gLang_ = lang;
+}
+
+[[nodiscard]] const std::string& language() {
+    if (gLang_.empty()) {
+        gLang_ = platform::get_system_language();
+        if (gLang_ != "zh") {
+            gLang_ = "en";
+        }
+    }
+    return gLang_;
+}
+
+[[nodiscard]] bool is_chinese() {
+    return language() == "zh";
+}
+
+[[nodiscard]] std::string_view tr(Msg id) {
+    int idx = static_cast<int>(id);
+    if (idx < 0 || idx >= MSG_COUNT) return "";
+    return is_chinese() ? gMessages_[idx].zh : gMessages_[idx].en;
+}
+
+}
diff --git a/src/core/i18n.cppm b/src/core/i18n.cppm
index 6ef36886..b09e0fe9 100644
--- a/src/core/i18n.cppm
+++ b/src/core/i18n.cppm
@@ -2,7 +2,6 @@ export module xlings.core.i18n;
 
 import std;
 
-import xlings.platform;
 
 namespace xlings::i18n {
 
@@ -165,31 +164,13 @@ constexpr MsgEntry gMessages_[] = {
 static_assert(sizeof(gMessages_) / sizeof(gMessages_[0]) == MSG_COUNT,
               "gMessages_ size must match Msg enum count");
 
-std::string gLang_;
+export void set_language(const std::string& lang);
 
-export void set_language(const std::string& lang) {
-    gLang_ = lang;
-}
+export [[nodiscard]] const std::string& language();
 
-export [[nodiscard]] const std::string& language() {
-    if (gLang_.empty()) {
-        gLang_ = platform::get_system_language();
-        if (gLang_ != "zh") {
-            gLang_ = "en";
-        }
-    }
-    return gLang_;
-}
+export [[nodiscard]] bool is_chinese();
 
-export [[nodiscard]] bool is_chinese() {
-    return language() == "zh";
-}
-
-export [[nodiscard]] std::string_view tr(Msg id) {
-    int idx = static_cast<int>(id);
-    if (idx < 0 || idx >= MSG_COUNT) return "";
-    return is_chinese() ? gMessages_[idx].zh : gMessages_[idx].en;
-}
+export [[nodiscard]] std::string_view tr(Msg id);
 
 export template<typename... Args>
 [[nodiscard]] std::string trf(Msg id, Args&&... args) {
diff --git a/src/core/log.cpp b/src/core/log.cpp
new file mode 100644
index 00000000..30f2ab1c
--- /dev/null
+++ b/src/core/log.cpp
@@ -0,0 +1,109 @@
+module;
+#include <ctime>
+#include <cstdio>
+
+module xlings.core.log;
+
+import std;
+import xlings.platform;
+import xlings.core.palette;
+
+namespace xlings::log {
+
+Level gLevel_{ Level::Info };
+
+std::string gContext_;
+
+std::ofstream gFile_;
+
+bool gColor_{ true };
+
+void set_level(Level level) {
+    gLevel_ = level;
+}
+
+void set_level(const std::string& level) {
+    if (level == "debug") gLevel_ = Level::Debug;
+    else if (level == "info") gLevel_ = Level::Info;
+    else if (level == "warn") gLevel_ = Level::Warn;
+    else if (level == "error") gLevel_ = Level::Error;
+}
+
+Level get_level() {
+    return gLevel_;
+}
+
+std::string_view level_string() {
+    switch (gLevel_) {
+        case Level::Debug: return "debug";
+        case Level::Info:  return "info";
+        case Level::Warn:  return "warn";
+        case Level::Error: return "error";
+    }
+    return "info";
+}
+
+void set_file(const std::filesystem::path& path) {
+    if (gFile_.is_open()) gFile_.close();
+    if (!path.empty()) gFile_.open(path, std::ios::app);
+}
+
+void set_context(std::string ctx) {
+    gContext_ = std::move(ctx);
+}
+
+void clear_context() {
+    gContext_.clear();
+}
+
+void enable_color(bool enabled) {
+    gColor_ = enabled;
+}
+
+// Colors come from xlings.core.palette, so these prefixes follow the
+// terminal background like the rendered panels do and go quiet under
+// NO_COLOR / TERM=dumb / a pipe. They used to be dark-palette SGR literals
+// spelled out here, which is why a light terminal kept getting the
+// low-contrast text the palette exists to avoid.
+bool color_on_()     { return gColor_ && palette::colors_enabled(); }
+
+bool color_on_err_() { return gColor_ && palette::colors_enabled_err(); }
+
+std::string colored_(palette::Rgb c, const char* text) {
+    if (!color_on_()) return text;
+    return palette::sgr_fg(c) + text + palette::reset;
+}
+
+std::string colored_err_(palette::Rgb c, const char* text) {
+    if (!color_on_err_()) return text;
+    return palette::sgr_fg(c) + text + palette::reset;
+}
+
+std::string timestamp_() {
+    auto now = std::chrono::system_clock::now();
+    auto tt = std::chrono::system_clock::to_time_t(now);
+    std::tm tm;
+#if defined(_WIN32)
+    ::localtime_s(&tm, &tt);
+#else
+    ::localtime_r(&tt, &tm);
+#endif
+    char buf[32];
+    std::snprintf(buf, sizeof(buf), "%04d-%02d-%02d %02d:%02d:%02d",
+                  tm.tm_year + 1900, tm.tm_mon + 1, tm.tm_mday,
+                  tm.tm_hour, tm.tm_min, tm.tm_sec);
+    return buf;
+}
+
+void write_to_file_(std::string_view prefix, std::string_view msg) {
+    if (gFile_.is_open()) {
+        gFile_ << timestamp_() << " " << prefix;
+        if (!gContext_.empty()) {
+            gFile_ << "[" << gContext_ << "] ";
+        }
+        gFile_ << msg << "\n";
+        gFile_.flush();
+    }
+}
+
+}
diff --git a/src/core/log.cppm b/src/core/log.cppm
index 806490cf..e6cecded 100644
--- a/src/core/log.cppm
+++ b/src/core/log.cppm
@@ -17,108 +17,42 @@ export enum class Level {
     Error
 };
 
-Level gLevel_ { Level::Info };
-std::string gContext_;
-std::ofstream gFile_;
-bool gColor_ { true };
+extern Level gLevel_;
+extern std::string gContext_;
 // Terminal output is suppressed when platform::is_tui_mode() is true
 
-export void set_level(Level level) {
-    gLevel_ = level;
-}
+export void set_level(Level level);
 
-export void set_level(const std::string& level) {
-    if (level == "debug") gLevel_ = Level::Debug;
-    else if (level == "info") gLevel_ = Level::Info;
-    else if (level == "warn") gLevel_ = Level::Warn;
-    else if (level == "error") gLevel_ = Level::Error;
-}
+export void set_level(const std::string& level);
 
-export Level get_level() {
-    return gLevel_;
-}
+export Level get_level();
 
-export std::string_view level_string() {
-    switch (gLevel_) {
-        case Level::Debug: return "debug";
-        case Level::Info:  return "info";
-        case Level::Warn:  return "warn";
-        case Level::Error: return "error";
-    }
-    return "info";
-}
+export std::string_view level_string();
 
-export void set_file(const std::filesystem::path& path) {
-    if (gFile_.is_open()) gFile_.close();
-    if (!path.empty()) gFile_.open(path, std::ios::app);
-}
+export void set_file(const std::filesystem::path& path);
 
-export void set_context(std::string ctx) {
-    gContext_ = std::move(ctx);
-}
+export void set_context(std::string ctx);
 
-export void clear_context() {
-    gContext_.clear();
-}
+export void clear_context();
 
-export void enable_color(bool enabled) {
-    gColor_ = enabled;
-}
+export void enable_color(bool enabled);
+bool color_on_err_();
 
-// Colors come from xlings.core.palette, so these prefixes follow the
-// terminal background like the rendered panels do and go quiet under
-// NO_COLOR / TERM=dumb / a pipe. They used to be dark-palette SGR literals
-// spelled out here, which is why a light terminal kept getting the
-// low-contrast text the palette exists to avoid.
-bool color_on_()     { return gColor_ && palette::colors_enabled(); }
-bool color_on_err_() { return gColor_ && palette::colors_enabled_err(); }
-
-std::string colored_(palette::Rgb c, const char* text) {
-    if (!color_on_()) return text;
-    return palette::sgr_fg(c) + text + palette::reset;
-}
+std::string colored_(palette::Rgb c, const char* text);
 
 // warn/error write to stderr, which can be a terminal when stdout is not.
-std::string colored_err_(palette::Rgb c, const char* text) {
-    if (!color_on_err_()) return text;
-    return palette::sgr_fg(c) + text + palette::reset;
-}
-
-std::string timestamp_() {
-    auto now = std::chrono::system_clock::now();
-    auto tt = std::chrono::system_clock::to_time_t(now);
-    std::tm tm;
-#if defined(_WIN32)
-    ::localtime_s(&tm, &tt);
-#else
-    ::localtime_r(&tt, &tm);
-#endif
-    char buf[32];
-    std::snprintf(buf, sizeof(buf), "%04d-%02d-%02d %02d:%02d:%02d",
-                  tm.tm_year + 1900, tm.tm_mon + 1, tm.tm_mday,
-                  tm.tm_hour, tm.tm_min, tm.tm_sec);
-    return buf;
-}
+std::string colored_err_(palette::Rgb c, const char* text);
 
-void write_to_file_(std::string_view prefix, std::string_view msg) {
-    if (gFile_.is_open()) {
-        gFile_ << timestamp_() << " " << prefix;
-        if (!gContext_.empty()) {
-            gFile_ << "[" << gContext_ << "] ";
-        }
-        gFile_ << msg << "\n";
-        gFile_.flush();
-    }
-}
+void write_to_file_(std::string_view prefix, std::string_view msg);
 
 export template<typename... Args>
 void debug(std::format_string<Args...> fmt, Args&&... args) {
     if (gLevel_ <= Level::Debug) {
         auto msg = std::format(fmt, std::forward<Args>(args)...);
         if (!platform::is_tui_mode()) {
-            std::print("{} ", colored_(palette::dim(), "[debug]"));
-            if (!gContext_.empty()) std::print("{} ", colored_(palette::dim(), std::format("[{}]", gContext_).c_str()));
-            std::println("{}", msg);
+            std::print(stdout, "{} ", colored_(palette::dim(), "[debug]"));
+            if (!gContext_.empty()) std::print(stdout, "{} ", colored_(palette::dim(), std::format("[{}]", gContext_).c_str()));
+            std::println(stdout, "{}", msg);
         }
         write_to_file_("[debug] ", msg);
     }
@@ -129,9 +63,9 @@ void info(std::format_string<Args...> fmt, Args&&... args) {
     if (gLevel_ <= Level::Info) {
         auto msg = std::format(fmt, std::forward<Args>(args)...);
         if (!platform::is_tui_mode()) {
-            std::print("{} ", colored_(palette::cyan(), "[xlings]"));
-            if (!gContext_.empty()) std::print("{} ", colored_(palette::cyan(), std::format("[{}]", gContext_).c_str()));
-            std::println("{}", msg);
+            std::print(stdout, "{} ", colored_(palette::cyan(), "[xlings]"));
+            if (!gContext_.empty()) std::print(stdout, "{} ", colored_(palette::cyan(), std::format("[{}]", gContext_).c_str()));
+            std::println(stdout, "{}", msg);
         }
         write_to_file_("[xlings] ", msg);
     }
@@ -170,7 +104,7 @@ export template<typename... Args>
 void println(std::format_string<Args...> fmt, Args&&... args) {
     if (gLevel_ <= Level::Info) {
         auto msg = std::format(fmt, std::forward<Args>(args)...);
-        if (!platform::is_tui_mode()) std::println("{}", msg);
+        if (!platform::is_tui_mode()) std::println(stdout, "{}", msg);
         write_to_file_("[status] ", msg);
     }
 }
@@ -179,7 +113,7 @@ export template<typename... Args>
 void print(std::format_string<Args...> fmt, Args&&... args) {
     if (gLevel_ <= Level::Info) {
         auto msg = std::format(fmt, std::forward<Args>(args)...);
-        std::print("{}", msg);
+        std::print(stdout, "{}", msg);
     }
 }
 
diff --git a/src/core/mirror/adaptive.cpp b/src/core/mirror/adaptive.cpp
new file mode 100644
index 00000000..90c5e986
--- /dev/null
+++ b/src/core/mirror/adaptive.cpp
@@ -0,0 +1,138 @@
+// xlings.core.mirror.adaptive — latency-ordered candidate selection for
+// multi-URL downloads (0.4.49).
+//
+// Design: .agents/docs/2026-06-04-github-asset-adaptive-mirror.md
+//
+// Problem: with no explicit mirror config, plain GitHub asset URLs are
+// always tried original-first; on a degraded network ("connects, then
+// trickles") the user waits out the full timeout budget before any mirror
+// is attempted. This partition probes each candidate host's TCP connect
+// latency once per process (memoized) and orders candidates accordingly,
+// gated by a sha256 integrity rule: third-party mirrors may only be tried
+// BEFORE the author-declared URL when the payload's bytes are pinned by a
+// declared sha256.
+//
+// The same cache doubles as the session network profile: a host whose
+// transfer stalled (watchdog abort in tinyhttps) is penalized to ∞ so the
+// next download in this process skips straight past it.
+
+module;
+
+#include <cstdlib>
+
+module xlings.core.mirror.adaptive;
+
+import std;
+import xlings.core.log;
+import xlings.libs.tinyhttps;
+
+namespace xlings::mirror::adaptive {
+
+namespace {
+
+constexpr int kProbeTimeoutMs = 1500;
+
+// "https://github.com/x/y/releases/..." → "https://github.com"
+std::string host_root_(std::string_view url) {
+    auto scheme_end = url.find("://");
+    if (scheme_end == std::string_view::npos) return {};
+    auto host_start = scheme_end + 3;
+    auto path_start = url.find('/', host_start);
+    return std::string(path_start == std::string_view::npos
+        ? url : url.substr(0, path_start));
+}
+
+struct Cache {
+    std::mutex mtx;
+    std::unordered_map<std::string, double> latency;  // host root → seconds (∞ = bad)
+};
+
+Cache& cache_() {
+    static Cache c;
+    return c;
+}
+
+bool adaptive_disabled_() {
+    const char* env = std::getenv("XLINGS_ADAPTIVE_MIRROR");
+    if (!env || !*env) return false;
+    std::string v = env;
+    return v == "off" || v == "0";
+}
+
+}
+
+double host_latency(const std::string& url, const ProbeFn& probe) {
+    auto host = host_root_(url);
+    if (host.empty()) return 0.0;
+
+    auto& c = cache_();
+    {
+        std::scoped_lock lock(c.mtx);
+        if (auto it = c.latency.find(host); it != c.latency.end())
+            return it->second;
+    }
+    double lat = probe
+        ? probe(host)
+        : tinyhttps::probe_latency(host, kProbeTimeoutMs);
+    {
+        std::scoped_lock lock(c.mtx);
+        c.latency.emplace(host, lat);
+    }
+    log::debug("[mirror:adaptive] {} latency {:.0f} ms", host,
+               std::isinf(lat) ? -1.0 : lat * 1000.0);
+    return lat;
+}
+
+void penalize_host(const std::string& url) {
+    auto host = host_root_(url);
+    if (host.empty()) return;
+    auto& c = cache_();
+    std::scoped_lock lock(c.mtx);
+    c.latency[host] = std::numeric_limits<double>::infinity();
+    log::debug("[mirror:adaptive] penalized {}", host);
+}
+
+void reset_for_tests() {
+    auto& c = cache_();
+    std::scoped_lock lock(c.mtx);
+    c.latency.clear();
+}
+
+std::vector<std::string> reorder(std::vector<std::string> urls, bool has_sha256, const ProbeFn& probe) {
+    if (urls.size() < 2 || adaptive_disabled_()) return urls;
+
+    struct Entry {
+        std::string url;
+        double      lat;
+        std::size_t idx;   // declared position, for stable ties
+    };
+    std::vector<Entry> entries;
+    entries.reserve(urls.size());
+    for (std::size_t i = 0; i < urls.size(); ++i) {
+        double lat = host_latency(urls[i], probe);
+        entries.push_back({std::move(urls[i]), lat, i});
+    }
+
+    auto by_latency = [](const Entry& a, const Entry& b) {
+        if (a.lat != b.lat) return a.lat < b.lat;
+        return a.idx < b.idx;   // stable: keep declared order on ties
+    };
+
+    bool primary_pinned = !has_sha256
+        && !std::isinf(entries.front().lat);
+
+    if (primary_pinned) {
+        // Unpinned content: the author-declared URL stays authoritative;
+        // only the fallbacks compete on latency.
+        std::sort(entries.begin() + 1, entries.end(), by_latency);
+    } else {
+        std::sort(entries.begin(), entries.end(), by_latency);
+    }
+
+    std::vector<std::string> out;
+    out.reserve(entries.size());
+    for (auto& e : entries) out.push_back(std::move(e.url));
+    return out;
+}
+
+}
diff --git a/src/core/mirror/adaptive.cppm b/src/core/mirror/adaptive.cppm
index eb951be8..9f3ba52e 100644
--- a/src/core/mirror/adaptive.cppm
+++ b/src/core/mirror/adaptive.cppm
@@ -24,43 +24,9 @@ export module xlings.core.mirror.adaptive;
 
 import std;
 
-import xlings.core.log;
 import xlings.libs.tinyhttps;
 
-namespace xlings::mirror::adaptive {
-
-namespace {
-
-constexpr int kProbeTimeoutMs = 1500;
-
-// "https://github.com/x/y/releases/..." → "https://github.com"
-std::string host_root_(std::string_view url) {
-    auto scheme_end = url.find("://");
-    if (scheme_end == std::string_view::npos) return {};
-    auto host_start = scheme_end + 3;
-    auto path_start = url.find('/', host_start);
-    return std::string(path_start == std::string_view::npos
-        ? url : url.substr(0, path_start));
-}
-
-struct Cache {
-    std::mutex mtx;
-    std::unordered_map<std::string, double> latency;  // host root → seconds (∞ = bad)
-};
-
-Cache& cache_() {
-    static Cache c;
-    return c;
-}
-
-bool adaptive_disabled_() {
-    const char* env = std::getenv("XLINGS_ADAPTIVE_MIRROR");
-    if (!env || !*env) return false;
-    std::string v = env;
-    return v == "off" || v == "0";
-}
-
-} // anonymous namespace
+namespace xlings::mirror::adaptive { // anonymous namespace
 
 // Injectable prober for tests. Empty = real TCP connect probe.
 export using ProbeFn = std::function<double(const std::string& hostRootUrl)>;
@@ -68,45 +34,14 @@ export using ProbeFn = std::function<double(const std::string& hostRootUrl)>;
 // Connect latency for the host of `url`, probed once per process and
 // memoized. Unknown/unparseable URLs return 0 (neutral — keeps declared
 // order under stable sort).
-export double host_latency(const std::string& url, const ProbeFn& probe = {}) {
-    auto host = host_root_(url);
-    if (host.empty()) return 0.0;
-
-    auto& c = cache_();
-    {
-        std::scoped_lock lock(c.mtx);
-        if (auto it = c.latency.find(host); it != c.latency.end())
-            return it->second;
-    }
-    double lat = probe
-        ? probe(host)
-        : tinyhttps::probe_latency(host, kProbeTimeoutMs);
-    {
-        std::scoped_lock lock(c.mtx);
-        c.latency.emplace(host, lat);
-    }
-    log::debug("[mirror:adaptive] {} latency {:.0f} ms", host,
-               std::isinf(lat) ? -1.0 : lat * 1000.0);
-    return lat;
-}
+export double host_latency(const std::string& url, const ProbeFn& probe = {});
 
 // Session-scoped demotion: a host whose transfer stalled is as bad as an
 // unreachable one for the rest of this process.
-export void penalize_host(const std::string& url) {
-    auto host = host_root_(url);
-    if (host.empty()) return;
-    auto& c = cache_();
-    std::scoped_lock lock(c.mtx);
-    c.latency[host] = std::numeric_limits<double>::infinity();
-    log::debug("[mirror:adaptive] penalized {}", host);
-}
+export void penalize_host(const std::string& url);
 
 // Test hook: drop all cached latencies.
-export void reset_for_tests() {
-    auto& c = cache_();
-    std::scoped_lock lock(c.mtx);
-    c.latency.clear();
-}
+export void reset_for_tests();
 
 // Order download candidates by measured host latency.
 //
@@ -120,41 +55,6 @@ export void reset_for_tests() {
 // Single-candidate lists and XLINGS_ADAPTIVE_MIRROR=off return unchanged.
 export std::vector<std::string> reorder(std::vector<std::string> urls,
                                         bool has_sha256,
-                                        const ProbeFn& probe = {}) {
-    if (urls.size() < 2 || adaptive_disabled_()) return urls;
-
-    struct Entry {
-        std::string url;
-        double      lat;
-        std::size_t idx;   // declared position, for stable ties
-    };
-    std::vector<Entry> entries;
-    entries.reserve(urls.size());
-    for (std::size_t i = 0; i < urls.size(); ++i) {
-        double lat = host_latency(urls[i], probe);
-        entries.push_back({std::move(urls[i]), lat, i});
-    }
-
-    auto by_latency = [](const Entry& a, const Entry& b) {
-        if (a.lat != b.lat) return a.lat < b.lat;
-        return a.idx < b.idx;   // stable: keep declared order on ties
-    };
-
-    bool primary_pinned = !has_sha256
-        && !std::isinf(entries.front().lat);
-
-    if (primary_pinned) {
-        // Unpinned content: the author-declared URL stays authoritative;
-        // only the fallbacks compete on latency.
-        std::sort(entries.begin() + 1, entries.end(), by_latency);
-    } else {
-        std::sort(entries.begin(), entries.end(), by_latency);
-    }
-
-    std::vector<std::string> out;
-    out.reserve(entries.size());
-    for (auto& e : entries) out.push_back(std::move(e.url));
-    return out;
-}
+                                        const ProbeFn& probe = {});
 
 } // namespace xlings::mirror::adaptive
diff --git a/src/core/mirror/expand.cpp b/src/core/mirror/expand.cpp
new file mode 100644
index 00000000..090895f0
--- /dev/null
+++ b/src/core/mirror/expand.cpp
@@ -0,0 +1,160 @@
+// xlings.core.mirror.expand — top-level URL expansion logic.
+//
+// `expand(url, opts)` is the single entry point used by HTTP / git / index
+// download paths. Given an input URL it returns an ordered list of URLs
+// to try in sequence — original first, then mirror variants — based on
+// the current Mode, the resource type, and the registered mirror list.
+
+module xlings.core.mirror.expand;
+
+import std;
+import xlings.core.config;
+import xlings.core.log;
+import xlings.libs.json;
+import xlings.platform;
+import xlings.core.mirror.types;
+import xlings.core.mirror.registry;
+import xlings.core.mirror.forms;
+
+namespace xlings::mirror {
+
+namespace {
+
+constexpr std::string_view kGithubHost      = "https://github.com/";
+constexpr std::string_view kRawHost         = "https://raw.githubusercontent.com/";
+constexpr std::string_view kCodeloadHost    = "https://codeload.github.com/";
+constexpr std::string_view kObjectsHost     = "https://objects.githubusercontent.com/";
+
+Mode parse_mode_(std::string_view s) {
+    if (s == "off")   return Mode::Off;
+    if (s == "force") return Mode::Force;
+    return Mode::Auto;  // default for unknown / "auto" / empty
+}
+
+// Resolve the process-wide mode once: env var > .xlings.json > Auto.
+Mode resolve_mode_() {
+    if (auto env = std::getenv("XLINGS_MIRROR_FALLBACK"); env && *env)
+        return parse_mode_(env);
+
+    // Read from ~/.xlings.json directly. Adding a typed field to Config
+    // is overkill for one optional setting most users never touch.
+    auto& paths = Config::paths();
+    auto path = paths.homeDir / ".xlings.json";
+    std::error_code ec;
+    if (std::filesystem::exists(path, ec)) {
+        try {
+            auto content = platform::read_file_to_string(path.string());
+            auto json = nlohmann::json::parse(content, nullptr, false);
+            if (!json.is_discarded() && json.is_object()) {
+                if (auto it = json.find("mirror_fallback");
+                    it != json.end() && it->is_string()) {
+                    return parse_mode_(it->get<std::string>());
+                }
+            }
+        } catch (...) {}
+    }
+    return Mode::Auto;
+}
+
+Mode& mode_storage_() {
+    static Mode mode = resolve_mode_();
+    return mode;
+}
+
+// Stable per-process shuffle seed: derive from start-of-process steady
+// clock so different xlings processes hit different mirrors first when
+// priorities tie. A single process keeps the same seed for the rest of
+// its lifetime so debug log reading is reproducible.
+std::uint32_t shuffle_seed_() {
+    static const std::uint32_t seed = static_cast<std::uint32_t>(
+        std::chrono::steady_clock::now().time_since_epoch().count());
+    return seed;
+}
+
+// Shuffle elements with the same priority in-place, deterministic per process.
+void shuffle_within_priority_(std::vector<Mirror>& mirrors) {
+    if (mirrors.size() < 2) return;
+    std::mt19937 rng(shuffle_seed_());
+    auto it = mirrors.begin();
+    while (it != mirrors.end()) {
+        auto end = std::find_if(it, mirrors.end(),
+            [p = it->priority](const Mirror& m) { return m.priority != p; });
+        if (std::distance(it, end) > 1) {
+            std::shuffle(it, end, rng);
+        }
+        it = end;
+    }
+}
+
+}
+
+Mode current_mode() {
+    return mode_storage_();
+}
+
+void set_mode(Mode mode) {
+    mode_storage_() = mode;
+}
+
+ResourceType classify(std::string_view url) {
+    if (url.starts_with(kRawHost))      return ResourceType::Raw;
+    if (url.starts_with(kCodeloadHost)) return ResourceType::Archive;
+    if (url.starts_with(kObjectsHost))  return ResourceType::Release;
+    if (url.starts_with(kGithubHost)) {
+        if (url.find("/releases/download/") != std::string_view::npos)
+            return ResourceType::Release;
+        if (url.find("/archive/") != std::string_view::npos)
+            return ResourceType::Archive;
+        if (url.ends_with(".git"))
+            return ResourceType::Git;
+    }
+    return ResourceType::Unknown;
+}
+
+bool is_github_url(std::string_view url) {
+    return url.starts_with(kGithubHost) ||
+           url.starts_with(kRawHost) ||
+           url.starts_with(kCodeloadHost) ||
+           url.starts_with(kObjectsHost);
+}
+
+std::vector<std::string> expand(std::string_view url, const ExpandOptions& opts) {
+    std::vector<std::string> out;
+
+    Mode mode = opts.mode.value_or(current_mode());
+
+    // Off → strict: original URL only.
+    if (mode == Mode::Off) {
+        if (!url.empty()) out.emplace_back(url);
+        return out;
+    }
+
+    // Non-GitHub URL: return as-is. We never proxy gitee, custom hosts, etc.
+    if (!is_github_url(url)) {
+        if (!url.empty()) out.emplace_back(url);
+        return out;
+    }
+
+    // Determine type.
+    ResourceType type = opts.type.value_or(classify(url));
+    if (type == ResourceType::Unknown) {
+        out.emplace_back(url);
+        return out;
+    }
+
+    auto candidates = filtered(type, opts.expected_size);
+    shuffle_within_priority_(candidates);
+
+    if (mode != Mode::Force) {
+        out.emplace_back(url);
+    }
+    for (const auto& m : candidates) {
+        if (auto rewritten = rewrite(url, m, type)) {
+            if (std::ranges::find(out, *rewritten) == out.end())
+                out.push_back(std::move(*rewritten));
+        }
+    }
+    return out;
+}
+
+}
diff --git a/src/core/mirror/expand.cppm b/src/core/mirror/expand.cppm
index 6ee53e1f..4261415b 100644
--- a/src/core/mirror/expand.cppm
+++ b/src/core/mirror/expand.cppm
@@ -10,119 +10,24 @@ export module xlings.core.mirror.expand;
 import std;
 
 import xlings.core.config;
-import xlings.core.log;
-import xlings.libs.json;
-import xlings.platform;
 import xlings.core.mirror.types;
 import xlings.core.mirror.registry;
 import xlings.core.mirror.forms;
 
-namespace xlings::mirror {
-
-namespace {
-
-constexpr std::string_view kGithubHost      = "https://github.com/";
-constexpr std::string_view kRawHost         = "https://raw.githubusercontent.com/";
-constexpr std::string_view kCodeloadHost    = "https://codeload.github.com/";
-constexpr std::string_view kObjectsHost     = "https://objects.githubusercontent.com/";
-
-Mode parse_mode_(std::string_view s) {
-    if (s == "off")   return Mode::Off;
-    if (s == "force") return Mode::Force;
-    return Mode::Auto;  // default for unknown / "auto" / empty
-}
-
-// Resolve the process-wide mode once: env var > .xlings.json > Auto.
-Mode resolve_mode_() {
-    if (auto env = std::getenv("XLINGS_MIRROR_FALLBACK"); env && *env)
-        return parse_mode_(env);
-
-    // Read from ~/.xlings.json directly. Adding a typed field to Config
-    // is overkill for one optional setting most users never touch.
-    auto& paths = Config::paths();
-    auto path = paths.homeDir / ".xlings.json";
-    std::error_code ec;
-    if (std::filesystem::exists(path, ec)) {
-        try {
-            auto content = platform::read_file_to_string(path.string());
-            auto json = nlohmann::json::parse(content, nullptr, false);
-            if (!json.is_discarded() && json.is_object()) {
-                if (auto it = json.find("mirror_fallback");
-                    it != json.end() && it->is_string()) {
-                    return parse_mode_(it->get<std::string>());
-                }
-            }
-        } catch (...) {}
-    }
-    return Mode::Auto;
-}
-
-Mode& mode_storage_() {
-    static Mode mode = resolve_mode_();
-    return mode;
-}
-
-// Stable per-process shuffle seed: derive from start-of-process steady
-// clock so different xlings processes hit different mirrors first when
-// priorities tie. A single process keeps the same seed for the rest of
-// its lifetime so debug log reading is reproducible.
-std::uint32_t shuffle_seed_() {
-    static const std::uint32_t seed = static_cast<std::uint32_t>(
-        std::chrono::steady_clock::now().time_since_epoch().count());
-    return seed;
-}
-
-// Shuffle elements with the same priority in-place, deterministic per process.
-void shuffle_within_priority_(std::vector<Mirror>& mirrors) {
-    if (mirrors.size() < 2) return;
-    std::mt19937 rng(shuffle_seed_());
-    auto it = mirrors.begin();
-    while (it != mirrors.end()) {
-        auto end = std::find_if(it, mirrors.end(),
-            [p = it->priority](const Mirror& m) { return m.priority != p; });
-        if (std::distance(it, end) > 1) {
-            std::shuffle(it, end, rng);
-        }
-        it = end;
-    }
-}
-
-} // anonymous namespace
+namespace xlings::mirror { // anonymous namespace
 
 // Mode accessor. Resolved lazily on first read.
-export Mode current_mode() {
-    return mode_storage_();
-}
+export Mode current_mode();
 
 // Override the process-wide mode. Primarily for tests.
-export void set_mode(Mode mode) {
-    mode_storage_() = mode;
-}
+export void set_mode(Mode mode);
 
 // Heuristic URL classification. Bare github.com URLs that are ambiguous
 // between web view and git clone get classified as Unknown — the git
 // caller passes ResourceType::Git via ExpandOptions to disambiguate.
-export ResourceType classify(std::string_view url) {
-    if (url.starts_with(kRawHost))      return ResourceType::Raw;
-    if (url.starts_with(kCodeloadHost)) return ResourceType::Archive;
-    if (url.starts_with(kObjectsHost))  return ResourceType::Release;
-    if (url.starts_with(kGithubHost)) {
-        if (url.find("/releases/download/") != std::string_view::npos)
-            return ResourceType::Release;
-        if (url.find("/archive/") != std::string_view::npos)
-            return ResourceType::Archive;
-        if (url.ends_with(".git"))
-            return ResourceType::Git;
-    }
-    return ResourceType::Unknown;
-}
+export ResourceType classify(std::string_view url);
 
-export bool is_github_url(std::string_view url) {
-    return url.starts_with(kGithubHost) ||
-           url.starts_with(kRawHost) ||
-           url.starts_with(kCodeloadHost) ||
-           url.starts_with(kObjectsHost);
-}
+export bool is_github_url(std::string_view url);
 
 // Main entry point. Returns the ordered list of URLs to try.
 //
@@ -130,43 +35,6 @@ export bool is_github_url(std::string_view url) {
 // Non-GitHub URLs are returned unmodified (no expansion). Mode::Off
 // always returns just the original.
 export std::vector<std::string> expand(std::string_view url,
-                                       const ExpandOptions& opts = {}) {
-    std::vector<std::string> out;
-
-    Mode mode = opts.mode.value_or(current_mode());
-
-    // Off → strict: original URL only.
-    if (mode == Mode::Off) {
-        if (!url.empty()) out.emplace_back(url);
-        return out;
-    }
-
-    // Non-GitHub URL: return as-is. We never proxy gitee, custom hosts, etc.
-    if (!is_github_url(url)) {
-        if (!url.empty()) out.emplace_back(url);
-        return out;
-    }
-
-    // Determine type.
-    ResourceType type = opts.type.value_or(classify(url));
-    if (type == ResourceType::Unknown) {
-        out.emplace_back(url);
-        return out;
-    }
-
-    auto candidates = filtered(type, opts.expected_size);
-    shuffle_within_priority_(candidates);
-
-    if (mode != Mode::Force) {
-        out.emplace_back(url);
-    }
-    for (const auto& m : candidates) {
-        if (auto rewritten = rewrite(url, m, type)) {
-            if (std::ranges::find(out, *rewritten) == out.end())
-                out.push_back(std::move(*rewritten));
-        }
-    }
-    return out;
-}
+                                       const ExpandOptions& opts = {});
 
 } // namespace xlings::mirror
diff --git a/src/core/mirror/forms.cpp b/src/core/mirror/forms.cpp
new file mode 100644
index 00000000..ca9a553f
--- /dev/null
+++ b/src/core/mirror/forms.cpp
@@ -0,0 +1,122 @@
+// xlings.core.mirror.forms — three URL-rewriting strategies that mirrors
+// can declare via `form` in the registry JSON. Each strategy is a pure
+// function so it's trivially unit-testable.
+
+module xlings.core.mirror.forms;
+
+import std;
+import xlings.core.mirror.types;
+
+namespace xlings::mirror {
+
+namespace {
+
+// "https://github.com/" prefix used by the host-replace strategy.
+constexpr std::string_view kGithubHost = "https://github.com/";
+constexpr std::string_view kRawHost    = "https://raw.githubusercontent.com/";
+constexpr std::string_view kCodeloadHost = "https://codeload.github.com/";
+
+// Replace the leading host portion of `url` (matched by `prefix`, which
+// must end with '/') with `replacement` (also ending with '/'). Returns
+// nullopt if `url` doesn't start with `prefix`.
+std::optional<std::string> replace_host_prefix(std::string_view url,
+                                                std::string_view prefix,
+                                                std::string_view replacement) {
+    if (!url.starts_with(prefix)) return std::nullopt;
+    std::string out;
+    out.reserve(replacement.size() + url.size() - prefix.size());
+    out.append(replacement);
+    out.append(url.substr(prefix.size()));
+    return out;
+}
+
+// jsDelivr's gh/ scheme expects: gh/<owner>/<repo>@<ref>/<path>
+// Source URL shape we accept: https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
+// Returns nullopt if path doesn't have all 4 segments.
+std::optional<std::string> rewrite_jsdelivr_(std::string_view url,
+                                              std::string_view mirror_host) {
+    if (!url.starts_with(kRawHost)) return std::nullopt;
+    auto rest = url.substr(kRawHost.size());
+
+    // Split on '/' for the first three segments (owner, repo, ref).
+    std::array<std::string_view, 3> parts{};
+    std::size_t start = 0;
+    for (int i = 0; i < 3; ++i) {
+        auto slash = rest.find('/', start);
+        if (slash == std::string_view::npos) return std::nullopt;
+        parts[i] = rest.substr(start, slash - start);
+        start = slash + 1;
+    }
+    if (parts[0].empty() || parts[1].empty() || parts[2].empty())
+        return std::nullopt;
+    auto path = rest.substr(start);
+    if (path.empty()) return std::nullopt;
+
+    return std::format("https://{}/gh/{}/{}@{}/{}",
+                       mirror_host, parts[0], parts[1], parts[2], path);
+}
+
+// Host-replace handles github.com directly and rewrites raw/codeload
+// flavors into the equivalent path under the mirror host (kkgithub-style).
+std::optional<std::string> rewrite_host_replace_(std::string_view url,
+                                                  std::string_view mirror_host,
+                                                  ResourceType type) {
+    auto base = std::format("https://{}/", mirror_host);
+
+    // github.com → mirror_host (1:1 path mapping)
+    if (auto out = replace_host_prefix(url, kGithubHost, base)) return out;
+
+    // raw.githubusercontent.com/x/y/<ref>/path → mirror/x/y/raw/<ref>/path
+    if (url.starts_with(kRawHost)) {
+        auto rest = url.substr(kRawHost.size());
+        // Need at least owner/repo/ref/path
+        std::size_t slash1 = rest.find('/');
+        if (slash1 == std::string_view::npos) return std::nullopt;
+        std::size_t slash2 = rest.find('/', slash1 + 1);
+        if (slash2 == std::string_view::npos) return std::nullopt;
+        // Insert "raw/" between owner/repo and the rest:
+        //   owner/repo/<ref>/path → owner/repo/raw/<ref>/path
+        return std::format("https://{}/{}/raw/{}",
+                           mirror_host,
+                           rest.substr(0, slash2),  // owner/repo
+                           rest.substr(slash2 + 1));  // ref/path
+    }
+
+    // codeload.github.com/x/y/<type>/<ref> → mirror/x/y/<type>/<ref>
+    // (Most host-replace mirrors don't proxy codeload; mark as unsupported
+    // by returning nullopt so the registry filter drops it instead of
+    // returning a bad URL.)
+    if (url.starts_with(kCodeloadHost) && type == ResourceType::Archive) {
+        return std::nullopt;
+    }
+
+    return std::nullopt;
+}
+
+// Prefix is the simplest: prepend the mirror as a proxy.
+std::optional<std::string> rewrite_prefix_(std::string_view url,
+                                            std::string_view mirror_host) {
+    // Only proxy URLs we actually want mirrored. Refuse to wrap
+    // non-GitHub-family URLs — caller should not have asked.
+    if (!url.starts_with(kGithubHost) &&
+        !url.starts_with(kRawHost) &&
+        !url.starts_with(kCodeloadHost)) {
+        return std::nullopt;
+    }
+    return std::format("https://{}/{}", mirror_host, url);
+}
+
+}
+
+std::optional<std::string> rewrite(std::string_view url,
+                                          const Mirror& mirror,
+                                          ResourceType type) {
+    switch (mirror.form) {
+        case Form::Prefix:      return rewrite_prefix_(url, mirror.host);
+        case Form::HostReplace: return rewrite_host_replace_(url, mirror.host, type);
+        case Form::JsDelivr:    return rewrite_jsdelivr_(url, mirror.host);
+    }
+    return std::nullopt;
+}
+
+}
diff --git a/src/core/mirror/forms.cppm b/src/core/mirror/forms.cppm
index 3454f588..e510c80e 100644
--- a/src/core/mirror/forms.cppm
+++ b/src/core/mirror/forms.cppm
@@ -7,119 +7,13 @@ export module xlings.core.mirror.forms;
 import std;
 import xlings.core.mirror.types;
 
-namespace xlings::mirror {
-
-namespace {
-
-// "https://github.com/" prefix used by the host-replace strategy.
-constexpr std::string_view kGithubHost = "https://github.com/";
-constexpr std::string_view kRawHost    = "https://raw.githubusercontent.com/";
-constexpr std::string_view kCodeloadHost = "https://codeload.github.com/";
-
-// Replace the leading host portion of `url` (matched by `prefix`, which
-// must end with '/') with `replacement` (also ending with '/'). Returns
-// nullopt if `url` doesn't start with `prefix`.
-std::optional<std::string> replace_host_prefix(std::string_view url,
-                                                std::string_view prefix,
-                                                std::string_view replacement) {
-    if (!url.starts_with(prefix)) return std::nullopt;
-    std::string out;
-    out.reserve(replacement.size() + url.size() - prefix.size());
-    out.append(replacement);
-    out.append(url.substr(prefix.size()));
-    return out;
-}
-
-// jsDelivr's gh/ scheme expects: gh/<owner>/<repo>@<ref>/<path>
-// Source URL shape we accept: https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
-// Returns nullopt if path doesn't have all 4 segments.
-std::optional<std::string> rewrite_jsdelivr_(std::string_view url,
-                                              std::string_view mirror_host) {
-    if (!url.starts_with(kRawHost)) return std::nullopt;
-    auto rest = url.substr(kRawHost.size());
-
-    // Split on '/' for the first three segments (owner, repo, ref).
-    std::array<std::string_view, 3> parts{};
-    std::size_t start = 0;
-    for (int i = 0; i < 3; ++i) {
-        auto slash = rest.find('/', start);
-        if (slash == std::string_view::npos) return std::nullopt;
-        parts[i] = rest.substr(start, slash - start);
-        start = slash + 1;
-    }
-    if (parts[0].empty() || parts[1].empty() || parts[2].empty())
-        return std::nullopt;
-    auto path = rest.substr(start);
-    if (path.empty()) return std::nullopt;
-
-    return std::format("https://{}/gh/{}/{}@{}/{}",
-                       mirror_host, parts[0], parts[1], parts[2], path);
-}
-
-// Host-replace handles github.com directly and rewrites raw/codeload
-// flavors into the equivalent path under the mirror host (kkgithub-style).
-std::optional<std::string> rewrite_host_replace_(std::string_view url,
-                                                  std::string_view mirror_host,
-                                                  ResourceType type) {
-    auto base = std::format("https://{}/", mirror_host);
-
-    // github.com → mirror_host (1:1 path mapping)
-    if (auto out = replace_host_prefix(url, kGithubHost, base)) return out;
-
-    // raw.githubusercontent.com/x/y/<ref>/path → mirror/x/y/raw/<ref>/path
-    if (url.starts_with(kRawHost)) {
-        auto rest = url.substr(kRawHost.size());
-        // Need at least owner/repo/ref/path
-        std::size_t slash1 = rest.find('/');
-        if (slash1 == std::string_view::npos) return std::nullopt;
-        std::size_t slash2 = rest.find('/', slash1 + 1);
-        if (slash2 == std::string_view::npos) return std::nullopt;
-        // Insert "raw/" between owner/repo and the rest:
-        //   owner/repo/<ref>/path → owner/repo/raw/<ref>/path
-        return std::format("https://{}/{}/raw/{}",
-                           mirror_host,
-                           rest.substr(0, slash2),  // owner/repo
-                           rest.substr(slash2 + 1));  // ref/path
-    }
-
-    // codeload.github.com/x/y/<type>/<ref> → mirror/x/y/<type>/<ref>
-    // (Most host-replace mirrors don't proxy codeload; mark as unsupported
-    // by returning nullopt so the registry filter drops it instead of
-    // returning a bad URL.)
-    if (url.starts_with(kCodeloadHost) && type == ResourceType::Archive) {
-        return std::nullopt;
-    }
-
-    return std::nullopt;
-}
-
-// Prefix is the simplest: prepend the mirror as a proxy.
-std::optional<std::string> rewrite_prefix_(std::string_view url,
-                                            std::string_view mirror_host) {
-    // Only proxy URLs we actually want mirrored. Refuse to wrap
-    // non-GitHub-family URLs — caller should not have asked.
-    if (!url.starts_with(kGithubHost) &&
-        !url.starts_with(kRawHost) &&
-        !url.starts_with(kCodeloadHost)) {
-        return std::nullopt;
-    }
-    return std::format("https://{}/{}", mirror_host, url);
-}
-
-} // anonymous namespace
+namespace xlings::mirror { // anonymous namespace
 
 // Public entry point used by expand.cppm. Returns the rewritten URL, or
 // nullopt when the mirror's form is incompatible with the input URL —
 // the caller drops that mirror from the candidate list.
 export std::optional<std::string> rewrite(std::string_view url,
                                           const Mirror& mirror,
-                                          ResourceType type) {
-    switch (mirror.form) {
-        case Form::Prefix:      return rewrite_prefix_(url, mirror.host);
-        case Form::HostReplace: return rewrite_host_replace_(url, mirror.host, type);
-        case Form::JsDelivr:    return rewrite_jsdelivr_(url, mirror.host);
-    }
-    return std::nullopt;
-}
+                                          ResourceType type);
 
 } // namespace xlings::mirror
diff --git a/src/core/mirror/registry.cpp b/src/core/mirror/registry.cpp
new file mode 100644
index 00000000..36a12d92
--- /dev/null
+++ b/src/core/mirror/registry.cpp
@@ -0,0 +1,179 @@
+// xlings.core.mirror.registry — load + cache the mirror list.
+//
+// Resolution order (first hit wins):
+//   1. ~/.xlings/data/github-mirrors.json (user override; full replacement)
+//   2. compiled-in DEFAULT_MIRRORS_JSON
+//
+// Loaded once on first call to all() / filtered(), then memoized for the
+// process lifetime. Failure to parse a user override is logged at warn
+// level and the default list is used instead.
+
+module xlings.core.mirror.registry;
+
+import std;
+import xlings.core.config;
+import xlings.core.log;
+import xlings.libs.json;
+import xlings.platform;
+import xlings.core.mirror.types;
+
+namespace xlings::mirror {
+
+namespace {
+
+// Default mirror list. This is an embedded resource — updates require a
+// release. See docs/plans/2026-05-01-mirror-fallback-step1.md for the
+// rationale (rejecting remote hot-update because of chicken-and-egg).
+//
+// Ordering by priority (ascending = tried first):
+//   jsdelivr     priority  5   raw-only, very stable
+//   ghfast       priority 10   active 2025
+//   ghproxy-net  priority 20   active 2025
+//   kkgithub     priority 30   host-replace style fallback
+constexpr std::string_view DEFAULT_MIRRORS_JSON = R"JSON({
+  "version": 1,
+  "mirrors": [
+    {
+      "name": "jsdelivr",
+      "form": "jsdelivr",
+      "host": "cdn.jsdelivr.net",
+      "supports": ["raw"],
+      "limit_bytes": 52428800,
+      "priority": 5
+    },
+    {
+      "name": "ghfast",
+      "form": "prefix",
+      "host": "ghfast.top",
+      "supports": ["release", "raw", "archive", "git"],
+      "priority": 10
+    },
+    {
+      "name": "ghproxy-net",
+      "form": "prefix",
+      "host": "ghproxy.net",
+      "supports": ["release", "raw", "archive", "git"],
+      "priority": 20
+    },
+    {
+      "name": "kkgithub",
+      "form": "host-replace",
+      "host": "kkgithub.com",
+      "supports": ["release", "raw", "archive", "git"],
+      "priority": 30
+    }
+  ]
+})JSON";
+
+std::optional<Form> parse_form_(std::string_view s) {
+    if (s == "prefix")       return Form::Prefix;
+    if (s == "host-replace") return Form::HostReplace;
+    if (s == "jsdelivr")     return Form::JsDelivr;
+    return std::nullopt;
+}
+
+std::optional<ResourceType> parse_resource_type_(std::string_view s) {
+    if (s == "release") return ResourceType::Release;
+    if (s == "raw")     return ResourceType::Raw;
+    if (s == "archive") return ResourceType::Archive;
+    if (s == "git")     return ResourceType::Git;
+    return std::nullopt;
+}
+
+// Parse a mirrors JSON document into a vector of Mirror. Returns nullopt
+// on any parse error so the caller can fall back to defaults.
+std::optional<std::vector<Mirror>> parse_mirrors_json_(std::string_view json_text) {
+    auto root = nlohmann::json::parse(json_text, nullptr, false);
+    if (root.is_discarded() || !root.is_object()) return std::nullopt;
+
+    auto mirrors_node = root.find("mirrors");
+    if (mirrors_node == root.end() || !mirrors_node->is_array()) return std::nullopt;
+
+    std::vector<Mirror> out;
+    out.reserve(mirrors_node->size());
+
+    for (const auto& m : *mirrors_node) {
+        if (!m.is_object()) continue;
+        Mirror mir;
+
+        if (auto it = m.find("name"); it != m.end() && it->is_string())
+            mir.name = it->get<std::string>();
+        if (auto it = m.find("host"); it != m.end() && it->is_string())
+            mir.host = it->get<std::string>();
+        if (auto it = m.find("priority"); it != m.end() && it->is_number_integer())
+            mir.priority = it->get<int>();
+
+        auto form_it = m.find("form");
+        if (form_it == m.end() || !form_it->is_string()) continue;
+        auto form = parse_form_(form_it->get<std::string>());
+        if (!form) continue;
+        mir.form = *form;
+
+        if (auto it = m.find("supports"); it != m.end() && it->is_array()) {
+            for (const auto& s : *it) {
+                if (!s.is_string()) continue;
+                if (auto rt = parse_resource_type_(s.get<std::string>()))
+                    mir.supports.push_back(*rt);
+            }
+        }
+        if (auto it = m.find("limit_bytes"); it != m.end() && it->is_number_unsigned())
+            mir.limit_bytes = it->get<std::size_t>();
+
+        if (mir.host.empty() || mir.name.empty() || mir.supports.empty())
+            continue;
+        out.push_back(std::move(mir));
+    }
+
+    // Stable sort ascending by priority for deterministic iteration.
+    std::ranges::stable_sort(out, [](const Mirror& a, const Mirror& b) {
+        return a.priority < b.priority;
+    });
+    return out;
+}
+
+// Load the effective mirror list once, memoize for process lifetime.
+const std::vector<Mirror>& load_once_() {
+    static const std::vector<Mirror> mirrors = [] {
+        auto& paths = Config::paths();
+        auto user_path = paths.dataDir / "github-mirrors.json";
+
+        std::error_code ec;
+        if (fs::exists(user_path, ec)) {
+            auto content = platform::read_file_to_string(user_path.string());
+            if (auto parsed = parse_mirrors_json_(content)) {
+                log::debug("[mirror] loaded {} mirrors from {}",
+                          parsed->size(), user_path.string());
+                return std::move(*parsed);
+            }
+            log::warn("[mirror] failed to parse {}, falling back to defaults",
+                     user_path.string());
+        }
+
+        if (auto parsed = parse_mirrors_json_(DEFAULT_MIRRORS_JSON))
+            return std::move(*parsed);
+
+        log::warn("[mirror] failed to parse compiled-in defaults; mirror "
+                  "fallback disabled");
+        return std::vector<Mirror>{};
+    }();
+    return mirrors;
+}
+
+}
+
+std::span<const Mirror> all() {
+    return load_once_();
+}
+
+std::vector<Mirror> filtered(ResourceType type, std::size_t expected_size) {
+    std::vector<Mirror> out;
+    for (const auto& m : load_once_()) {
+        if (std::ranges::find(m.supports, type) == m.supports.end()) continue;
+        if (expected_size > 0 && m.limit_bytes && expected_size > *m.limit_bytes)
+            continue;
+        out.push_back(m);
+    }
+    return out;
+}
+
+}
diff --git a/src/core/mirror/registry.cppm b/src/core/mirror/registry.cppm
index 7bc2eb68..72bf84b8 100644
--- a/src/core/mirror/registry.cppm
+++ b/src/core/mirror/registry.cppm
@@ -13,176 +13,20 @@ export module xlings.core.mirror.registry;
 import std;
 
 import xlings.core.config;
-import xlings.core.log;
-import xlings.libs.json;
-import xlings.platform;
 import xlings.core.mirror.types;
 
 namespace xlings::mirror {
 
-namespace fs = std::filesystem;
-
-namespace {
-
-// Default mirror list. This is an embedded resource — updates require a
-// release. See docs/plans/2026-05-01-mirror-fallback-step1.md for the
-// rationale (rejecting remote hot-update because of chicken-and-egg).
-//
-// Ordering by priority (ascending = tried first):
-//   jsdelivr     priority  5   raw-only, very stable
-//   ghfast       priority 10   active 2025
-//   ghproxy-net  priority 20   active 2025
-//   kkgithub     priority 30   host-replace style fallback
-constexpr std::string_view DEFAULT_MIRRORS_JSON = R"JSON({
-  "version": 1,
-  "mirrors": [
-    {
-      "name": "jsdelivr",
-      "form": "jsdelivr",
-      "host": "cdn.jsdelivr.net",
-      "supports": ["raw"],
-      "limit_bytes": 52428800,
-      "priority": 5
-    },
-    {
-      "name": "ghfast",
-      "form": "prefix",
-      "host": "ghfast.top",
-      "supports": ["release", "raw", "archive", "git"],
-      "priority": 10
-    },
-    {
-      "name": "ghproxy-net",
-      "form": "prefix",
-      "host": "ghproxy.net",
-      "supports": ["release", "raw", "archive", "git"],
-      "priority": 20
-    },
-    {
-      "name": "kkgithub",
-      "form": "host-replace",
-      "host": "kkgithub.com",
-      "supports": ["release", "raw", "archive", "git"],
-      "priority": 30
-    }
-  ]
-})JSON";
-
-std::optional<Form> parse_form_(std::string_view s) {
-    if (s == "prefix")       return Form::Prefix;
-    if (s == "host-replace") return Form::HostReplace;
-    if (s == "jsdelivr")     return Form::JsDelivr;
-    return std::nullopt;
-}
-
-std::optional<ResourceType> parse_resource_type_(std::string_view s) {
-    if (s == "release") return ResourceType::Release;
-    if (s == "raw")     return ResourceType::Raw;
-    if (s == "archive") return ResourceType::Archive;
-    if (s == "git")     return ResourceType::Git;
-    return std::nullopt;
-}
-
-// Parse a mirrors JSON document into a vector of Mirror. Returns nullopt
-// on any parse error so the caller can fall back to defaults.
-std::optional<std::vector<Mirror>> parse_mirrors_json_(std::string_view json_text) {
-    auto root = nlohmann::json::parse(json_text, nullptr, false);
-    if (root.is_discarded() || !root.is_object()) return std::nullopt;
-
-    auto mirrors_node = root.find("mirrors");
-    if (mirrors_node == root.end() || !mirrors_node->is_array()) return std::nullopt;
-
-    std::vector<Mirror> out;
-    out.reserve(mirrors_node->size());
-
-    for (const auto& m : *mirrors_node) {
-        if (!m.is_object()) continue;
-        Mirror mir;
-
-        if (auto it = m.find("name"); it != m.end() && it->is_string())
-            mir.name = it->get<std::string>();
-        if (auto it = m.find("host"); it != m.end() && it->is_string())
-            mir.host = it->get<std::string>();
-        if (auto it = m.find("priority"); it != m.end() && it->is_number_integer())
-            mir.priority = it->get<int>();
-
-        auto form_it = m.find("form");
-        if (form_it == m.end() || !form_it->is_string()) continue;
-        auto form = parse_form_(form_it->get<std::string>());
-        if (!form) continue;
-        mir.form = *form;
-
-        if (auto it = m.find("supports"); it != m.end() && it->is_array()) {
-            for (const auto& s : *it) {
-                if (!s.is_string()) continue;
-                if (auto rt = parse_resource_type_(s.get<std::string>()))
-                    mir.supports.push_back(*rt);
-            }
-        }
-        if (auto it = m.find("limit_bytes"); it != m.end() && it->is_number_unsigned())
-            mir.limit_bytes = it->get<std::size_t>();
-
-        if (mir.host.empty() || mir.name.empty() || mir.supports.empty())
-            continue;
-        out.push_back(std::move(mir));
-    }
-
-    // Stable sort ascending by priority for deterministic iteration.
-    std::ranges::stable_sort(out, [](const Mirror& a, const Mirror& b) {
-        return a.priority < b.priority;
-    });
-    return out;
-}
-
-// Load the effective mirror list once, memoize for process lifetime.
-const std::vector<Mirror>& load_once_() {
-    static const std::vector<Mirror> mirrors = [] {
-        auto& paths = Config::paths();
-        auto user_path = paths.dataDir / "github-mirrors.json";
-
-        std::error_code ec;
-        if (fs::exists(user_path, ec)) {
-            auto content = platform::read_file_to_string(user_path.string());
-            if (auto parsed = parse_mirrors_json_(content)) {
-                log::debug("[mirror] loaded {} mirrors from {}",
-                          parsed->size(), user_path.string());
-                return std::move(*parsed);
-            }
-            log::warn("[mirror] failed to parse {}, falling back to defaults",
-                     user_path.string());
-        }
-
-        if (auto parsed = parse_mirrors_json_(DEFAULT_MIRRORS_JSON))
-            return std::move(*parsed);
-
-        log::warn("[mirror] failed to parse compiled-in defaults; mirror "
-                  "fallback disabled");
-        return std::vector<Mirror>{};
-    }();
-    return mirrors;
-}
-
-} // anonymous namespace
+namespace fs = std::filesystem; // anonymous namespace
 
 // All mirrors, in priority order. Read-only view; the underlying storage
 // is process-wide and immutable after first load.
-export std::span<const Mirror> all() {
-    return load_once_();
-}
+export std::span<const Mirror> all();
 
 // Mirrors filtered by resource type and (optionally) by `expected_size`.
 // Expected size of 0 means "size unknown" — limit_bytes filter is skipped
 // because we can't know whether the mirror will refuse the request.
 export std::vector<Mirror> filtered(ResourceType type,
-                                     std::size_t expected_size = 0) {
-    std::vector<Mirror> out;
-    for (const auto& m : load_once_()) {
-        if (std::ranges::find(m.supports, type) == m.supports.end()) continue;
-        if (expected_size > 0 && m.limit_bytes && expected_size > *m.limit_bytes)
-            continue;
-        out.push_back(m);
-    }
-    return out;
-}
+                                     std::size_t expected_size = 0);
 
 } // namespace xlings::mirror
diff --git a/src/core/profile.cpp b/src/core/profile.cpp
new file mode 100644
index 00000000..5f39448d
--- /dev/null
+++ b/src/core/profile.cpp
@@ -0,0 +1,373 @@
+module;
+
+#include <ctime>
+#include <cstdio>
+
+module xlings.core.profile;
+
+import std;
+import xlings.core.config;
+import xlings.libs.json;
+import xlings.core.log;
+import xlings.platform;
+import xlings.core.utils;
+import xlings.core.xvm.db;
+import xlings.core.xvm.types;
+
+namespace xlings::profile {
+
+std::string utc_now_iso_() {
+    auto now   = std::chrono::system_clock::now();
+    auto nowTT = std::chrono::system_clock::to_time_t(now);
+    char buf[32];
+    std::strftime(buf, sizeof(buf), "%Y-%m-%dT%H:%M:%SZ", std::gmtime(&nowTT));
+    return buf;
+}
+
+int next_gen_number_(const fs::path& gensDir) {
+    int maxNum = 0;
+    if (!fs::exists(gensDir)) return 1;
+    for (auto& entry : platform::dir_entries(gensDir)) {
+        auto stem = entry.path().stem().string();
+        try { maxNum = std::max(maxNum, std::stoi(stem)); }
+        catch (...) {}
+    }
+    return maxNum + 1;
+}
+
+// NOTE: `.workspace.xvm.yaml` used to be written here and by rollback().
+// Nothing in the tree ever read it -- which is what made `profile rollback`
+// a no-op with respect to version selection: it recorded an intent in a file
+// no reader consulted, and the live workspace kept whatever it had. Rollback
+// now returns the selection so the caller can apply it through the real
+// switch path, and the file is gone rather than left as a decoy.
+std::uintmax_t dir_size_(const fs::path& dir) {
+    std::uintmax_t total = 0;
+    std::error_code ec;
+    for (auto it = fs::recursive_directory_iterator(dir, ec); it != std::default_sentinel; ++it) {
+        if (it->is_regular_file())
+            total += it->file_size();
+    }
+    return total;
+}
+
+Generation load_current(const fs::path& envDir) {
+    auto profilePath = envDir / ".profile.json";
+    if (!fs::exists(profilePath)) return {0, "", "init", {}};
+    try {
+        auto content = platform::read_file_to_string(profilePath.string());
+        auto json = nlohmann::json::parse(content);
+        Generation gen;
+        gen.number  = json.value("current_generation", 0);
+        gen.created = json.value("created", "");
+        gen.reason  = json.value("reason", "");
+        if (json.contains("packages") && json["packages"].is_object()) {
+            for (auto it = json["packages"].begin(); it != json["packages"].end(); ++it)
+                gen.packages[it.key()] = it.value().get<std::string>();
+        }
+        return gen;
+    } catch (...) { return {0, "", "init", {}}; }
+}
+
+int commit(const fs::path& envDir,
+                  std::map<std::string, std::string> packages,
+                  const std::string& reason) {
+    auto gensDir = envDir / "generations";
+    fs::create_directories(gensDir);
+
+    int nextGen = next_gen_number_(gensDir);
+    auto now = utc_now_iso_();
+
+    nlohmann::json genJson = {
+        {"generation", nextGen},
+        {"created",    now},
+        {"reason",     reason},
+        {"packages",   packages}
+    };
+    auto genFile = gensDir / (([](int n) { char b[8]; std::snprintf(b, sizeof(b), "%03d", n); return std::string(b); })(nextGen) + ".json");
+    platform::write_string_to_file(genFile.string(), genJson.dump(2));
+
+    nlohmann::json profileJson = {
+        {"current_generation", nextGen},
+        {"packages",           packages}
+    };
+    platform::write_string_to_file((envDir / ".profile.json").string(),
+                                profileJson.dump(2));
+
+    return 0;
+}
+
+std::vector<Generation> list_generations(const fs::path& envDir) {
+    std::vector<Generation> result;
+    auto gensDir = envDir / "generations";
+    if (!fs::exists(gensDir)) return result;
+
+    for (auto& entry : platform::dir_entries(gensDir)) {
+        if (!entry.is_regular_file()) continue;
+        try {
+            auto content = platform::read_file_to_string(entry.path().string());
+            auto json = nlohmann::json::parse(content);
+            Generation gen;
+            gen.number  = json.value("generation", 0);
+            gen.created = json.value("created", "");
+            gen.reason  = json.value("reason", "");
+            if (json.contains("packages") && json["packages"].is_object())
+                for (auto it = json["packages"].begin(); it != json["packages"].end(); ++it)
+                    gen.packages[it.key()] = it.value().get<std::string>();
+            result.push_back(gen);
+        } catch (...) {}
+    }
+
+    std::ranges::sort(result, {}, &Generation::number);
+    return result;
+}
+
+std::expected<std::map<std::string, std::string>, std::string>
+rollback(const fs::path& envDir, int targetGen) {
+    std::map<std::string, std::string> packages;
+
+    if (targetGen > 0) {
+        auto gensDir = envDir / "generations";
+        auto genFile = gensDir / (([](int n) { char b[8]; std::snprintf(b, sizeof(b), "%03d", n); return std::string(b); })(targetGen) + ".json");
+        if (!fs::exists(genFile)) {
+            return std::unexpected(
+                std::format("generation {} not found", targetGen));
+        }
+        try {
+            auto content = platform::read_file_to_string(genFile.string());
+            auto json = nlohmann::json::parse(content);
+            for (auto it = json["packages"].begin(); it != json["packages"].end(); ++it)
+                packages[it.key()] = it.value().get<std::string>();
+        } catch (...) {
+            return std::unexpected(
+                std::format("failed to read generation {}", targetGen));
+        }
+    }
+
+    nlohmann::json profileJson = {
+        {"current_generation", targetGen},
+        {"packages",           packages}
+    };
+    platform::write_string_to_file((envDir / ".profile.json").string(),
+                                profileJson.dump(2));
+
+    return packages;
+}
+
+std::vector<SubosSnapshot> load_subos_snapshots(const fs::path& xlingsHome) {
+    std::vector<SubosSnapshot> snapshots;
+    auto subosDir = xlingsHome / "subos";
+    std::error_code ec;
+    if (!fs::is_directory(subosDir, ec)) return snapshots;
+
+    for (auto& entry : platform::dir_entries(subosDir)) {
+        std::error_code dec;
+        if (!entry.is_directory(dec)) continue;
+        auto name = entry.path().filename().string();
+        if (name == "current") continue;
+        auto wsPath = entry.path() / ".xlings.json";
+        std::error_code fec;
+        if (!fs::exists(wsPath, fec)) continue;
+        try {
+            auto content = platform::read_file_to_string(wsPath.string());
+            auto json = nlohmann::json::parse(content, nullptr, false);
+            if (json.is_discarded() || !json.is_object()) continue;
+            if (!json.contains("workspace") || !json["workspace"].is_object()) continue;
+            snapshots.push_back({
+                .name = name,
+                .dir = entry.path(),
+                .workspace = xvm::subos_workspace_from_json(json["workspace"]),
+            });
+        } catch (...) {}
+    }
+    std::ranges::sort(snapshots, [](const auto& a, const auto& b) {
+        return a.name < b.name;
+    });
+    return snapshots;
+}
+
+bool save_subos_workspace(const fs::path& subosRoot,
+                                 const xvm::SubosWorkspace& workspace) {
+    const auto wsPath = subosRoot / ".xlings.json";
+    nlohmann::json json = nlohmann::json::object();
+    std::error_code ec;
+    if (fs::exists(wsPath, ec)) {
+        try {
+            auto content = platform::read_file_to_string(wsPath.string());
+            auto parsed = nlohmann::json::parse(content, nullptr, false);
+            if (!parsed.is_discarded() && parsed.is_object()) {
+                json = std::move(parsed);
+            } else {
+                // Refuse rather than replace: an unreadable file is not an
+                // empty one, and overwriting it would turn "we could not read
+                // your subos" into "your subos is now blank".
+                return false;
+            }
+        } catch (...) {
+            return false;
+        }
+    }
+    json["workspace"] = xvm::subos_workspace_to_json(workspace);
+    try {
+        platform::write_string_to_file(wsPath.string(), json.dump(2));
+    } catch (...) {
+        return false;
+    }
+    return true;
+}
+
+// Build a set of referenced xpkg "dirname/version" keys from all subos workspaces
+// by mapping workspace target names to xpkg directory paths via the versions DB.
+std::set<std::string> collect_subos_references_(const fs::path& xlingsHome) {
+    std::set<std::string> referenced;
+    auto xpkgsDir = xlingsHome / "data" / "xpkgs";
+
+    // Load global versions DB
+    auto configPath = xlingsHome / ".xlings.json";
+    xvm::VersionDB globalDB;
+    if (fs::exists(configPath)) {
+        try {
+            auto content = platform::read_file_to_string(configPath.string());
+            auto json = nlohmann::json::parse(content, nullptr, false);
+            if (!json.is_discarded() && json.contains("versions"))
+                globalDB = xvm::versions_from_json(json["versions"]);
+        } catch (...) {}
+    }
+
+    // Build a map: xpkg_dir_name/version -> key, from versions DB paths
+    // e.g., "xim-x-gcc/15.1.0" from path "/home/.../.xlings/data/xpkgs/xim-x-gcc/15.1.0/bin"
+    //
+    // Pin every payload of every target name that appears in either the
+    // active or installed[] map. (The lambda is intentionally coarse:
+    // currently a target name in workspace pins ALL versions of that
+    // target; finer-grained per-version pinning is a separate
+    // refactor.) The 0.4.19 fix here is to also walk installed[] —
+    // pre-fix, a target only pinned in installed[] of some subos (e.g.
+    // after `xlings remove` cleared its active but the user kept
+    // installed[]) was eligible for GC.
+    auto add_refs_from_subos_workspace = [&](const xvm::SubosWorkspace& sws) {
+        std::set<std::string> targetNames;
+        for (auto& [target, _] : sws.active) targetNames.insert(target);
+        for (auto& [target, _] : sws.installed) targetNames.insert(target);
+        for (auto& target : targetNames) {
+            auto it = globalDB.find(target);
+            if (it == globalDB.end()) continue;
+            for (auto& [verKey, vdata] : it->second.versions) {
+                if (vdata.path.empty()) continue;
+                // Extract xpkg dir from path: .../xpkgs/<dirname>/<version>/...
+                auto xpkgsPos = vdata.path.find("xpkgs/");
+                if (xpkgsPos == std::string::npos) continue;
+                auto rel = vdata.path.substr(xpkgsPos + 6); // after "xpkgs/"
+                // rel is like "xim-x-gcc/15.1.0/bin" or "xim-x-gcc/15.1.0"
+                // Extract first two path components: dirname/version
+                auto slash1 = rel.find('/');
+                if (slash1 == std::string::npos) continue;
+                auto slash2 = rel.find('/', slash1 + 1);
+                auto dirAndVer = (slash2 != std::string::npos)
+                    ? rel.substr(0, slash2)
+                    : rel;
+                referenced.insert(dirAndVer);
+            }
+        }
+    };
+
+    // Scan all subos workspace files
+    for (auto& snapshot : load_subos_snapshots(xlingsHome)) {
+        add_refs_from_subos_workspace(snapshot.workspace);
+    }
+
+    return referenced;
+}
+
+std::vector<std::string> find_subos_referencing(
+        const fs::path& xlingsHome, const std::string& target) {
+    std::vector<std::string> result;
+    for (auto& snapshot : load_subos_snapshots(xlingsHome)) {
+        if (snapshot.workspace.active.contains(target)
+            || snapshot.workspace.installed.contains(target)) {
+            result.push_back(snapshot.name);
+        }
+    }
+    return result;
+}
+
+std::vector<std::string> find_subos_pinning_version(
+        const fs::path& xlingsHome,
+        const std::string& target,
+        const std::string& version) {
+    auto matches = [&](std::string_view stored) {
+        return stored == version
+            || xvm::strip_namespace(std::string(stored)) == version;
+    };
+
+    std::vector<std::string> result;
+    for (auto& snapshot : load_subos_snapshots(xlingsHome)) {
+        const auto& ws = snapshot.workspace;
+        bool pinned = false;
+        if (auto it = ws.active.find(target);
+            it != ws.active.end() && matches(it->second)) {
+            pinned = true;
+        }
+        if (!pinned) {
+            // installed[] pins the payload just as hard as active does — a
+            // subos that opted into the version but is not currently using it
+            // still breaks if the payload goes.
+            if (auto it = ws.installed.find(target); it != ws.installed.end()) {
+                for (auto& v : it->second) {
+                    if (matches(v)) { pinned = true; break; }
+                }
+            }
+        }
+        if (pinned) result.push_back(snapshot.name);
+    }
+    return result;
+}
+
+int gc(const fs::path& xlingsHome, bool dryRun) {
+    auto referenced = collect_subos_references_(xlingsHome);
+
+    auto pkgDir = xlingsHome / "data" / "xpkgs";
+    if (!fs::exists(pkgDir)) {
+        std::println("[xlings:store] xpkgs not found, nothing to gc");
+        return 0;
+    }
+
+    std::uintmax_t freedBytes = 0;
+    int removedCount = 0;
+
+    for (auto& pkgEntry : platform::dir_entries(pkgDir)) {
+        if (!pkgEntry.is_directory()) continue;
+        auto pkgName = pkgEntry.path().filename().string();
+        for (auto& verEntry : platform::dir_entries(pkgEntry)) {
+            if (!verEntry.is_directory()) continue;
+            auto ver = verEntry.path().filename().string();
+            auto key = pkgName + "/" + ver;
+            if (!referenced.count(key)) {
+                auto size = dir_size_(verEntry.path());
+                if (dryRun) {
+                    auto mb = static_cast<int>(static_cast<double>(size) / 1e5) / 10.0;
+                    std::println("  would remove xpkgs/{}/{} ({} MB)", pkgName, ver, mb);
+                } else {
+                    std::error_code ec;
+                    fs::remove_all(verEntry.path(), ec);
+                    if (!ec)
+                        std::println("[xlings:store] removed xpkgs/{}/{}", pkgName, ver);
+                }
+                freedBytes += size;
+                ++removedCount;
+            }
+        }
+    }
+
+    auto totalMb = static_cast<int>(static_cast<double>(freedBytes) / 1e5) / 10.0;
+    if (dryRun) {
+        std::println("[xlings:store] gc dry-run: {} packages, {} MB would be freed",
+            removedCount, totalMb);
+    } else {
+        std::println("[xlings:store] gc: {} packages removed, {} MB freed",
+            removedCount, totalMb);
+    }
+    return 0;
+}
+
+}
diff --git a/src/core/profile.cppm b/src/core/profile.cppm
index 1a787e26..6a998b7c 100644
--- a/src/core/profile.cppm
+++ b/src/core/profile.cppm
@@ -8,10 +8,6 @@ export module xlings.core.profile;
 import std;
 
 import xlings.core.config;
-import xlings.libs.json;
-import xlings.core.log;
-import xlings.platform;
-import xlings.core.utils;
 import xlings.core.xvm.db;
 import xlings.core.xvm.types;
 
@@ -26,112 +22,13 @@ export struct Generation {
     std::map<std::string, std::string>     packages;
 };
 
-std::string utc_now_iso_() {
-    auto now   = std::chrono::system_clock::now();
-    auto nowTT = std::chrono::system_clock::to_time_t(now);
-    char buf[32];
-    std::strftime(buf, sizeof(buf), "%Y-%m-%dT%H:%M:%SZ", std::gmtime(&nowTT));
-    return buf;
-}
-
-int next_gen_number_(const fs::path& gensDir) {
-    int maxNum = 0;
-    if (!fs::exists(gensDir)) return 1;
-    for (auto& entry : platform::dir_entries(gensDir)) {
-        auto stem = entry.path().stem().string();
-        try { maxNum = std::max(maxNum, std::stoi(stem)); }
-        catch (...) {}
-    }
-    return maxNum + 1;
-}
-
-// NOTE: `.workspace.xvm.yaml` used to be written here and by rollback().
-// Nothing in the tree ever read it -- which is what made `profile rollback`
-// a no-op with respect to version selection: it recorded an intent in a file
-// no reader consulted, and the live workspace kept whatever it had. Rollback
-// now returns the selection so the caller can apply it through the real
-// switch path, and the file is gone rather than left as a decoy.
-
-std::uintmax_t dir_size_(const fs::path& dir) {
-    std::uintmax_t total = 0;
-    std::error_code ec;
-    for (auto it = fs::recursive_directory_iterator(dir, ec); it != std::default_sentinel; ++it) {
-        if (it->is_regular_file())
-            total += it->file_size();
-    }
-    return total;
-}
-
-export Generation load_current(const fs::path& envDir) {
-    auto profilePath = envDir / ".profile.json";
-    if (!fs::exists(profilePath)) return {0, "", "init", {}};
-    try {
-        auto content = platform::read_file_to_string(profilePath.string());
-        auto json = nlohmann::json::parse(content);
-        Generation gen;
-        gen.number  = json.value("current_generation", 0);
-        gen.created = json.value("created", "");
-        gen.reason  = json.value("reason", "");
-        if (json.contains("packages") && json["packages"].is_object()) {
-            for (auto it = json["packages"].begin(); it != json["packages"].end(); ++it)
-                gen.packages[it.key()] = it.value().get<std::string>();
-        }
-        return gen;
-    } catch (...) { return {0, "", "init", {}}; }
-}
+export Generation load_current(const fs::path& envDir);
 
 export int commit(const fs::path& envDir,
                   std::map<std::string, std::string> packages,
-                  const std::string& reason) {
-    auto gensDir = envDir / "generations";
-    fs::create_directories(gensDir);
-
-    int nextGen = next_gen_number_(gensDir);
-    auto now = utc_now_iso_();
-
-    nlohmann::json genJson = {
-        {"generation", nextGen},
-        {"created",    now},
-        {"reason",     reason},
-        {"packages",   packages}
-    };
-    auto genFile = gensDir / (([](int n) { char b[8]; std::snprintf(b, sizeof(b), "%03d", n); return std::string(b); })(nextGen) + ".json");
-    platform::write_string_to_file(genFile.string(), genJson.dump(2));
+                  const std::string& reason);
 
-    nlohmann::json profileJson = {
-        {"current_generation", nextGen},
-        {"packages",           packages}
-    };
-    platform::write_string_to_file((envDir / ".profile.json").string(),
-                                profileJson.dump(2));
-
-    return 0;
-}
-
-export std::vector<Generation> list_generations(const fs::path& envDir) {
-    std::vector<Generation> result;
-    auto gensDir = envDir / "generations";
-    if (!fs::exists(gensDir)) return result;
-
-    for (auto& entry : platform::dir_entries(gensDir)) {
-        if (!entry.is_regular_file()) continue;
-        try {
-            auto content = platform::read_file_to_string(entry.path().string());
-            auto json = nlohmann::json::parse(content);
-            Generation gen;
-            gen.number  = json.value("generation", 0);
-            gen.created = json.value("created", "");
-            gen.reason  = json.value("reason", "");
-            if (json.contains("packages") && json["packages"].is_object())
-                for (auto it = json["packages"].begin(); it != json["packages"].end(); ++it)
-                    gen.packages[it.key()] = it.value().get<std::string>();
-            result.push_back(gen);
-        } catch (...) {}
-    }
-
-    std::ranges::sort(result, {}, &Generation::number);
-    return result;
-}
+export std::vector<Generation> list_generations(const fs::path& envDir);
 
 // Roll the recorded selection back to a generation, and hand it to the
 // caller to apply.
@@ -146,36 +43,7 @@ export std::vector<Generation> list_generations(const fs::path& envDir) {
 // This used to write the selection into `<envDir>/xvm/.workspace.xvm.yaml`
 // and stop. Nothing read that file, so rollback changed no version at all.
 export std::expected<std::map<std::string, std::string>, std::string>
-rollback(const fs::path& envDir, int targetGen) {
-    std::map<std::string, std::string> packages;
-
-    if (targetGen > 0) {
-        auto gensDir = envDir / "generations";
-        auto genFile = gensDir / (([](int n) { char b[8]; std::snprintf(b, sizeof(b), "%03d", n); return std::string(b); })(targetGen) + ".json");
-        if (!fs::exists(genFile)) {
-            return std::unexpected(
-                std::format("generation {} not found", targetGen));
-        }
-        try {
-            auto content = platform::read_file_to_string(genFile.string());
-            auto json = nlohmann::json::parse(content);
-            for (auto it = json["packages"].begin(); it != json["packages"].end(); ++it)
-                packages[it.key()] = it.value().get<std::string>();
-        } catch (...) {
-            return std::unexpected(
-                std::format("failed to read generation {}", targetGen));
-        }
-    }
-
-    nlohmann::json profileJson = {
-        {"current_generation", targetGen},
-        {"packages",           packages}
-    };
-    platform::write_string_to_file((envDir / ".profile.json").string(),
-                                profileJson.dump(2));
-
-    return packages;
-}
+rollback(const fs::path& envDir, int targetGen);
 
 // One subos's workspace file, as read off disk.
 //
@@ -199,37 +67,7 @@ export struct SubosSnapshot {
 // read-only inspection and reference counting, and a subos whose config a
 // user hand-edited into invalid JSON must not take down an unrelated
 // `remove`. `current` is a symlink to the active one and would double-count.
-export std::vector<SubosSnapshot> load_subos_snapshots(const fs::path& xlingsHome) {
-    std::vector<SubosSnapshot> snapshots;
-    auto subosDir = xlingsHome / "subos";
-    std::error_code ec;
-    if (!fs::is_directory(subosDir, ec)) return snapshots;
-
-    for (auto& entry : platform::dir_entries(subosDir)) {
-        std::error_code dec;
-        if (!entry.is_directory(dec)) continue;
-        auto name = entry.path().filename().string();
-        if (name == "current") continue;
-        auto wsPath = entry.path() / ".xlings.json";
-        std::error_code fec;
-        if (!fs::exists(wsPath, fec)) continue;
-        try {
-            auto content = platform::read_file_to_string(wsPath.string());
-            auto json = nlohmann::json::parse(content, nullptr, false);
-            if (json.is_discarded() || !json.is_object()) continue;
-            if (!json.contains("workspace") || !json["workspace"].is_object()) continue;
-            snapshots.push_back({
-                .name = name,
-                .dir = entry.path(),
-                .workspace = xvm::subos_workspace_from_json(json["workspace"]),
-            });
-        } catch (...) {}
-    }
-    std::ranges::sort(snapshots, [](const auto& a, const auto& b) {
-        return a.name < b.name;
-    });
-    return snapshots;
-}
+export std::vector<SubosSnapshot> load_subos_snapshots(const fs::path& xlingsHome);
 
 // Write one other subos's workspace back, preserving everything else in its
 // state file.
@@ -246,110 +84,11 @@ export std::vector<SubosSnapshot> load_subos_snapshots(const fs::path& xlingsHom
 // lock; this does not take it, because it has no way to know whether the
 // caller is mid-transaction over several files.
 export bool save_subos_workspace(const fs::path& subosRoot,
-                                 const xvm::SubosWorkspace& workspace) {
-    const auto wsPath = subosRoot / ".xlings.json";
-    nlohmann::json json = nlohmann::json::object();
-    std::error_code ec;
-    if (fs::exists(wsPath, ec)) {
-        try {
-            auto content = platform::read_file_to_string(wsPath.string());
-            auto parsed = nlohmann::json::parse(content, nullptr, false);
-            if (!parsed.is_discarded() && parsed.is_object()) {
-                json = std::move(parsed);
-            } else {
-                // Refuse rather than replace: an unreadable file is not an
-                // empty one, and overwriting it would turn "we could not read
-                // your subos" into "your subos is now blank".
-                return false;
-            }
-        } catch (...) {
-            return false;
-        }
-    }
-    json["workspace"] = xvm::subos_workspace_to_json(workspace);
-    try {
-        platform::write_string_to_file(wsPath.string(), json.dump(2));
-    } catch (...) {
-        return false;
-    }
-    return true;
-}
-
-// Build a set of referenced xpkg "dirname/version" keys from all subos workspaces
-// by mapping workspace target names to xpkg directory paths via the versions DB.
-std::set<std::string> collect_subos_references_(const fs::path& xlingsHome) {
-    std::set<std::string> referenced;
-    auto xpkgsDir = xlingsHome / "data" / "xpkgs";
-
-    // Load global versions DB
-    auto configPath = xlingsHome / ".xlings.json";
-    xvm::VersionDB globalDB;
-    if (fs::exists(configPath)) {
-        try {
-            auto content = platform::read_file_to_string(configPath.string());
-            auto json = nlohmann::json::parse(content, nullptr, false);
-            if (!json.is_discarded() && json.contains("versions"))
-                globalDB = xvm::versions_from_json(json["versions"]);
-        } catch (...) {}
-    }
-
-    // Build a map: xpkg_dir_name/version -> key, from versions DB paths
-    // e.g., "xim-x-gcc/15.1.0" from path "/home/.../.xlings/data/xpkgs/xim-x-gcc/15.1.0/bin"
-    //
-    // Pin every payload of every target name that appears in either the
-    // active or installed[] map. (The lambda is intentionally coarse:
-    // currently a target name in workspace pins ALL versions of that
-    // target; finer-grained per-version pinning is a separate
-    // refactor.) The 0.4.19 fix here is to also walk installed[] —
-    // pre-fix, a target only pinned in installed[] of some subos (e.g.
-    // after `xlings remove` cleared its active but the user kept
-    // installed[]) was eligible for GC.
-    auto add_refs_from_subos_workspace = [&](const xvm::SubosWorkspace& sws) {
-        std::set<std::string> targetNames;
-        for (auto& [target, _] : sws.active) targetNames.insert(target);
-        for (auto& [target, _] : sws.installed) targetNames.insert(target);
-        for (auto& target : targetNames) {
-            auto it = globalDB.find(target);
-            if (it == globalDB.end()) continue;
-            for (auto& [verKey, vdata] : it->second.versions) {
-                if (vdata.path.empty()) continue;
-                // Extract xpkg dir from path: .../xpkgs/<dirname>/<version>/...
-                auto xpkgsPos = vdata.path.find("xpkgs/");
-                if (xpkgsPos == std::string::npos) continue;
-                auto rel = vdata.path.substr(xpkgsPos + 6); // after "xpkgs/"
-                // rel is like "xim-x-gcc/15.1.0/bin" or "xim-x-gcc/15.1.0"
-                // Extract first two path components: dirname/version
-                auto slash1 = rel.find('/');
-                if (slash1 == std::string::npos) continue;
-                auto slash2 = rel.find('/', slash1 + 1);
-                auto dirAndVer = (slash2 != std::string::npos)
-                    ? rel.substr(0, slash2)
-                    : rel;
-                referenced.insert(dirAndVer);
-            }
-        }
-    };
-
-    // Scan all subos workspace files
-    for (auto& snapshot : load_subos_snapshots(xlingsHome)) {
-        add_refs_from_subos_workspace(snapshot.workspace);
-    }
-
-    return referenced;
-}
+                                 const xvm::SubosWorkspace& workspace);
 
 // Find which subos environments reference a given package target name.
 export std::vector<std::string> find_subos_referencing(
-        const fs::path& xlingsHome, const std::string& target) {
-    std::vector<std::string> result;
-    for (auto& snapshot : load_subos_snapshots(xlingsHome)) {
-        if (snapshot.workspace.active.contains(target)
-            || snapshot.workspace.installed.contains(target)) {
-            result.push_back(snapshot.name);
-        }
-    }
-    return result;
-}
+        const fs::path& xlingsHome, const std::string& target);
 
 // Which subos still pin an EXACT version of a target.
 //
@@ -368,80 +107,8 @@ export std::vector<std::string> find_subos_referencing(
 export std::vector<std::string> find_subos_pinning_version(
         const fs::path& xlingsHome,
         const std::string& target,
-        const std::string& version) {
-    auto matches = [&](std::string_view stored) {
-        return stored == version
-            || xvm::strip_namespace(std::string(stored)) == version;
-    };
-
-    std::vector<std::string> result;
-    for (auto& snapshot : load_subos_snapshots(xlingsHome)) {
-        const auto& ws = snapshot.workspace;
-        bool pinned = false;
-        if (auto it = ws.active.find(target);
-            it != ws.active.end() && matches(it->second)) {
-            pinned = true;
-        }
-        if (!pinned) {
-            // installed[] pins the payload just as hard as active does — a
-            // subos that opted into the version but is not currently using it
-            // still breaks if the payload goes.
-            if (auto it = ws.installed.find(target); it != ws.installed.end()) {
-                for (auto& v : it->second) {
-                    if (matches(v)) { pinned = true; break; }
-                }
-            }
-        }
-        if (pinned) result.push_back(snapshot.name);
-    }
-    return result;
-}
-
-export int gc(const fs::path& xlingsHome, bool dryRun = false) {
-    auto referenced = collect_subos_references_(xlingsHome);
-
-    auto pkgDir = xlingsHome / "data" / "xpkgs";
-    if (!fs::exists(pkgDir)) {
-        std::println("[xlings:store] xpkgs not found, nothing to gc");
-        return 0;
-    }
-
-    std::uintmax_t freedBytes = 0;
-    int removedCount = 0;
-
-    for (auto& pkgEntry : platform::dir_entries(pkgDir)) {
-        if (!pkgEntry.is_directory()) continue;
-        auto pkgName = pkgEntry.path().filename().string();
-        for (auto& verEntry : platform::dir_entries(pkgEntry)) {
-            if (!verEntry.is_directory()) continue;
-            auto ver = verEntry.path().filename().string();
-            auto key = pkgName + "/" + ver;
-            if (!referenced.count(key)) {
-                auto size = dir_size_(verEntry.path());
-                if (dryRun) {
-                    auto mb = static_cast<int>(static_cast<double>(size) / 1e5) / 10.0;
-                    std::println("  would remove xpkgs/{}/{} ({} MB)", pkgName, ver, mb);
-                } else {
-                    std::error_code ec;
-                    fs::remove_all(verEntry.path(), ec);
-                    if (!ec)
-                        std::println("[xlings:store] removed xpkgs/{}/{}", pkgName, ver);
-                }
-                freedBytes += size;
-                ++removedCount;
-            }
-        }
-    }
+        const std::string& version);
 
-    auto totalMb = static_cast<int>(static_cast<double>(freedBytes) / 1e5) / 10.0;
-    if (dryRun) {
-        std::println("[xlings:store] gc dry-run: {} packages, {} MB would be freed",
-            removedCount, totalMb);
-    } else {
-        std::println("[xlings:store] gc: {} packages removed, {} MB freed",
-            removedCount, totalMb);
-    }
-    return 0;
-}
+export int gc(const fs::path& xlingsHome, bool dryRun = false);
 
 } // namespace xlings::profile
diff --git a/src/core/semver.cpp b/src/core/semver.cpp
new file mode 100644
index 00000000..7fbe99e4
--- /dev/null
+++ b/src/core/semver.cpp
@@ -0,0 +1,16 @@
+module;
+
+module xlings.core.semver;
+
+import std;
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::semver {
+
+Segment Segment::number(unsigned long long v) { return {true, v, {}}; }
+
+Segment Segment::alpha(std::string t) { return {false, 0, std::move(t)}; }
+
+} // namespace xlings::semver
diff --git a/src/core/semver.cppm b/src/core/semver.cppm
index 41c41b0b..9c6def56 100644
--- a/src/core/semver.cppm
+++ b/src/core/semver.cppm
@@ -51,8 +51,8 @@ struct Segment {
     unsigned long long num = 0;
     std::string text;         // alpha segments only
 
-    static Segment number(unsigned long long v) { return {true, v, {}}; }
-    static Segment alpha(std::string t) { return {false, 0, std::move(t)}; }
+    static Segment number(unsigned long long v);
+    static Segment alpha(std::string t);
 };
 
 struct Version {
diff --git a/src/core/subos.cpp b/src/core/subos.cpp
new file mode 100644
index 00000000..93ec2781
--- /dev/null
+++ b/src/core/subos.cpp
@@ -0,0 +1,1681 @@
+module;
+
+// System headers used by use_spawn_shell only. `import std;` doesn't
+// pull these in, and we want execl/errno (POSIX) or CreateProcess
+// (Win32) without #include in the named-module purview (which the
+// standard forbids for headers that aren't importable units).
+#include <cstdio>  // stderr (used by std::println(stderr, ...))
+#if defined(_WIN32)
+#define WIN32_LEAN_AND_MEAN
+// windows.h defines `min`/`max` as function-like macros, which turns any
+// `std::min({a, b, c})` in this module into "too many arguments provided to
+// function-like macro invocation" -- an error that names the call site and
+// says nothing about where the macro came from. Every other module here that
+// includes windows.h already defines this (platform.cppm, platform/windows.cppm,
+// platform/target.cppm); this one was the exception, and it cost four
+// consecutive red Windows runs.
+#define NOMINMAX
+#include <windows.h>
+#else
+#include <cerrno>
+#include <cstring>
+#include <unistd.h>
+#include <sys/wait.h>
+#endif
+
+module xlings.core.subos;
+
+import std;
+import xlings.core.config;
+import xlings.core.home_config;
+import xlings.libs.json;
+import xlings.core.log;
+import xlings.platform;
+import xlings.runtime;
+import xlings.core.utils;
+import xlings.core.xself;
+import xlings.core.xim.commands;
+import xlings.core.subos.keeper;
+import xlings.core.subos.gpu;
+import xlings.core.subos.graphics;
+import xlings.core.subos.sandbox;
+import xlings.core.subos.manifest;
+import xlings.cli.spec;
+
+namespace xlings::subos {
+
+nlohmann::json read_config_json_(const fs::path& path) {
+    if (!fs::exists(path)) return nlohmann::json::object();
+    try {
+        auto content = platform::read_file_to_string(path.string());
+        auto json = nlohmann::json::parse(content, nullptr, false);
+        return json.is_discarded() ? nlohmann::json::object() : json;
+    } catch (...) { return nlohmann::json::object(); }
+}
+
+void write_config_json_(const fs::path& path, const nlohmann::json& json) {
+    platform::write_string_to_file(path.string(), json.dump(2));
+}
+
+SubosInfo candidate_info_(const std::string& name, bool includeToolCount) {
+    auto& p = Config::paths();
+    auto dir = Config::subos_dir(name);
+    int toolCount = 0;
+    auto binDir = dir / "bin";
+    if (includeToolCount && fs::exists(binDir)) {
+        for (auto& e : platform::dir_entries(binDir)) {
+            auto stem = e.path().stem().string();
+            if (!xself::is_builtin_shim(stem) && stem != "xvm-alias")
+                ++toolCount;
+        }
+    }
+    return {name, dir, p.activeSubos == name, toolCount};
+}
+
+SubosCandidateView candidate_view(bool includeToolCount) {
+    auto& p = Config::paths();
+    auto json = read_config_json_(p.homeDir / ".xlings.json");
+    SubosCandidateView view;
+    bool hasDefault = false;
+
+    if (json.contains("subos") && json["subos"].is_object()) {
+        for (auto it = json["subos"].begin(); it != json["subos"].end(); ++it) {
+            auto name = it.key();
+            hasDefault = hasDefault || name == "default";
+            view.candidates.push_back(candidate_info_(name, includeToolCount));
+        }
+    }
+
+    // Bounded compatibility for homes created before the registry existed.
+    // Only the well-known default manifest is synthesized. Arbitrary
+    // directories are never promoted into environments by a read-only query.
+    std::error_code ec;
+    const auto defaultManifest =
+        Config::subos_dir("default") / ".xlings.json";
+    if (!hasDefault && fs::is_regular_file(defaultManifest, ec)) {
+        view.candidates.push_back(
+            candidate_info_("default", includeToolCount));
+    }
+
+    std::ranges::sort(view.candidates, {}, &SubosInfo::name);
+    return view;
+}
+
+std::vector<SubosInfo> list_all() {
+    return candidate_view().candidates;
+}
+
+std::string lowercase_name_(std::string_view name) {
+    std::string lowered(name);
+    for (auto& ch : lowered) {
+        if (ch >= 'A' && ch <= 'Z') ch = static_cast<char>(ch - 'A' + 'a');
+    }
+    return lowered;
+}
+
+std::size_t edit_distance_(std::string_view lhs, std::string_view rhs) {
+    std::vector<std::size_t> prev(rhs.size() + 1);
+    std::vector<std::size_t> next(rhs.size() + 1);
+    std::iota(prev.begin(), prev.end(), std::size_t{0});
+    for (std::size_t i = 0; i < lhs.size(); ++i) {
+        next[0] = i + 1;
+        for (std::size_t j = 0; j < rhs.size(); ++j) {
+            const auto replace = prev[j] + (lhs[i] == rhs[j] ? 0u : 1u);
+            next[j + 1] = std::min({prev[j + 1] + 1, next[j] + 1, replace});
+        }
+        std::swap(prev, next);
+    }
+    return prev.back();
+}
+
+std::vector<SubosInfo> suggestions_(
+        std::string_view query,
+        std::span<const SubosInfo> candidates) {
+    struct Scored {
+        int substringRank;
+        std::size_t distance;
+        SubosInfo candidate;
+    };
+    const auto loweredQuery = lowercase_name_(query);
+    std::vector<Scored> scored;
+    scored.reserve(candidates.size());
+    for (const auto& candidate : candidates) {
+        const auto lowered = lowercase_name_(candidate.name);
+        const bool related = lowered.contains(loweredQuery)
+            || loweredQuery.contains(lowered);
+        scored.push_back({related ? 0 : 1,
+                          edit_distance_(loweredQuery, lowered), candidate});
+    }
+    std::ranges::sort(scored, [](const auto& lhs, const auto& rhs) {
+        return std::tie(lhs.substringRank, lhs.distance, lhs.candidate.name)
+             < std::tie(rhs.substringRank, rhs.distance, rhs.candidate.name);
+    });
+    std::vector<SubosInfo> result;
+    for (std::size_t i = 0; i < std::min<std::size_t>(3, scored.size()); ++i) {
+        result.push_back(std::move(scored[i].candidate));
+    }
+    return result;
+}
+
+CandidateResolution_ resolve_candidate_(std::string_view query) {
+    auto all = candidate_view(false).candidates;
+    if (query.empty()) {
+        return {.reason = "missing_name", .candidates = std::move(all)};
+    }
+
+    if (auto exact = std::ranges::find(all, query, &SubosInfo::name);
+        exact != all.end()) {
+        return {.selected = exact->name,
+                .reason = "exact",
+                .candidates = {*exact}};
+    }
+
+    const auto loweredQuery = lowercase_name_(query);
+    std::vector<SubosInfo> matches;
+    for (const auto& candidate : all) {
+        if (lowercase_name_(candidate.name) == loweredQuery) {
+            matches.push_back(candidate);
+        }
+    }
+    if (matches.size() == 1) {
+        return {.selected = matches.front().name,
+                .reason = "case_insensitive_exact",
+                .candidates = std::move(matches),
+                .autoSelected = true};
+    }
+    if (matches.size() > 1) {
+        return {.reason = "ambiguous", .candidates = std::move(matches)};
+    }
+
+    for (const auto& candidate : all) {
+        if (lowercase_name_(candidate.name).starts_with(loweredQuery)) {
+            matches.push_back(candidate);
+        }
+    }
+    if (matches.size() == 1) {
+        return {.selected = matches.front().name,
+                .reason = "unique_prefix",
+                .candidates = std::move(matches),
+                .autoSelected = true};
+    }
+    if (matches.size() > 1) {
+        return {.reason = "ambiguous", .candidates = std::move(matches)};
+    }
+
+    return {.reason = "not_found",
+            .candidates = suggestions_(query, all)};
+}
+
+void emit_candidates_(EventStream& stream,
+                      const CandidateResolution_& resolution,
+                      std::string_view query,
+                      std::string_view hint = {}) {
+    nlohmann::json candidates = nlohmann::json::array();
+    for (const auto& candidate : resolution.candidates) {
+        candidates.push_back({
+            {"name", candidate.name},
+            {"active", candidate.isActive},
+            {"dir", candidate.dir.string()},
+            {"pkgCount", candidate.toolCount},
+        });
+    }
+    nlohmann::json payload;
+    payload["reason"] = resolution.reason;
+    payload["query"] = query;
+    payload["candidates"] = std::move(candidates);
+    payload["auto_selected"] = resolution.autoSelected;
+    if (!resolution.selected.empty()) payload["selected"] = resolution.selected;
+    if (!hint.empty()) payload["hint"] = hint;
+    stream.emit(DataEvent{"subos_candidates", payload.dump()});
+}
+
+UseNameResolution_ resolve_use_name_(std::string_view query,
+                                    EventStream& stream) {
+    auto resolution = resolve_candidate_(query);
+    if (query.empty()) {
+        const auto hint = resolution.candidates.empty()
+            ? "Create: xlings subos new <name>"
+            : "Use: xlings subos use <name>";
+        emit_candidates_(stream, resolution, query, hint);
+        return {};
+    }
+    if (!resolution.selected.empty()) {
+        if (resolution.autoSelected) {
+            emit_candidates_(stream, resolution, query);
+        }
+        return {.selected = std::move(resolution.selected)};
+    }
+    if (resolution.reason == "ambiguous") {
+        emit_candidates_(stream, resolution, query);
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = std::format("subos name '{}' is ambiguous", query),
+            .recoverable = true,
+            .hint = "use one of the exact names listed above",
+        });
+        return {.exitCode = 2};
+    }
+
+    emit_candidates_(stream, resolution, query);
+    std::string nearest;
+    for (const auto& candidate : resolution.candidates) {
+        if (!nearest.empty()) nearest += ", ";
+        nearest += candidate.name;
+    }
+    stream.emit(ErrorEvent{
+        .code = ErrorCode::NotFound,
+        .message = std::format("subos '{}' not found", query),
+        .recoverable = true,
+        .hint = nearest.empty()
+            ? "create it first: xlings subos new " + std::string(query)
+            : "did you mean: " + nearest,
+    });
+    return {.exitCode = 1};
+}
+
+void update_current_symlink_(EventStream& stream,
+                              const fs::path& homeDir,
+                              const fs::path& targetDir) {
+    auto linkPath = homeDir / "subos" / "current";
+    std::error_code ec;
+    fs::remove(linkPath, ec);
+    // The same helper `self init` uses to create this link, rather than
+    // `fs::create_directory_symlink` directly. On Windows a symlink needs
+    // developer mode or elevation and a junction does not, so the two spellings
+    // disagree exactly there: init would lay down a junction and every later
+    // switch would fail to replace it, leaving `subos/current` pointing at
+    // whatever was active the day the home was created -- while `subos list`
+    // reported the switch as done.
+    if (!platform::create_directory_link(linkPath, targetDir)) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::Permission,
+            .message = std::format("failed to update current symlink: {}",
+                                   Config::display_path(linkPath)),
+            .recoverable = true,
+        });
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Sandbox subos helpers (0.4.23 V4 — see .agents/docs/sandbox-v4-design.md)
+//
+// V4 model: sandbox is NOT a creation property of subos. It's a `use`
+// modifier — `xlings subos use <name> --sandbox` enters the same subos
+// via proot fs-isolation, with sandbox-private $HOME / /tmp / /etc and
+// host-shared ~/.xlings / /usr / /lib*. Real user identity (no fake
+// root). Shell is whatever $SHELL is. Prompt switches from
+// `[xsubos:<name>]` to `<xsubos:<name>>` to signal sandbox mode.
+//
+// Helpers here:
+//   - sandbox::init_sandbox_dirs_ — lazy-init the per-subos
+//     sandbox dirs (<subos>/{home/<user>, tmp, etc/...}) at first
+//     `subos use --sandbox`. Idempotent.
+//   - sandbox::locate_proot_ — search for the proot binary
+//     (defined later, alongside build_proot_argv_).
+//   - sandbox::build_proot_argv_ — assemble the proot CLI for
+//     entering the sandbox (defined later).
+//
+// Note: V1.1-V1.3 (`--sandbox-shell <xpkg>`, `sandbox-shell` /
+// `sandbox-shell-xpkg` config fields, eager shell install at
+// create-time) was removed in V4. Old sandboxes still in user homes
+// retain those fields; V4 silently ignores them, and `subos use
+// --sandbox` works on them because init_sandbox_dirs_ is idempotent.
+// ─────────────────────────────────────────────────────────────────────
+
+
+// Give a subos directory a `subos_info` block, or leave the one it has.
+//
+// Idempotent, and called from every path that produces a subos directory
+// (create, new_from, and the migration of a subos made before this block
+// existed). A subos without it violates invariant I4 and cannot be described,
+// checked or entered with its environment.
+//
+// The block is added even when `.xlings.json` already exists, which is the
+// difference from the surrounding code: the file predates the block, so
+// "the file is there" does not mean "the subos describes itself".
+bool ensure_subos_info_(const fs::path& dir, std::string_view runtime) {
+    auto json = read_config_json_(dir / ".xlings.json");
+    if (!json.is_object()) json = nlohmann::json::object();
+    if (!json.contains("workspace")) json["workspace"] = nlohmann::json::object();
+
+    // Only replace a block that is absent or unusable. Rewriting a valid one
+    // would discard the envs a package declared into it.
+    if (manifest::validate_block(json).empty()) return true;
+
+    // An unusable block can still carry a valid runtime binding, and that
+    // binding — not the caller's fallback — is what the subos was declared
+    // against. preserved_runtime keeps it through the rebuild.
+    json[std::string(manifest::BLOCK)] = manifest::make_block(
+        manifest::preserved_runtime(json, runtime),
+        std::format("xlings {}", Info::VERSION),
+        platform::host_glibc_version());
+    try {
+        write_config_json_(dir / ".xlings.json", json);
+    } catch (const std::exception& e) {
+        log::error("failed to write subos manifest {}: {}",
+                   (dir / ".xlings.json").string(), e.what());
+        return false;
+    }
+    return true;
+}
+
+int create(const std::string& name, const fs::path& customDir,
+                  sandbox::StorageMode storage, const std::string& imageSize,
+                  const std::string& runtime,
+                  EventStream& stream) {
+    auto& p = Config::paths();
+
+    if (name == "current") {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = "'current' is a reserved subos name",
+            .recoverable = false,
+        });
+        return 1;
+    }
+
+    // Checked before anything is laid down. A malformed runtime that only
+    // surfaced at write time would leave a registered subos that cannot
+    // satisfy its own invariants.
+    const std::string effectiveRuntime =
+        runtime.empty() ? std::string(manifest::DEFAULT_RUNTIME) : runtime;
+    if (!manifest::is_binding(effectiveRuntime)) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = "invalid --runtime '" + effectiveRuntime
+                       + "' (expected <package>@<version>, e.g. glibc@2.39)",
+            .recoverable = false,
+        });
+        return 1;
+    }
+
+    for (char c : name) {
+        if (!std::isalnum(static_cast<unsigned char>(c)) && c != '_' && c != '-') {
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::InvalidInput,
+                .message = "invalid subos name: '" + name
+                           + "' (allowed: alphanumeric, underscore, dash)",
+                .recoverable = false,
+            });
+            return 1;
+        }
+    }
+
+    // Cheap pre-check so the common "already exists" mistake fails before we
+    // lay down directories or run mkfs. It is advisory only -- the binding
+    // check that actually decides is the one inside the locked commit below.
+    if (read_home_config(p.homeDir).value("subos", nlohmann::json::object())
+            .contains(name)) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = "subos '" + name + "' already exists",
+            .recoverable = false,
+        });
+        return 1;
+    }
+
+    auto dir = customDir.empty() ? (p.homeDir / "subos" / name) : customDir;
+
+    fs::create_directories(dir / "bin");
+    fs::create_directories(dir / "lib");
+    fs::create_directories(dir / "usr");
+    fs::create_directories(dir / "generations");
+
+    auto subosConfig = dir / ".xlings.json";
+    if (!fs::exists(subosConfig)) {
+        nlohmann::json j;
+        j["workspace"] = nlohmann::json::object();
+        if (storage != sandbox::StorageMode::Shared)
+            j["storage"] = sandbox::storage_to_string_(storage);
+        if (storage == sandbox::StorageMode::Image)
+            j["imageSize"] = imageSize;
+        j[std::string(manifest::BLOCK)] = manifest::make_block(
+            effectiveRuntime, std::format("xlings {}", Info::VERSION),
+            platform::host_glibc_version());
+        write_config_json_(subosConfig, j);
+    } else if (!ensure_subos_info_(dir, effectiveRuntime)) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::Internal,
+            .message = "failed to write the subos manifest for '" + name + "'",
+            .recoverable = false,
+            .hint = "check write permission on " + subosConfig.string(),
+        });
+        return 1;
+    }
+
+    // Image mode: create sparse ext4 image
+    if (storage == sandbox::StorageMode::Image) {
+        auto rc = sandbox::init_image_(dir / "home.img", imageSize);
+        if (rc != 0) {
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::Internal,
+                .message = "failed to create home.img",
+                .recoverable = false,
+                .hint = "ensure mkfs.ext4 is available (e2fsprogs)",
+            });
+            return 1;
+        }
+        fs::create_directories(dir / ".mountpoint");
+    }
+
+    // Create shim hardlinks from xlings binary
+    auto xlingsBin = p.homeDir / "xlings";
+    if (!fs::exists(xlingsBin))
+        xlingsBin = p.homeDir / "bin" / "xlings";
+    if (fs::exists(xlingsBin)) {
+        if (xself::ensure_subos_shims(dir / "bin", xlingsBin, p.homeDir) != 0) {
+            log::warn("some shims could not be written into {}; commands may "
+                      "not resolve inside this subos", (dir / "bin").string());
+        }
+    }
+
+    // Everything above this point -- mkfs.ext4 for image storage in
+    // particular -- can take seconds. Reading the config before it and
+    // writing it after would put back a document that predates any install
+    // that finished meanwhile. Re-read under the lock and edit only our key.
+    bool raced = false;
+    auto committed = update_home_config(p.homeDir, [&](nlohmann::json& json) {
+        if (!json.contains("subos") || !json["subos"].is_object()) {
+            json["subos"] = nlohmann::json::object();
+        }
+        if (json["subos"].contains(name)) {
+            raced = true;
+            return false;
+        }
+        json["subos"][name] =
+            {{"dir", customDir.empty() ? "" : customDir.string()}};
+        return true;
+    });
+    if (!committed) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::Internal,
+            .message = "subos '" + name + "' was created on disk but could "
+                       "not be recorded: " + committed.error(),
+            .recoverable = true,
+            .hint = "retry once the other xlings finishes; the directory at "
+                    + dir.string() + " is reused as-is",
+        });
+        return 1;
+    }
+    if (raced) {
+        // Another xlings registered this name while we were building. Its
+        // entry is the one on disk; ours would overwrite a directory the
+        // other command is using.
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = "subos '" + name + "' already exists",
+            .recoverable = false,
+        });
+        return 1;
+    }
+
+    // The subos is registered; check it can actually satisfy the invariants
+    // before saying so. A creation that reports success and leaves a subos
+    // that doctor immediately condemns is the failure mode this whole slice
+    // exists to remove -- "it happened" and "it worked" must not look alike.
+    if (auto findings = manifest::validate(dir); !findings.empty()) {
+        std::string detail;
+        for (const auto& f : findings) {
+            if (!detail.empty()) detail += "; ";
+            detail += std::string(manifest::describe(f.kind));
+            if (!f.detail.empty()) detail += " (" + f.detail + ")";
+        }
+        // Roll back to the state before the command: the registry entry first,
+        // since that is what makes the name unusable a second time.
+        (void)update_home_config(p.homeDir, [&](nlohmann::json& json) {
+            if (json.contains("subos") && json["subos"].is_object())
+                json["subos"].erase(name);
+            return true;
+        });
+        std::error_code rmec;
+        fs::remove_all(dir, rmec);
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::Internal,
+            .message = "subos '" + name + "' did not come out valid: " + detail,
+            .recoverable = false,
+            .hint = rmec
+                ? "rolled back the registry entry, but " + dir.string()
+                  + " could not be removed -- delete it before retrying"
+                : "nothing was left behind; retry, or report this",
+        });
+        return 1;
+    }
+
+    // A declared runtime is installed, not merely recorded.
+    //
+    // `--runtime glibc@2.39` names what this subos runs on. Writing it to the
+    // manifest and stopping there leaves the subos empty, and the first
+    // package to arrive decides the actual glibc — a subos declaring 2.39 ends
+    // up on 2.44 because something's `>=2.38` resolved higher. The flag then
+    // describes an intention the subos does not hold, which is worse than not
+    // having the flag: it reads as a guarantee.
+    //
+    // Only when asked. `subos new` without --runtime stays what it was, a
+    // local directory operation that cannot fail on a network — the default
+    // subos that `self install` creates goes through that path.
+    if (!runtime.empty()) {
+        // Both, and that is not belt-and-braces. The override is what
+        // recomputes Config's cached paths, and XLINGS_ACTIVE_SUBOS is what
+        // the activation path re-reads for itself. Setting only the override
+        // put the payload in the right subos and then reported
+        // "'glibc' is not installed in this subos" from the reader that had
+        // not been told — a command that succeeds narrating a failure.
+        auto prevEnv = utils::get_env_or_default("XLINGS_ACTIVE_SUBOS");
+        platform::set_env_variable("XLINGS_ACTIVE_SUBOS", name);
+        auto prev = Config::set_active_subos_override(name);
+        std::vector<std::string> targets{effectiveRuntime};
+        // useAfterInstall stays FALSE. The payload is usually already in the
+        // store — another subos has it — so cmd_install takes its
+        // "already installed" path, and the activation that flag triggers
+        // runs before the registration for THIS subos has landed. It fails,
+        // prints three [error] lines and a [warn], and the subos ends up
+        // correct anyway. A command that succeeds must not narrate a failure.
+        const int rc = xim::cmd_install(targets, /*yes=*/true,
+                                        /*noDeps=*/false, stream);
+        (void)Config::set_active_subos_override(prev);
+        platform::set_env_variable("XLINGS_ACTIVE_SUBOS", prevEnv);
+        if (rc != 0) {
+            // The subos exists and is valid; it just does not have what it
+            // says it runs on. Reported rather than rolled back, because the
+            // directory is usable and deleting it would throw away a
+            // successful create over a failed download.
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::Internal,
+                .message = "subos '" + name + "' was created but its declared "
+                           "runtime " + effectiveRuntime
+                           + " could not be installed",
+                .recoverable = true,
+                .hint = "run: xlings subos use " + name
+                        + " && xlings install " + effectiveRuntime,
+            });
+            return rc;
+        }
+    }
+
+    nlohmann::json payload;
+    payload["name"] = name;
+    payload["dir"]  = dir.string();
+    payload["storage"] = sandbox::storage_to_string_(storage);
+    payload["runtime"] = effectiveRuntime;
+    stream.emit(DataEvent{"subos_created", payload.dump()});
+    return 0;
+}
+
+int create(const std::string& name, const fs::path& customDir,
+                  sandbox::StorageMode storage, const std::string& imageSize,
+                  EventStream& stream) {
+    return create(name, customDir, storage, imageSize, "", stream);
+}
+
+int create(const std::string& name, const fs::path& customDir,
+                  EventStream& stream) {
+    return create(name, customDir, sandbox::StorageMode::Shared, "50G", "", stream);
+}
+
+namespace new_from_detail_ {
+
+bool is_pkg_spec_(const std::string& spec) {
+    return spec.find(':') != std::string::npos || spec.find('@') != std::string::npos;
+}
+
+PkgRef parse_pkg_spec_(const std::string& spec) {
+    PkgRef r;
+    std::string rest = spec;
+    if (auto colon = rest.find(':'); colon != std::string::npos) {
+        r.ns = rest.substr(0, colon);
+        rest = rest.substr(colon + 1);
+    }
+    if (auto at = rest.find('@'); at != std::string::npos) {
+        r.name = rest.substr(0, at);
+        r.ver  = rest.substr(at + 1);
+    } else {
+        r.name = rest;
+    }
+    return r;
+}
+
+// Recursive directory copy with reflink/clonefile preferred where the
+// filesystem supports COW. Falls back to full byte-copy. Excludes the
+// caller's xlings binary shims (those are minted fresh in the target).
+int copy_tree_(const fs::path& src, const fs::path& dst,
+               EventStream& stream) {
+    std::error_code ec;
+    fs::create_directories(dst, ec);
+    if (ec) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::Internal,
+            .message = "failed to create fork target dir: " + ec.message(),
+            .recoverable = false,
+        });
+        return 1;
+    }
+
+    // Use the system cp with reflink/clonefile flags; falls back to
+    // full copy when the FS doesn't support it. Skip the bin/ subtree
+    // here — shims are regenerated below.
+    std::string copy_cmd;
+#if defined(__linux__)
+    // cp -a preserves mode/ownership/timestamps; --reflink=auto uses
+    // COW where available (btrfs/xfs) and full copy otherwise.
+    copy_cmd = std::format(
+        "cp -a --reflink=auto '{}/.' '{}/'", src.string(), dst.string());
+#elif defined(__APPLE__)
+    // APFS clonefile via /bin/cp -c
+    copy_cmd = std::format("cp -ac '{}/.' '{}/'", src.string(), dst.string());
+#endif
+
+    if (!copy_cmd.empty()) {
+        auto rc = std::system(copy_cmd.c_str());
+        if (rc != 0) {
+            log::warn("cp -a/--reflink failed (rc={}), falling back to "
+                      "std::filesystem::copy", rc);
+            fs::copy(src, dst,
+                     fs::copy_options::recursive |
+                     fs::copy_options::overwrite_existing |
+                     fs::copy_options::copy_symlinks, ec);
+            if (ec) {
+                stream.emit(ErrorEvent{
+                    .code = ErrorCode::Internal,
+                    .message = "fork copy failed: " + ec.message(),
+                    .recoverable = false,
+                });
+                return 1;
+            }
+        }
+    } else {
+        // Windows / generic
+        fs::copy(src, dst,
+                 fs::copy_options::recursive |
+                 fs::copy_options::overwrite_existing |
+                 fs::copy_options::copy_symlinks, ec);
+        if (ec) {
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::Internal,
+                .message = "fork copy failed: " + ec.message(),
+                .recoverable = false,
+            });
+            return 1;
+        }
+    }
+    return 0;
+}
+
+// Locate xpkgs/<ns>-x-<name>/<ver>/ for a parsed pkg ref. Returns empty
+// path if no matching install exists.
+fs::path locate_base_pkg_(const PkgRef& ref) {
+    auto& p = Config::paths();
+    auto storeName = ref.ns.empty() ? ref.name : (ref.ns + "-x-" + ref.name);
+    auto base = p.dataDir / "xpkgs" / storeName;
+    if (!fs::is_directory(base)) return {};
+
+    // Specific version requested
+    if (!ref.ver.empty()) {
+        auto candidate = base / ref.ver;
+        return fs::is_directory(candidate) ? candidate : fs::path{};
+    }
+
+    // No version → take the highest-sorted installed version directory.
+    fs::path latest;
+    std::error_code ec;
+    for (auto it = fs::directory_iterator(base, ec);
+         !ec && it != std::default_sentinel; it.increment(ec)) {
+        if (it->is_directory(ec)) latest = it->path();
+    }
+    return latest;
+}
+
+}
+
+int new_from(const std::string& name, const fs::path& customDir,
+                    sandbox::StorageMode storage, const std::string& imageSize,
+                    const std::string& fromSpec, const std::string& runtime,
+                    EventStream& stream) {
+    auto& p = Config::paths();
+
+    fs::path baseDir;
+
+    if (new_from_detail_::is_pkg_spec_(fromSpec)) {
+        // ── pkg-spec path: locate or install the base xpkg ────────────
+        auto ref = new_from_detail_::parse_pkg_spec_(fromSpec);
+        baseDir = new_from_detail_::locate_base_pkg_(ref);
+
+        if (baseDir.empty()) {
+            // Auto-install (E5a): invoke `xlings install <spec>` so the
+            // base lands at xpkgs/<ns>-x-<name>/<ver>/. We use the host
+            // xlings binary (same process binary) so the install runs
+            // with the same context (XLINGS_HOME, mirror config, etc.).
+            log::info("base subos pkg '{}' not installed; auto-installing...",
+                      fromSpec);
+            auto xlings_bin = p.homeDir / "xlings";
+            if (!fs::exists(xlings_bin))
+                xlings_bin = p.homeDir / "bin" / "xlings";
+
+            auto cmd = std::format("{} install -y {}",
+                                   xlings_bin.string(), fromSpec);
+            auto rc = std::system(cmd.c_str());
+            if (rc != 0) {
+                stream.emit(ErrorEvent{
+                    .code = ErrorCode::Internal,
+                    .message = "auto-install of base '" + fromSpec
+                               + "' failed",
+                    .recoverable = true,
+                    .hint = "run manually: xlings install " + fromSpec,
+                });
+                return 1;
+            }
+            baseDir = new_from_detail_::locate_base_pkg_(ref);
+        }
+
+        if (baseDir.empty()) {
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::NotFound,
+                .message = "couldn't locate base pkg payload for '" + fromSpec
+                           + "' after install",
+                .recoverable = false,
+            });
+            return 1;
+        }
+    } else {
+        // ── local fork path: source is an existing subos by name ──────
+        baseDir = p.homeDir / "subos" / fromSpec;
+        if (!fs::is_directory(baseDir)) {
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::NotFound,
+                .message = "source subos '" + fromSpec + "' not found",
+                .recoverable = true,
+                .hint = "list available: xlings subos list",
+            });
+            return 1;
+        }
+    }
+
+    // Validate base shape: must contain .xlings.json for fork to make sense
+    if (!fs::is_regular_file(baseDir / ".xlings.json")) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = "source '" + fromSpec
+                       + "' has no .xlings.json (not a valid fork source)",
+            .recoverable = false,
+        });
+        return 1;
+    }
+
+    // Create target subos via standard `create`. This sets up
+    // bin/lib/usr/generations, writes initial .xlings.json, optionally
+    // creates home.img, and registers the subos.
+    if (auto rc = create(name, customDir, storage, imageSize, runtime, stream);
+        rc != 0) {
+        return rc;
+    }
+
+    auto dstDir = customDir.empty() ? (p.homeDir / "subos" / name) : customDir;
+
+    // Overlay base content on top — workspace (.xlings.json), any
+    // templates/static files. We re-issue create()'s file writes
+    // afterwards for storage/imageSize keys so the new subos's own
+    // storage choice wins over the base's. The base's .xlings.json
+    // workspace map is the data we want to inherit.
+    if (auto rc = new_from_detail_::copy_tree_(baseDir, dstDir, stream); rc != 0) {
+        return rc;
+    }
+
+    // Restore storage/imageSize fields in target's .xlings.json since
+    // copy_tree_ overwrote it with base's version (base usually has no
+    // explicit storage key — it inherits at fork time).
+    auto subosCfgPath = dstDir / ".xlings.json";
+    auto subosCfg = read_config_json_(subosCfgPath);
+    if (storage != sandbox::StorageMode::Shared)
+        subosCfg["storage"] = sandbox::storage_to_string_(storage);
+    else
+        subosCfg.erase("storage");
+    if (storage == sandbox::StorageMode::Image)
+        subosCfg["imageSize"] = imageSize;
+    else
+        subosCfg.erase("imageSize");
+    // Same restoration, same reason. copy_tree_ replaced the manifest create()
+    // wrote with the base's, and a base built before subos_info existed has
+    // none -- which would leave the fork registered and failing its own
+    // invariants. A base that does carry one keeps it: it describes the very
+    // content that was just copied in, envs included.
+    if (!subosCfg.contains("workspace"))
+        subosCfg["workspace"] = nlohmann::json::object();
+    if (!manifest::validate_block(subosCfg).empty()) {
+        subosCfg[std::string(manifest::BLOCK)] = manifest::make_block(
+            manifest::preserved_runtime(
+                subosCfg,
+                runtime.empty() ? manifest::DEFAULT_RUNTIME : runtime),
+            std::format("xlings {}", Info::VERSION),
+            platform::host_glibc_version());
+    }
+    write_config_json_(subosCfgPath, subosCfg);
+
+    // Re-mint subos shims (they may have been clobbered by copy_tree_
+    // if base happened to ship its own bin/ — defensive).
+    auto xlingsBin = p.homeDir / "xlings";
+    if (!fs::exists(xlingsBin))
+        xlingsBin = p.homeDir / "bin" / "xlings";
+    if (fs::exists(xlingsBin)) {
+        if (xself::ensure_subos_shims(dstDir / "bin", xlingsBin, p.homeDir) != 0) {
+            log::warn("some shims could not be written into {}; commands may "
+                      "not resolve inside this subos", (dstDir / "bin").string());
+        }
+    }
+
+    nlohmann::json payload;
+    payload["name"]    = name;
+    payload["from"]    = fromSpec;
+    payload["base"]    = baseDir.string();
+    payload["storage"] = sandbox::storage_to_string_(storage);
+    stream.emit(DataEvent{"subos_forked", payload.dump()});
+    return 0;
+}
+
+ // namespace use_detail_
+
+// Internal — not exported. `xlings subos use --global <name>` and
+// the back-compat single-arg `use()` both route here.
+int use_global(const std::string& name, EventStream& stream) {
+    if (auto rc = use_detail_::validate_subos_(name, stream); rc != 0) return rc;
+
+    auto& p = Config::paths();
+    // The window here is short, but a full-document rewrite is a full-document
+    // rewrite: an install committing between the read and the write loses its
+    // `versions` entry all the same.
+    auto committed = update_home_config(p.homeDir, [&](nlohmann::json& json) {
+        json["activeSubos"] = name;
+        return true;
+    });
+    if (!committed) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::Internal,
+            .message = "failed to switch subos: " + committed.error(),
+            .recoverable = true,
+        });
+        return 1;
+    }
+
+    auto dir = Config::subos_dir(name);
+    update_current_symlink_(stream, p.homeDir, dir);
+
+    nlohmann::json payload;
+    payload["name"] = name;
+    payload["dir"]  = dir.string();
+    stream.emit(DataEvent{"subos_switched", payload.dump()});
+    return 0;
+}
+
+// Internal — not exported. Powers the hidden `--shell <kind>` flag,
+// kept available for tests and power users that want eval-able output
+// without a sub-shell layer. The default user-facing path is
+// use_spawn_shell; --shell is intentionally not in the help text.
+// Shell-level entry never activates storage isolation (V4 orthogonality
+// — see use_spawn_shell). Emit a single hint to stderr if the subos
+// was created with image/tmpfs storage so the user understands the
+// attribute is dormant in this entry. Writes to stderr (not stdout)
+// so the --shell <kind> path stays eval-safe.
+// `--sandbox` without `--gpu` on a machine that has one, for a subos that does
+// graphics: say so, once, before entering.
+//
+// bwrap's `--dev` builds a fresh /dev from a hard-coded whitelist that does not
+// include /dev/nvidia*, /dev/dri or /dev/dxg, so a sandbox without `--gpu` is a
+// software-rendering environment by construction. That default is CORRECT --
+// device passthrough should be a decision someone takes, not something a tool
+// does quietly -- and `--gpu` genuinely restores it: measured, GLX and Vulkan
+// come back byte-identical to the unsandboxed subos.
+//
+// So the gap is not capability, it is silence. Without the flag the user gets
+// "runs, draws a window, exits 0", indistinguishable from the GPU case except
+// in frame rate. That is this stack's whole failure mode: succeeding at the
+// wrong thing without saying so.
+//
+// THREE conditions, and the narrowness is the point. `warn_storage_dormant_on_
+// shell_` a few lines below is a hint that fired on every entry of its kind,
+// became noise, and is now commented out -- a hint that cannot be acted on is
+// worse than none. This one can only fire where acting on it changes the
+// outcome:
+//
+//   * the subos has a GL dispatch -- a subos that does no graphics is not
+//     missing anything (read, not probed: same state file `subos info` reads)
+//   * the host actually has GPU device nodes -- on a machine with no GPU,
+//     `--gpu` would expose nothing and the advice would be false
+//   * `--gpu` was not passed -- the user who asked does not need telling
+void warn_sandbox_without_gpu_(const std::string& name, bool gpu,
+                               EventStream& stream) {
+    if (gpu) return;
+    auto w = xlings::subos::graphics::read_graphics_wiring(Config::subos_dir(name));
+    if (!w.has_dispatch()) return;
+    if (!xlings::subos::gpu::host_has_gpu_devices()) return;
+    stream.emit(DataEvent{"tip", nlohmann::json{
+        {"message",
+         "this subos has a GL stack but the sandbox exposes no GPU device; "
+         "GL will render in software. Add --gpu to pass the host's GPU through."}
+    }.dump()});
+}
+
+void warn_storage_dormant_on_shell_(const std::string& name) {
+    auto& p = Config::paths();
+    auto storage = sandbox::read_storage_mode_(p.homeDir / "subos" / name);
+    if (storage == sandbox::StorageMode::Shared) return;
+    // Hint disabled: wording was ambiguous ("use --sandbox to activate"
+    // reads as either the verb or the `subos use` command) and it fired
+    // on every shell-level entry for image/tmpfs subos, becoming noise
+    // once the user already knows the layout. Revisit with a clearer
+    // one-time / opt-in form before re-enabling.
+    // std::println(stderr,
+    //              "[xlings] storage={} is sandbox-only; entering "
+    //              "shell-level (use --sandbox to activate)",
+    //              sandbox::storage_to_string_(storage));
+    (void)storage;
+}
+
+int use_emit_shell(const std::string& name,
+                          std::string_view shell_kind,
+                          EventStream& stream) {
+    if (auto rc = use_detail_::validate_subos_(name, stream); rc != 0) return rc;
+    warn_storage_dormant_on_shell_(name);
+
+    auto& p = Config::paths();
+    auto bin_dir = p.homeDir / "subos" / name / "bin";
+
+    bool is_fish = (shell_kind == "fish");
+    bool is_pwsh = (shell_kind == "pwsh" || shell_kind == "powershell" ||
+                    shell_kind == "ps1" || shell_kind == "ps");
+
+    // The subos's own declared environment (GL driver paths, EGL vendor dirs,
+    // and whatever else a package needs a *user's* binary to see). Emitted
+    // after the xvm/PATH lines so a declaration cannot displace them.
+    //
+    // UC-1 -- a variable the user already exported wins. The emitted code
+    // tests the live variable rather than what this process happens to see:
+    // `--shell` output is frequently captured once and eval'd later, in a
+    // shell whose environment has moved on.
+    const auto envVars = use_detail_::subos_env_for_(name);
+    use_detail_::report_injected_env_(name, envVars);
+
+    if (is_fish) {
+        std::println(R"(set -gx XLINGS_ACTIVE_SUBOS "{}";)", name);
+        std::println(R"(set -gx XLINGS_BIN "{}";)", bin_dir.string());
+        // Strip any old subos bin segments from PATH, then prepend the new
+        // bin. fish's $PATH is a list, so we use string match -v.
+        std::println(R"(set -gx PATH "{}" (string match -v -r "^{}/subos/[^/]+/bin$" -- $PATH);)",
+                     bin_dir.string(), p.homeDir.string());
+        for (const auto& v : envVars) {
+            if (v.unresolved) continue;
+            // R"SH(...)SH": the fish source below contains `)"`, which ends a
+            // plain R"(...)" literal early -- and the truncation compiles,
+            // because what is left is still a valid string.
+            if (v.op == manifest::OP_PREPEND) {
+                std::println(
+                    R"SH(if set -q {0}; set -gx {0} "{1}:${0}"; else; set -gx {0} "{1}"; end;)SH",
+                    v.var, v.value);
+            } else {
+                std::println(R"SH(if not set -q {0}; set -gx {0} "{1}"; end;)SH",
+                             v.var, v.value);
+            }
+        }
+        return 0;
+    }
+    if (is_pwsh) {
+        std::println(R"($env:XLINGS_ACTIVE_SUBOS = '{}')", name);
+        std::println(R"($env:XLINGS_BIN = '{}')", bin_dir.string());
+        std::println(R"($env:Path = '{}' + ';' + (($env:Path -split ';') -notmatch '^{}\\subos\\[^\\]+\\bin$' -join ';'))",
+                     bin_dir.string(), p.homeDir.string());
+        for (const auto& v : envVars) {
+            if (v.unresolved) continue;
+            // ';' rather than ':' -- these are path lists, and on Windows the
+            // separator is the one the platform's own tools split on.
+            if (v.op == manifest::OP_PREPEND) {
+                std::println(
+                    R"($env:{0} = if ($env:{0}) {{ '{1}' + ';' + $env:{0} }} else {{ '{1}' }})",
+                    v.var, v.value);
+            } else {
+                // `$null -eq`, not `-not`: PowerShell's `-not` is true for an
+                // empty string too, which would overwrite a value the user
+                // deliberately set to "".
+                std::println(R"(if ($null -eq $env:{0}) {{ $env:{0} = '{1}' }})",
+                             v.var, v.value);
+            }
+        }
+        return 0;
+    }
+    // POSIX (sh/bash/zsh) default
+    auto orig_path = utils::get_env_or_default("PATH");
+    auto new_path  = use_detail_::rebuild_path_for_subos_(
+        orig_path, p.homeDir, bin_dir);
+    std::println(R"(export XLINGS_ACTIVE_SUBOS="{}";)", name);
+    std::println(R"(export XLINGS_BIN="{}";)", bin_dir.string());
+    std::println(R"(export PATH="{}";)", new_path);
+    for (const auto& v : envVars) {
+        if (v.unresolved) continue;
+        if (v.op == manifest::OP_PREPEND) {
+            // ${VAR:+:$VAR} appends the separator only when VAR is non-empty,
+            // so an unset variable does not become a trailing ':' -- which an
+            // empty PATH-list element reads as "the current directory".
+            std::println(R"(export {0}="{1}${{{0}:+:${0}}}";)", v.var, v.value);
+        } else {
+            // `${VAR=v}`, NOT `${VAR:=v}`. The colon form also assigns when VAR
+            // is set-but-empty, which would overwrite a value the user chose.
+            std::println(R"(: "${{{0}={1}}}"; export {0};)", v.var, v.value);
+        }
+    }
+    return 0;
+}
+
+int use_spawn_shell(const std::string& name, EventStream& stream, bool sandbox, const std::string& sandbox_backend, bool gpu, const std::string& cmd)
+{
+    // V5: --sandbox [backend] is a `use`-time modifier. Dispatch to the
+    // sandbox path when set; auto-detect backend (bwrap preferred, proot
+    // fallback) or use the explicitly requested one.
+    //
+    // Storage mode (image/tmpfs) and sandbox are orthogonal axes per
+    // V4 design: shell-level entry only swaps env/PATH and never
+    // mounts. Image / tmpfs only take effect when `--sandbox` is
+    // explicitly passed — earlier V6 auto-upgrade fused the two axes
+    // and made `subos use <image-subos>` silently require root, bwrap,
+    // and a working mount namespace just to switch shells.
+    //
+    // M3: `cmd` non-empty switches to non-interactive single-command
+    // execution — `shell -c <cmd>` instead of an interactive shell.
+    // Useful for scripts and agent workflows.
+    if (sandbox) {
+        // Before entering, not inside: the sandbox module cannot import this
+        // one (this one imports it), and proot/bwrap pass our environment
+        // through to the shell anyway. The home is bound at its own absolute
+        // path, so the payload paths in these values mean the same thing on
+        // both sides of the boundary.
+        if (auto rc = use_detail_::validate_subos_(name, stream); rc != 0) return rc;
+        use_detail_::apply_subos_env_(name);
+        warn_sandbox_without_gpu_(name, gpu, stream);
+        return sandbox::enter(name, stream, sandbox_backend, gpu, cmd);
+    }
+    warn_storage_dormant_on_shell_(name);
+
+    if (auto rc = use_detail_::validate_subos_(name, stream); rc != 0) return rc;
+
+    auto already = utils::get_env_or_default("XLINGS_ACTIVE_SUBOS");
+    if (already == name) {
+        nlohmann::json p; p["name"] = name;
+        stream.emit(DataEvent{"subos_already_in", p.dump()});
+        return 0;
+    }
+    if (!already.empty()) {
+        nlohmann::json p; p["from"] = already; p["to"] = name;
+        stream.emit(DataEvent{"subos_nesting", p.dump()});
+    }
+
+    auto& p = Config::paths();
+    auto bin_dir = p.homeDir / "subos" / name / "bin";
+
+    auto orig_path = utils::get_env_or_default("PATH");
+    auto new_path  = use_detail_::rebuild_path_for_subos_(
+        orig_path, p.homeDir, bin_dir);
+
+    // Set env BEFORE spawning so the child shell inherits it. The profile
+    // sourced by the child reads XLINGS_ACTIVE_SUBOS and re-computes
+    // XLINGS_BIN; XLINGS_BIN we set here is mostly defensive (covers the
+    // case where the child shell is started with --norc and never sources
+    // the profile).
+    platform::set_env_variable("XLINGS_ACTIVE_SUBOS", name);
+    platform::set_env_variable("XLINGS_BIN", bin_dir.string());
+    // E2a: the subos's library farm, DECLARED rather than derivable.
+    //
+    // Two consumers need it and neither should have to guess. The linker
+    // wrapper in the binutils payload writes it into `-rpath-link` (and, when
+    // not opted out, `-rpath`) so a program built in here can find the
+    // libraries it just linked against; mcpp reads it to know which directory
+    // to strip back out at pack time. Both reading one declaration is the
+    // difference between a contract and two derivations of the same decision
+    // that drift.
+    //
+    // `XLINGS_BIN` + "/../lib" would work today and is exactly the coincidence
+    // this replaces: it is true because of how the farm happens to be laid
+    // out, not because anything promised it.
+    platform::set_env_variable(
+        "XLINGS_SUBOS_LIB",
+        (p.homeDir / "subos" / name / "lib").string());
+    platform::set_env_variable("PATH", new_path);
+
+    // The subos's declared environment, applied to this process before it is
+    // replaced -- so the shell (or the single `--cmd`) inherits it, and so
+    // does every user binary run inside. This is the path that matters for
+    // issue #352: nothing xlings wraps needs LIBGL_DRIVERS_PATH, the user's
+    // own GL program does.
+    //
+    // UC-1 -- a variable already set in this environment is the user's, and
+    // `set` leaves it alone. `prepend` still contributes, since composing is
+    // what prepend means.
+    use_detail_::apply_subos_env_(name);
+
+    nlohmann::json payload;
+    payload["name"] = name;
+    payload["mode"] = "spawn";
+    stream.emit(DataEvent{"subos_entering", payload.dump()});
+
+    // Flush std streams before exec/CreateProcess — buffered output isn't
+    // preserved across execve(2), and on Windows the child shell may start
+    // writing before the parent's pending output drains; in either case
+    // CI capture (where stdout is a pipe rather than a TTY) loses any
+    // block-buffered bytes that didn't get flushed.
+    std::cout.flush();
+    std::cerr.flush();
+
+    return platform::run_shell(cmd, cmd.empty());
+}
+
+int use(const std::string& name, EventStream& stream) {
+    auto resolved = resolve_use_name_(name, stream);
+    if (resolved.selected.empty()) return resolved.exitCode;
+    return use_global(resolved.selected, stream);
+}
+
+int remove(const std::string& name, EventStream& stream) {
+    if (name == "default") {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = "cannot remove the 'default' subos",
+            .recoverable = false,
+        });
+        return 1;
+    }
+
+    auto& p = Config::paths();
+    if (p.activeSubos == name) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = "cannot remove the active subos '" + name + "'",
+            .recoverable = true,
+            .hint = "switch first: xlings subos use default",
+        });
+        return 1;
+    }
+
+    if (!read_home_config(p.homeDir).value("subos", nlohmann::json::object())
+             .contains(name)) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::NotFound,
+            .message = "subos '" + name + "' not found",
+            .recoverable = true,
+        });
+        return 1;
+    }
+
+    auto dir = Config::subos_dir(name);
+    if (fs::exists(dir)) {
+        // V6: image-storage subos has an ext4 mount at <subos>/.mountpoint.
+        // remove_all would either (a) hit EBUSY at the mountpoint, leaving
+        // a half-cleaned tree behind, or (b) silently recurse into the
+        // live mount and erase the image's contents before EBUSY surfaces.
+        // Detect and umount first.
+#if defined(__linux__)
+        auto mountpoint = dir / ".mountpoint";
+        if (fs::exists(mountpoint)
+            && sandbox::is_mounted_(mountpoint))
+        {
+            if (sandbox::unmount_image_(mountpoint) != 0) {
+                stream.emit(ErrorEvent{
+                    .code = ErrorCode::Permission,
+                    .message = "failed to unmount " + mountpoint.string()
+                               + " (image storage subos); refusing to "
+                                 "remove to avoid corrupting the live "
+                                 "filesystem",
+                    .recoverable = true,
+                    .hint = "ensure no shell is inside this subos, then "
+                            "retry — or manually: sudo umount "
+                            + mountpoint.string(),
+                });
+                return 1;
+            }
+        }
+#endif
+        std::error_code ec;
+        fs::remove_all(dir, ec);
+        if (ec) {
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::Permission,
+                .message = "failed to remove " + dir.string() + ": " + ec.message(),
+                .recoverable = false,
+            });
+            return 1;
+        }
+    }
+
+    // remove_all above walks the whole subos tree and can run for a long
+    // time on a big one. Deleting our key out of a document read before that
+    // walk would resurrect every other key's pre-walk value.
+    auto committed = update_home_config(p.homeDir, [&](nlohmann::json& json) {
+        if (!json.contains("subos") || !json["subos"].is_object()) return false;
+        return json["subos"].erase(name) > 0;
+    });
+    if (!committed) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::Internal,
+            .message = "subos '" + name + "' was deleted from disk but its "
+                       "entry could not be removed: " + committed.error(),
+            .recoverable = true,
+            .hint = "retry once the other xlings finishes",
+        });
+        return 1;
+    }
+
+    nlohmann::json payload;
+    payload["name"] = name;
+    stream.emit(DataEvent{"subos_removed", payload.dump()});
+    return 0;
+}
+
+std::optional<SubosInfo> info(const std::string& name) {
+    auto& p = Config::paths();
+    auto dir = Config::subos_dir(name);
+    if (!fs::exists(dir)) return std::nullopt;
+
+    int toolCount = 0;
+    auto binDir = dir / "bin";
+    if (fs::exists(binDir)) {
+        for (auto& e : platform::dir_entries(binDir)) {
+            auto stem = e.path().stem().string();
+            if (!xself::is_builtin_shim(stem) && stem != "xvm-alias")
+                ++toolCount;
+        }
+    }
+    return SubosInfo{name, dir, p.activeSubos == name, toolCount};
+}
+
+int run_list_(EventStream& stream) {
+    auto all = candidate_view().candidates;
+    std::vector<std::tuple<std::string, std::string, int, bool>> entries;
+    for (auto& s : all) {
+        entries.emplace_back(s.name, s.dir.string(), s.toolCount, s.isActive);
+    }
+    nlohmann::json entriesJson = nlohmann::json::array();
+    for (auto& [n, d, tc, active] : entries) {
+        entriesJson.push_back({{"name", n}, {"dir", d}, {"pkgCount", tc}, {"active", active}});
+    }
+    nlohmann::json payload;
+    payload["entries"] = std::move(entriesJson);
+    stream.emit(DataEvent{"subos_list", payload.dump()});
+    return 0;
+}
+
+// The graphics section of `xlings subos info`.
+//
+// This is the ONLY channel the wiring verdict has. It was designed as the
+// second one: the graphics recipe logs a warning for every vendor it finds
+// broken, and that seemed sufficient. Measured on a real install — the config
+// hook's log does not surface on the success path at all, not the new
+// warnings and not the stack's own long-standing "GL renders on the GPU"
+// banner. A user whose NVIDIA vendor cannot load is told nothing, anywhere,
+// unless they run this command.
+//
+// Empty when the subos has no GL dispatch, so `subos info` is unchanged for
+// every subos that does no graphics — which is most of them.
+nlohmann::json graphics_fields_(const fs::path& subosDir) {
+    namespace gfx = xlings::subos::graphics;
+    auto w = gfx::read_graphics_wiring(subosDir);
+    nlohmann::json out = nlohmann::json::array();
+    if (!w.has_dispatch()) return out;
+
+    auto row = [&](std::string label, std::string value, bool alert) {
+        out.push_back({{"label", std::move(label)}, {"value", std::move(value)},
+                       {"highlight", false}, {"alert", alert}});
+    };
+
+    row("GL dispatch", w.dispatchDir.string(), false);
+
+    switch (w.status) {
+    case gfx::WiringStatus::NoVendors:
+        // The failure this whole mechanism exists to remove, and the one case
+        // that needs no record to detect: glvnd with nothing to dispatch to
+        // falls back to software rendering and reports success.
+        row("vendors",
+            "NONE REGISTERED — every GL program in this subos falls back to "
+            "software rendering. Run 'xlings install graphics' to wire it.",
+            true);
+        return out;
+    case gfx::WiringStatus::Unrecorded:
+        row("vendors",
+            std::to_string(w.vendorFiles) + " registered, but this stack was "
+            "wired before xlings recorded whether they load. Re-run "
+            "'xlings install graphics' to check them.",
+            true);
+        return out;
+    default:
+        break;
+    }
+
+    // The one part of this stack we do not own is the host's NVIDIA driver,
+    // and it moves: a distribution update replaces it, the versioned SONAMEs
+    // our payload links to change, and the wiring below describes a driver
+    // that is no longer there. The detector already existed and worked
+    // (`xlings-gl-doctor`); what it lacked was a way to reach the user without
+    // being remembered. Reported before the per-vendor rows because when it
+    // fires, every row under it is about the old driver.
+    if (auto d = gfx::read_driver_stamp(w.dispatchDir / "lib" /
+                                        std::string(gfx::kVendorSubdir));
+        d.drifted()) {
+        row("host driver",
+            "CHANGED — this stack was wired for " + d.builtFor +
+            " and the host is now running " + d.hostNow +
+            ". Re-run 'xlings install graphics'; until then the states below "
+            "describe a driver that is no longer loaded.",
+            true);
+    }
+
+    if (w.dispatchMismatch) {
+        // The record describes libraries nobody in this subos will load.
+        // Reporting their states as this subos's would be a confident wrong
+        // answer, so say that first and keep the states clearly attributed.
+        row("stale wiring",
+            "recorded against " + w.recordedDispatch + ", which is not the "
+            "dispatch this subos loads. The states below may describe a "
+            "different stack — re-run 'xlings install graphics'.",
+            true);
+    }
+
+    for (const auto& v : w.vendors) {
+        auto lbl = gfx::label_for(v.soname);
+        auto label = lbl ? lbl->vendor + " " + lbl->api : v.soname;
+        // `needs-transitive-consumer` is marked too: it is not a failure for
+        // installed programs, but it IS the answer to "why does the GL app I
+        // just compiled render in software", and that question is why someone
+        // reads this panel.
+        row(std::move(label), gfx::describe(v),
+            v.stale || v.is_broken() || v.needs_transitive_consumer());
+    }
+    return out;
+}
+
+int run_info_(const std::string& name, EventStream& stream) {
+    auto& p = Config::paths();
+    auto target = name.empty() ? p.activeSubos : name;
+    auto si = info(target);
+    if (!si) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::NotFound,
+            .message = "subos '" + target + "' not found",
+            .recoverable = true,
+        });
+        return 1;
+    }
+    nlohmann::json fieldsJson = nlohmann::json::array();
+    fieldsJson.push_back({{"label", "active"}, {"value", si->isActive ? "yes" : "no"}, {"highlight", si->isActive}});
+    fieldsJson.push_back({{"label", "dir"}, {"value", si->dir.string()}, {"highlight", false}});
+    fieldsJson.push_back({{"label", "tools"}, {"value", std::to_string(si->toolCount)}, {"highlight", false}});
+    nlohmann::json payload;
+    payload["title"] = si->name;
+    payload["fields"] = std::move(fieldsJson);
+    auto gfx = graphics_fields_(si->dir);
+    if (!gfx.empty()) payload["extra_fields"] = std::move(gfx);
+    stream.emit(DataEvent{"info_panel", payload.dump()});
+    return 0;
+}
+
+int run(int argc, char* argv[], EventStream& stream) {
+    // Drop the options root publishes as valid on every command before any
+    // subcommand's argv loop sees them. `subos new` and `subos use` end their
+    // loops with a catch-all `usageError`, so a documented global flag such as
+    // `--yes` -- which an agent is instructed to always pass -- would come
+    // back as "unknown option" from a command that has nothing to confirm.
+    std::vector<char*> filtered;
+    filtered.reserve(static_cast<std::size_t>(argc));
+    for (int i = 0; i < argc; ++i) {
+        if (i >= 3 && cli::spec::is_global_option(argv[i])) continue;
+        filtered.push_back(argv[i]);
+    }
+    argc = static_cast<int>(filtered.size());
+    argv = filtered.data();
+
+    if (argc < 3) return run_list_(stream);
+
+    std::string sub = argv[2];
+    if (sub == "ls") sub = "list";
+    if (sub == "rm") sub = "remove";
+    if (sub == "i")  sub = "info";
+
+    auto usageError = [&](std::string_view detail) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = std::string(detail),
+            .recoverable = false,
+            .hint = "usage: xlings subos <new|use|list|ls|remove|rm|info|i|stop> [name]",
+        });
+    };
+
+    if (sub == "new") {
+        if (argc < 4) { usageError("missing <name> for: xlings subos new"); return 1; }
+        // Parse: xlings subos new <name> [--storage <mode>] [--image-size <size>] [--from <spec>]
+        std::string name;
+        sandbox::StorageMode storage = sandbox::StorageMode::Shared;
+        std::string imageSize = "50G";
+        // M2: --from <spec> creates the new subos by forking an existing
+        // source. Spec containing `:` or `@` is treated as a pkg-spec
+        // (auto-installs the base xpkg if missing); bare name is treated
+        // as a local subos to fork from.
+        std::string fromSpec;
+        // --runtime <binding>: what this subos's binaries are built against
+        // ("glibc@2.39"). Creation-time, because changing it later would
+        // invalidate every payload already installed. Absent → the built-in
+        // default, so existing invocations keep working unchanged.
+        std::string runtime;
+        for (int i = 3; i < argc; ++i) {
+            std::string a = argv[i];
+            if (a == "--runtime" && i + 1 < argc) {
+                runtime = argv[++i];
+            }
+            else if (a.rfind("--runtime=", 0) == 0) {
+                runtime = a.substr(10);
+            }
+            else if (a == "--storage" && i + 1 < argc) {
+                auto s = std::string(argv[++i]);
+                if (s == "image") storage = sandbox::StorageMode::Image;
+                else if (s == "tmpfs") storage = sandbox::StorageMode::Tmpfs;
+                else if (s == "shared") storage = sandbox::StorageMode::Shared;
+                else {
+                    usageError("unknown storage mode: " + s
+                               + " (valid: shared, image, tmpfs)");
+                    return 1;
+                }
+            }
+            else if (a == "--image-size" && i + 1 < argc) {
+                imageSize = argv[++i];
+            }
+            else if (a == "--from" && i + 1 < argc) {
+                fromSpec = argv[++i];
+            }
+            else if (a.rfind("--from=", 0) == 0) {
+                fromSpec = a.substr(7);
+            }
+            else if (!a.empty() && a[0] != '-' && name.empty()) {
+                name = std::move(a);
+            }
+            else {
+                usageError("unknown option for `xlings subos new`: " + a);
+                return 1;
+            }
+        }
+        if (name.empty()) {
+            usageError("missing <name> for: xlings subos new");
+            return 1;
+        }
+        if (!fromSpec.empty()) {
+            return new_from(name, {}, storage, imageSize, fromSpec, runtime, stream);
+        }
+        return create(name, {}, storage, imageSize, runtime, stream);
+    }
+    if (sub == "use") {
+        // Flags supported:
+        //   --global         persist the choice into ~/.xlings.json + symlink
+        //                    (legacy behavior; affects every shell)
+        //   --shell <kind>   emit shell code on stdout for the user to
+        //                    eval/Invoke-Expression. <kind> ∈ {sh,bash,zsh,
+        //                    fish,pwsh}. Defaults to "sh" if not provided.
+        //   --sandbox        Linux-only: enter via proot fs-isolation. $HOME,
+        //                    /tmp, /etc/passwd are sandbox-private; ~/.xlings,
+        //                    /usr, /lib*, /etc/{resolv.conf,ld.so.cache} are
+        //                    bound from host. Same shell (`$SHELL`) as outside.
+        //                    Prompt switches from `[xsubos:<name>]` to
+        //                    `<xsubos:<name>>` so the user can tell at a glance.
+        //   (no flag)        spawn a fresh interactive shell with
+        //                    XLINGS_ACTIVE_SUBOS=<name> in env. Per-shell.
+        std::string name;
+        std::string mode = "spawn";        // default
+        std::string shell_kind = "sh";
+        bool sandbox = false;
+        std::string sandbox_backend;       // "" = auto, "bwrap", "proot"
+        // M3: --cmd <string> runs a single command non-interactively
+        // and exits with the command's exit code. Works in both shell-
+        // level and sandbox modes. Internally routed to `sh -c <cmd>`
+        // (POSIX) or `pwsh -Command <cmd>` / `cmd /c <cmd>` (Windows).
+        std::string cmd;
+        // M5: explicit keeper policy overrides (D9). The runtime auto-
+        // default (storage=image|tmpfs + sandbox + Linux → keeper on,
+        // TTL=5min) is encoded in keeper::should_auto_keeper. These
+        // flags let the user override per call:
+        //   --no-keep      force disable (one-shot, even if auto would)
+        //   --keep         never-expiring (use until `subos stop`)
+        //   --ttl <sec>    custom idle TTL
+        bool no_keep = false;
+        bool keep_forever = false;
+        int  ttl_sec = 0;                  // 0 = use default
+        // --gpu: opt-in NVIDIA + DRM device passthrough for bwrap
+        // sandbox. Missing devices are silently skipped. Requires
+        // --sandbox; ignored when the backend resolves to proot (proot
+        // already passes /dev and /sys through wholesale).
+        // Ref: .agents/docs/2026-05-22-subos-sandbox-gpu-passthrough.md
+        bool gpu = false;
+        for (int i = 3; i < argc; ++i) {
+            std::string a = argv[i];
+            if (a == "--global") { mode = "global"; }
+            else if (a == "--shell") {
+                mode = "shell";
+                if (i + 1 < argc && argv[i + 1][0] != '-') {
+                    shell_kind = argv[++i];
+                }
+            }
+            else if (a.rfind("--shell=", 0) == 0) {
+                mode = "shell";
+                shell_kind = a.substr(8);
+            }
+            else if (a == "--sandbox") {
+                sandbox = true;
+                // Optional backend argument: --sandbox bwrap | --sandbox proot
+                if (i + 1 < argc) {
+                    std::string next = argv[i + 1];
+                    if (next == "bwrap" || next == "proot") {
+                        sandbox_backend = next;
+                        ++i;
+                    }
+                }
+            }
+            else if (a == "--cmd" && i + 1 < argc) {
+                cmd = argv[++i];
+            }
+            else if (a.rfind("--cmd=", 0) == 0) {
+                cmd = a.substr(6);
+            }
+            // M5 keeper policy flags. The runtime spawning of the keeper
+            // is wired separately (see keeper.cppm); these flags are
+            // accepted on the CLI and threaded through for forward
+            // compatibility. Auto-default (D9) is governed by
+            // should_auto_keeper() at runtime.
+            else if (a == "--no-keep") {
+                no_keep = true;
+            }
+            else if (a == "--keep") {
+                keep_forever = true;
+            }
+            else if (a == "--ttl" && i + 1 < argc) {
+                try { ttl_sec = std::stoi(argv[++i]); }
+                catch (...) {
+                    usageError("--ttl expects an integer (seconds)");
+                    return 1;
+                }
+            }
+            else if (a.rfind("--ttl=", 0) == 0) {
+                try { ttl_sec = std::stoi(std::string(a.substr(6))); }
+                catch (...) {
+                    usageError("--ttl=<sec> expects an integer");
+                    return 1;
+                }
+            }
+            else if (a == "--gpu") {
+                gpu = true;
+            }
+            else if (!a.empty() && a[0] != '-' && name.empty()) {
+                name = std::move(a);
+            }
+            else {
+                usageError("unknown option for `xlings subos use`: " + a);
+                return 1;
+            }
+        }
+        if (no_keep && keep_forever) {
+            usageError("--no-keep and --keep are mutually exclusive");
+            return 1;
+        }
+
+        if (gpu && !sandbox) {
+            usageError("--gpu requires --sandbox "
+                       "(GPU passthrough only applies to bwrap-sandboxed sessions)");
+            return 1;
+        }
+
+        // No name is a request to SEE the candidates -- but only when the rest
+        // of the command asked for nothing else. Every other flag here names an
+        // effect: run this command, emit this shell code, persist this choice,
+        // enter this sandbox. Listing candidates and exiting 0 in their place
+        // reports success for work that never happened, and `--shell` makes it
+        // worse than a no-op: that stdout is eval'd by the caller, so a table
+        // lands where shell code was expected.
+        //
+        // The acceptance path for this whole release is
+        // `subos use <name> --sandbox --cmd ...`; a typo there has to fail, not
+        // print a list and return 0.
+        const bool discoveryOnly = mode == "spawn" && cmd.empty()
+            && !sandbox && !gpu && !no_keep && !keep_forever && ttl_sec == 0;
+        if (name.empty() && !discoveryOnly) {
+            usageError("missing <name> for: xlings subos use "
+                       "(run `xlings subos use` with no other arguments to "
+                       "list candidates)");
+            return 1;
+        }
+
+        auto resolved = resolve_use_name_(name, stream);
+        if (resolved.selected.empty()) return resolved.exitCode;
+        name = std::move(resolved.selected);
+
+        if (mode == "global") {
+            if (!cmd.empty()) {
+                usageError("--cmd is incompatible with --global "
+                           "(--global persists the active subos but doesn't spawn a shell)");
+                return 1;
+            }
+            return use_global(name, stream);
+        }
+        if (mode == "shell") {
+            if (!cmd.empty()) {
+                usageError("--cmd is incompatible with --shell <kind> "
+                           "(--shell emits env code; use plain `subos use --cmd` for non-interactive exec)");
+                return 1;
+            }
+            return use_emit_shell(name, shell_kind, stream);
+        }
+        return use_spawn_shell(name, stream, sandbox, sandbox_backend, gpu, cmd);
+    }
+    if (sub == "list")   return run_list_(stream);
+    if (sub == "remove") {
+        if (argc < 4) { usageError("missing <name> for: xlings subos remove|rm"); return 1; }
+        return remove(argv[3], stream);
+    }
+    if (sub == "info")   return run_info_(argc > 3 ? argv[3] : "", stream);
+    if (sub == "stop") {
+        // M4/D9: stop the auto-keeper for a sandboxed subos.
+        // Safe to invoke even when no keeper is running — it's a no-op.
+        if (argc < 4) { usageError("missing <name> for: xlings subos stop"); return 1; }
+        return keeper::stop_keeper(argv[3]);
+    }
+
+    usageError("unknown subcommand: " + sub);
+    return 1;
+}
+
+}
diff --git a/src/core/subos.cppm b/src/core/subos.cppm
index 73f97402..3e6807cf 100644
--- a/src/core/subos.cppm
+++ b/src/core/subos.cppm
@@ -28,8 +28,6 @@ export module xlings.core.subos;
 import std;
 
 import xlings.core.config;
-import xlings.core.home_config;
-import xlings.libs.json;
 import xlings.core.log;
 import xlings.platform;
 import xlings.runtime;
@@ -60,89 +58,9 @@ export struct SubosCandidateView {
     std::vector<SubosInfo> candidates;
 };
 
-nlohmann::json read_config_json_(const fs::path& path) {
-    if (!fs::exists(path)) return nlohmann::json::object();
-    try {
-        auto content = platform::read_file_to_string(path.string());
-        auto json = nlohmann::json::parse(content, nullptr, false);
-        return json.is_discarded() ? nlohmann::json::object() : json;
-    } catch (...) { return nlohmann::json::object(); }
-}
-
-void write_config_json_(const fs::path& path, const nlohmann::json& json) {
-    platform::write_string_to_file(path.string(), json.dump(2));
-}
-
-SubosInfo candidate_info_(const std::string& name, bool includeToolCount) {
-    auto& p = Config::paths();
-    auto dir = Config::subos_dir(name);
-    int toolCount = 0;
-    auto binDir = dir / "bin";
-    if (includeToolCount && fs::exists(binDir)) {
-        for (auto& e : platform::dir_entries(binDir)) {
-            auto stem = e.path().stem().string();
-            if (!xself::is_builtin_shim(stem) && stem != "xvm-alias")
-                ++toolCount;
-        }
-    }
-    return {name, dir, p.activeSubos == name, toolCount};
-}
-
-export SubosCandidateView candidate_view(bool includeToolCount = true) {
-    auto& p = Config::paths();
-    auto json = read_config_json_(p.homeDir / ".xlings.json");
-    SubosCandidateView view;
-    bool hasDefault = false;
-
-    if (json.contains("subos") && json["subos"].is_object()) {
-        for (auto it = json["subos"].begin(); it != json["subos"].end(); ++it) {
-            auto name = it.key();
-            hasDefault = hasDefault || name == "default";
-            view.candidates.push_back(candidate_info_(name, includeToolCount));
-        }
-    }
-
-    // Bounded compatibility for homes created before the registry existed.
-    // Only the well-known default manifest is synthesized. Arbitrary
-    // directories are never promoted into environments by a read-only query.
-    std::error_code ec;
-    const auto defaultManifest =
-        Config::subos_dir("default") / ".xlings.json";
-    if (!hasDefault && fs::is_regular_file(defaultManifest, ec)) {
-        view.candidates.push_back(
-            candidate_info_("default", includeToolCount));
-    }
-
-    std::ranges::sort(view.candidates, {}, &SubosInfo::name);
-    return view;
-}
-
-export std::vector<SubosInfo> list_all() {
-    return candidate_view().candidates;
-}
+export SubosCandidateView candidate_view(bool includeToolCount = true);
 
-std::string lowercase_name_(std::string_view name) {
-    std::string lowered(name);
-    for (auto& ch : lowered) {
-        if (ch >= 'A' && ch <= 'Z') ch = static_cast<char>(ch - 'A' + 'a');
-    }
-    return lowered;
-}
-
-std::size_t edit_distance_(std::string_view lhs, std::string_view rhs) {
-    std::vector<std::size_t> prev(rhs.size() + 1);
-    std::vector<std::size_t> next(rhs.size() + 1);
-    std::iota(prev.begin(), prev.end(), std::size_t{0});
-    for (std::size_t i = 0; i < lhs.size(); ++i) {
-        next[0] = i + 1;
-        for (std::size_t j = 0; j < rhs.size(); ++j) {
-            const auto replace = prev[j] + (lhs[i] == rhs[j] ? 0u : 1u);
-            next[j + 1] = std::min({prev[j + 1] + 1, next[j] + 1, replace});
-        }
-        std::swap(prev, next);
-    }
-    return prev.back();
-}
+export std::vector<SubosInfo> list_all();
 
 struct CandidateResolution_ {
     std::string selected;
@@ -151,242 +69,11 @@ struct CandidateResolution_ {
     bool autoSelected { false };
 };
 
-std::vector<SubosInfo> suggestions_(
-        std::string_view query,
-        std::span<const SubosInfo> candidates) {
-    struct Scored {
-        int substringRank;
-        std::size_t distance;
-        SubosInfo candidate;
-    };
-    const auto loweredQuery = lowercase_name_(query);
-    std::vector<Scored> scored;
-    scored.reserve(candidates.size());
-    for (const auto& candidate : candidates) {
-        const auto lowered = lowercase_name_(candidate.name);
-        const bool related = lowered.contains(loweredQuery)
-            || loweredQuery.contains(lowered);
-        scored.push_back({related ? 0 : 1,
-                          edit_distance_(loweredQuery, lowered), candidate});
-    }
-    std::ranges::sort(scored, [](const auto& lhs, const auto& rhs) {
-        return std::tie(lhs.substringRank, lhs.distance, lhs.candidate.name)
-             < std::tie(rhs.substringRank, rhs.distance, rhs.candidate.name);
-    });
-    std::vector<SubosInfo> result;
-    for (std::size_t i = 0; i < std::min<std::size_t>(3, scored.size()); ++i) {
-        result.push_back(std::move(scored[i].candidate));
-    }
-    return result;
-}
-
-CandidateResolution_ resolve_candidate_(std::string_view query) {
-    auto all = candidate_view(false).candidates;
-    if (query.empty()) {
-        return {.reason = "missing_name", .candidates = std::move(all)};
-    }
-
-    if (auto exact = std::ranges::find(all, query, &SubosInfo::name);
-        exact != all.end()) {
-        return {.selected = exact->name,
-                .reason = "exact",
-                .candidates = {*exact}};
-    }
-
-    const auto loweredQuery = lowercase_name_(query);
-    std::vector<SubosInfo> matches;
-    for (const auto& candidate : all) {
-        if (lowercase_name_(candidate.name) == loweredQuery) {
-            matches.push_back(candidate);
-        }
-    }
-    if (matches.size() == 1) {
-        return {.selected = matches.front().name,
-                .reason = "case_insensitive_exact",
-                .candidates = std::move(matches),
-                .autoSelected = true};
-    }
-    if (matches.size() > 1) {
-        return {.reason = "ambiguous", .candidates = std::move(matches)};
-    }
-
-    for (const auto& candidate : all) {
-        if (lowercase_name_(candidate.name).starts_with(loweredQuery)) {
-            matches.push_back(candidate);
-        }
-    }
-    if (matches.size() == 1) {
-        return {.selected = matches.front().name,
-                .reason = "unique_prefix",
-                .candidates = std::move(matches),
-                .autoSelected = true};
-    }
-    if (matches.size() > 1) {
-        return {.reason = "ambiguous", .candidates = std::move(matches)};
-    }
-
-    return {.reason = "not_found",
-            .candidates = suggestions_(query, all)};
-}
-
-void emit_candidates_(EventStream& stream,
-                      const CandidateResolution_& resolution,
-                      std::string_view query,
-                      std::string_view hint = {}) {
-    nlohmann::json candidates = nlohmann::json::array();
-    for (const auto& candidate : resolution.candidates) {
-        candidates.push_back({
-            {"name", candidate.name},
-            {"active", candidate.isActive},
-            {"dir", candidate.dir.string()},
-            {"pkgCount", candidate.toolCount},
-        });
-    }
-    nlohmann::json payload;
-    payload["reason"] = resolution.reason;
-    payload["query"] = query;
-    payload["candidates"] = std::move(candidates);
-    payload["auto_selected"] = resolution.autoSelected;
-    if (!resolution.selected.empty()) payload["selected"] = resolution.selected;
-    if (!hint.empty()) payload["hint"] = hint;
-    stream.emit(DataEvent{"subos_candidates", payload.dump()});
-}
-
 struct UseNameResolution_ {
     std::string selected;
     int exitCode { 0 };
 };
 
-UseNameResolution_ resolve_use_name_(std::string_view query,
-                                    EventStream& stream) {
-    auto resolution = resolve_candidate_(query);
-    if (query.empty()) {
-        const auto hint = resolution.candidates.empty()
-            ? "Create: xlings subos new <name>"
-            : "Use: xlings subos use <name>";
-        emit_candidates_(stream, resolution, query, hint);
-        return {};
-    }
-    if (!resolution.selected.empty()) {
-        if (resolution.autoSelected) {
-            emit_candidates_(stream, resolution, query);
-        }
-        return {.selected = std::move(resolution.selected)};
-    }
-    if (resolution.reason == "ambiguous") {
-        emit_candidates_(stream, resolution, query);
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = std::format("subos name '{}' is ambiguous", query),
-            .recoverable = true,
-            .hint = "use one of the exact names listed above",
-        });
-        return {.exitCode = 2};
-    }
-
-    emit_candidates_(stream, resolution, query);
-    std::string nearest;
-    for (const auto& candidate : resolution.candidates) {
-        if (!nearest.empty()) nearest += ", ";
-        nearest += candidate.name;
-    }
-    stream.emit(ErrorEvent{
-        .code = ErrorCode::NotFound,
-        .message = std::format("subos '{}' not found", query),
-        .recoverable = true,
-        .hint = nearest.empty()
-            ? "create it first: xlings subos new " + std::string(query)
-            : "did you mean: " + nearest,
-    });
-    return {.exitCode = 1};
-}
-
-void update_current_symlink_(EventStream& stream,
-                              const fs::path& homeDir,
-                              const fs::path& targetDir) {
-    auto linkPath = homeDir / "subos" / "current";
-    std::error_code ec;
-    fs::remove(linkPath, ec);
-    // The same helper `self init` uses to create this link, rather than
-    // `fs::create_directory_symlink` directly. On Windows a symlink needs
-    // developer mode or elevation and a junction does not, so the two spellings
-    // disagree exactly there: init would lay down a junction and every later
-    // switch would fail to replace it, leaving `subos/current` pointing at
-    // whatever was active the day the home was created -- while `subos list`
-    // reported the switch as done.
-    if (!platform::create_directory_link(linkPath, targetDir)) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::Permission,
-            .message = std::format("failed to update current symlink: {}",
-                                   Config::display_path(linkPath)),
-            .recoverable = true,
-        });
-    }
-}
-
-// ─────────────────────────────────────────────────────────────────────
-// Sandbox subos helpers (0.4.23 V4 — see .agents/docs/sandbox-v4-design.md)
-//
-// V4 model: sandbox is NOT a creation property of subos. It's a `use`
-// modifier — `xlings subos use <name> --sandbox` enters the same subos
-// via proot fs-isolation, with sandbox-private $HOME / /tmp / /etc and
-// host-shared ~/.xlings / /usr / /lib*. Real user identity (no fake
-// root). Shell is whatever $SHELL is. Prompt switches from
-// `[xsubos:<name>]` to `<xsubos:<name>>` to signal sandbox mode.
-//
-// Helpers here:
-//   - sandbox::init_sandbox_dirs_ — lazy-init the per-subos
-//     sandbox dirs (<subos>/{home/<user>, tmp, etc/...}) at first
-//     `subos use --sandbox`. Idempotent.
-//   - sandbox::locate_proot_ — search for the proot binary
-//     (defined later, alongside build_proot_argv_).
-//   - sandbox::build_proot_argv_ — assemble the proot CLI for
-//     entering the sandbox (defined later).
-//
-// Note: V1.1-V1.3 (`--sandbox-shell <xpkg>`, `sandbox-shell` /
-// `sandbox-shell-xpkg` config fields, eager shell install at
-// create-time) was removed in V4. Old sandboxes still in user homes
-// retain those fields; V4 silently ignores them, and `subos use
-// --sandbox` works on them because init_sandbox_dirs_ is idempotent.
-// ─────────────────────────────────────────────────────────────────────
-
-
-// Give a subos directory a `subos_info` block, or leave the one it has.
-//
-// Idempotent, and called from every path that produces a subos directory
-// (create, new_from, and the migration of a subos made before this block
-// existed). A subos without it violates invariant I4 and cannot be described,
-// checked or entered with its environment.
-//
-// The block is added even when `.xlings.json` already exists, which is the
-// difference from the surrounding code: the file predates the block, so
-// "the file is there" does not mean "the subos describes itself".
-bool ensure_subos_info_(const fs::path& dir, std::string_view runtime) {
-    auto json = read_config_json_(dir / ".xlings.json");
-    if (!json.is_object()) json = nlohmann::json::object();
-    if (!json.contains("workspace")) json["workspace"] = nlohmann::json::object();
-
-    // Only replace a block that is absent or unusable. Rewriting a valid one
-    // would discard the envs a package declared into it.
-    if (manifest::validate_block(json).empty()) return true;
-
-    // An unusable block can still carry a valid runtime binding, and that
-    // binding — not the caller's fallback — is what the subos was declared
-    // against. preserved_runtime keeps it through the rebuild.
-    json[std::string(manifest::BLOCK)] = manifest::make_block(
-        manifest::preserved_runtime(json, runtime),
-        std::format("xlings {}", Info::VERSION),
-        platform::host_glibc_version());
-    try {
-        write_config_json_(dir / ".xlings.json", json);
-    } catch (const std::exception& e) {
-        log::error("failed to write subos manifest {}: {}",
-                   (dir / ".xlings.json").string(), e.what());
-        return false;
-    }
-    return true;
-}
-
 // Create a subos. V6: storage mode is a creation-time property
 // (`--storage image|tmpfs|shared`). Non-shared modes force sandbox
 // entry at use-time. The sandbox-private dirs are laid down lazily.
@@ -398,257 +85,16 @@ bool ensure_subos_info_(const fs::path& dir, std::string_view runtime) {
 export int create(const std::string& name, const fs::path& customDir,
                   sandbox::StorageMode storage, const std::string& imageSize,
                   const std::string& runtime,
-                  EventStream& stream) {
-    auto& p = Config::paths();
-
-    if (name == "current") {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = "'current' is a reserved subos name",
-            .recoverable = false,
-        });
-        return 1;
-    }
-
-    // Checked before anything is laid down. A malformed runtime that only
-    // surfaced at write time would leave a registered subos that cannot
-    // satisfy its own invariants.
-    const std::string effectiveRuntime =
-        runtime.empty() ? std::string(manifest::DEFAULT_RUNTIME) : runtime;
-    if (!manifest::is_binding(effectiveRuntime)) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = "invalid --runtime '" + effectiveRuntime
-                       + "' (expected <package>@<version>, e.g. glibc@2.39)",
-            .recoverable = false,
-        });
-        return 1;
-    }
-
-    for (char c : name) {
-        if (!std::isalnum(static_cast<unsigned char>(c)) && c != '_' && c != '-') {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::InvalidInput,
-                .message = "invalid subos name: '" + name
-                           + "' (allowed: alphanumeric, underscore, dash)",
-                .recoverable = false,
-            });
-            return 1;
-        }
-    }
-
-    // Cheap pre-check so the common "already exists" mistake fails before we
-    // lay down directories or run mkfs. It is advisory only -- the binding
-    // check that actually decides is the one inside the locked commit below.
-    if (read_home_config(p.homeDir).value("subos", nlohmann::json::object())
-            .contains(name)) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = "subos '" + name + "' already exists",
-            .recoverable = false,
-        });
-        return 1;
-    }
-
-    auto dir = customDir.empty() ? (p.homeDir / "subos" / name) : customDir;
-
-    fs::create_directories(dir / "bin");
-    fs::create_directories(dir / "lib");
-    fs::create_directories(dir / "usr");
-    fs::create_directories(dir / "generations");
-
-    auto subosConfig = dir / ".xlings.json";
-    if (!fs::exists(subosConfig)) {
-        nlohmann::json j;
-        j["workspace"] = nlohmann::json::object();
-        if (storage != sandbox::StorageMode::Shared)
-            j["storage"] = sandbox::storage_to_string_(storage);
-        if (storage == sandbox::StorageMode::Image)
-            j["imageSize"] = imageSize;
-        j[std::string(manifest::BLOCK)] = manifest::make_block(
-            effectiveRuntime, std::format("xlings {}", Info::VERSION),
-            platform::host_glibc_version());
-        write_config_json_(subosConfig, j);
-    } else if (!ensure_subos_info_(dir, effectiveRuntime)) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::Internal,
-            .message = "failed to write the subos manifest for '" + name + "'",
-            .recoverable = false,
-            .hint = "check write permission on " + subosConfig.string(),
-        });
-        return 1;
-    }
-
-    // Image mode: create sparse ext4 image
-    if (storage == sandbox::StorageMode::Image) {
-        auto rc = sandbox::init_image_(dir / "home.img", imageSize);
-        if (rc != 0) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::Internal,
-                .message = "failed to create home.img",
-                .recoverable = false,
-                .hint = "ensure mkfs.ext4 is available (e2fsprogs)",
-            });
-            return 1;
-        }
-        fs::create_directories(dir / ".mountpoint");
-    }
-
-    // Create shim hardlinks from xlings binary
-    auto xlingsBin = p.homeDir / "xlings";
-    if (!fs::exists(xlingsBin))
-        xlingsBin = p.homeDir / "bin" / "xlings";
-    if (fs::exists(xlingsBin)) {
-        if (xself::ensure_subos_shims(dir / "bin", xlingsBin, p.homeDir) != 0) {
-            log::warn("some shims could not be written into {}; commands may "
-                      "not resolve inside this subos", (dir / "bin").string());
-        }
-    }
-
-    // Everything above this point -- mkfs.ext4 for image storage in
-    // particular -- can take seconds. Reading the config before it and
-    // writing it after would put back a document that predates any install
-    // that finished meanwhile. Re-read under the lock and edit only our key.
-    bool raced = false;
-    auto committed = update_home_config(p.homeDir, [&](nlohmann::json& json) {
-        if (!json.contains("subos") || !json["subos"].is_object()) {
-            json["subos"] = nlohmann::json::object();
-        }
-        if (json["subos"].contains(name)) {
-            raced = true;
-            return false;
-        }
-        json["subos"][name] =
-            {{"dir", customDir.empty() ? "" : customDir.string()}};
-        return true;
-    });
-    if (!committed) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::Internal,
-            .message = "subos '" + name + "' was created on disk but could "
-                       "not be recorded: " + committed.error(),
-            .recoverable = true,
-            .hint = "retry once the other xlings finishes; the directory at "
-                    + dir.string() + " is reused as-is",
-        });
-        return 1;
-    }
-    if (raced) {
-        // Another xlings registered this name while we were building. Its
-        // entry is the one on disk; ours would overwrite a directory the
-        // other command is using.
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = "subos '" + name + "' already exists",
-            .recoverable = false,
-        });
-        return 1;
-    }
-
-    // The subos is registered; check it can actually satisfy the invariants
-    // before saying so. A creation that reports success and leaves a subos
-    // that doctor immediately condemns is the failure mode this whole slice
-    // exists to remove -- "it happened" and "it worked" must not look alike.
-    if (auto findings = manifest::validate(dir); !findings.empty()) {
-        std::string detail;
-        for (const auto& f : findings) {
-            if (!detail.empty()) detail += "; ";
-            detail += std::string(manifest::describe(f.kind));
-            if (!f.detail.empty()) detail += " (" + f.detail + ")";
-        }
-        // Roll back to the state before the command: the registry entry first,
-        // since that is what makes the name unusable a second time.
-        (void)update_home_config(p.homeDir, [&](nlohmann::json& json) {
-            if (json.contains("subos") && json["subos"].is_object())
-                json["subos"].erase(name);
-            return true;
-        });
-        std::error_code rmec;
-        fs::remove_all(dir, rmec);
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::Internal,
-            .message = "subos '" + name + "' did not come out valid: " + detail,
-            .recoverable = false,
-            .hint = rmec
-                ? "rolled back the registry entry, but " + dir.string()
-                  + " could not be removed -- delete it before retrying"
-                : "nothing was left behind; retry, or report this",
-        });
-        return 1;
-    }
-
-    // A declared runtime is installed, not merely recorded.
-    //
-    // `--runtime glibc@2.39` names what this subos runs on. Writing it to the
-    // manifest and stopping there leaves the subos empty, and the first
-    // package to arrive decides the actual glibc — a subos declaring 2.39 ends
-    // up on 2.44 because something's `>=2.38` resolved higher. The flag then
-    // describes an intention the subos does not hold, which is worse than not
-    // having the flag: it reads as a guarantee.
-    //
-    // Only when asked. `subos new` without --runtime stays what it was, a
-    // local directory operation that cannot fail on a network — the default
-    // subos that `self install` creates goes through that path.
-    if (!runtime.empty()) {
-        // Both, and that is not belt-and-braces. The override is what
-        // recomputes Config's cached paths, and XLINGS_ACTIVE_SUBOS is what
-        // the activation path re-reads for itself. Setting only the override
-        // put the payload in the right subos and then reported
-        // "'glibc' is not installed in this subos" from the reader that had
-        // not been told — a command that succeeds narrating a failure.
-        auto prevEnv = utils::get_env_or_default("XLINGS_ACTIVE_SUBOS");
-        platform::set_env_variable("XLINGS_ACTIVE_SUBOS", name);
-        auto prev = Config::set_active_subos_override(name);
-        std::vector<std::string> targets{effectiveRuntime};
-        // useAfterInstall stays FALSE. The payload is usually already in the
-        // store — another subos has it — so cmd_install takes its
-        // "already installed" path, and the activation that flag triggers
-        // runs before the registration for THIS subos has landed. It fails,
-        // prints three [error] lines and a [warn], and the subos ends up
-        // correct anyway. A command that succeeds must not narrate a failure.
-        const int rc = xim::cmd_install(targets, /*yes=*/true,
-                                        /*noDeps=*/false, stream);
-        (void)Config::set_active_subos_override(prev);
-        platform::set_env_variable("XLINGS_ACTIVE_SUBOS", prevEnv);
-        if (rc != 0) {
-            // The subos exists and is valid; it just does not have what it
-            // says it runs on. Reported rather than rolled back, because the
-            // directory is usable and deleting it would throw away a
-            // successful create over a failed download.
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::Internal,
-                .message = "subos '" + name + "' was created but its declared "
-                           "runtime " + effectiveRuntime
-                           + " could not be installed",
-                .recoverable = true,
-                .hint = "run: xlings subos use " + name
-                        + " && xlings install " + effectiveRuntime,
-            });
-            return rc;
-        }
-    }
-
-    nlohmann::json payload;
-    payload["name"] = name;
-    payload["dir"]  = dir.string();
-    payload["storage"] = sandbox::storage_to_string_(storage);
-    payload["runtime"] = effectiveRuntime;
-    stream.emit(DataEvent{"subos_created", payload.dump()});
-    return 0;
-}
+                  EventStream& stream);
 
 // Back-compat overloads. Callers that predate the runtime argument get the
 // built-in default, and callers that predate storage get shared as before.
 export int create(const std::string& name, const fs::path& customDir,
                   sandbox::StorageMode storage, const std::string& imageSize,
-                  EventStream& stream) {
-    return create(name, customDir, storage, imageSize, "", stream);
-}
+                  EventStream& stream);
 
 export int create(const std::string& name, const fs::path& customDir,
-                  EventStream& stream) {
-    return create(name, customDir, sandbox::StorageMode::Shared, "50G", "", stream);
-}
+                  EventStream& stream);
 
 // ─────────────────────────────────────────────────────────────────────
 // M2: subos new --from <spec>
@@ -672,10 +118,6 @@ export int create(const std::string& name, const fs::path& customDir,
 // Refs: .agents/docs/subos-as-xpkg-design-2026-05-16.md (M2, E1-E5).
 namespace new_from_detail_ {
 
-bool is_pkg_spec_(const std::string& spec) {
-    return spec.find(':') != std::string::npos || spec.find('@') != std::string::npos;
-}
-
 // Parse `[<ns>:]<name>[@<ver>]` → {ns, name, ver}. Empty ns if absent;
 // empty ver if absent ("latest" semantics handled downstream).
 struct PkgRef {
@@ -684,257 +126,12 @@ struct PkgRef {
     std::string ver;
 };
 
-PkgRef parse_pkg_spec_(const std::string& spec) {
-    PkgRef r;
-    std::string rest = spec;
-    if (auto colon = rest.find(':'); colon != std::string::npos) {
-        r.ns = rest.substr(0, colon);
-        rest = rest.substr(colon + 1);
-    }
-    if (auto at = rest.find('@'); at != std::string::npos) {
-        r.name = rest.substr(0, at);
-        r.ver  = rest.substr(at + 1);
-    } else {
-        r.name = rest;
-    }
-    return r;
-}
-
-// Recursive directory copy with reflink/clonefile preferred where the
-// filesystem supports COW. Falls back to full byte-copy. Excludes the
-// caller's xlings binary shims (those are minted fresh in the target).
-int copy_tree_(const fs::path& src, const fs::path& dst,
-               EventStream& stream) {
-    std::error_code ec;
-    fs::create_directories(dst, ec);
-    if (ec) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::Internal,
-            .message = "failed to create fork target dir: " + ec.message(),
-            .recoverable = false,
-        });
-        return 1;
-    }
-
-    // Use the system cp with reflink/clonefile flags; falls back to
-    // full copy when the FS doesn't support it. Skip the bin/ subtree
-    // here — shims are regenerated below.
-    std::string copy_cmd;
-#if defined(__linux__)
-    // cp -a preserves mode/ownership/timestamps; --reflink=auto uses
-    // COW where available (btrfs/xfs) and full copy otherwise.
-    copy_cmd = std::format(
-        "cp -a --reflink=auto '{}/.' '{}/'", src.string(), dst.string());
-#elif defined(__APPLE__)
-    // APFS clonefile via /bin/cp -c
-    copy_cmd = std::format("cp -ac '{}/.' '{}/'", src.string(), dst.string());
-#endif
-
-    if (!copy_cmd.empty()) {
-        auto rc = std::system(copy_cmd.c_str());
-        if (rc != 0) {
-            log::warn("cp -a/--reflink failed (rc={}), falling back to "
-                      "std::filesystem::copy", rc);
-            fs::copy(src, dst,
-                     fs::copy_options::recursive |
-                     fs::copy_options::overwrite_existing |
-                     fs::copy_options::copy_symlinks, ec);
-            if (ec) {
-                stream.emit(ErrorEvent{
-                    .code = ErrorCode::Internal,
-                    .message = "fork copy failed: " + ec.message(),
-                    .recoverable = false,
-                });
-                return 1;
-            }
-        }
-    } else {
-        // Windows / generic
-        fs::copy(src, dst,
-                 fs::copy_options::recursive |
-                 fs::copy_options::overwrite_existing |
-                 fs::copy_options::copy_symlinks, ec);
-        if (ec) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::Internal,
-                .message = "fork copy failed: " + ec.message(),
-                .recoverable = false,
-            });
-            return 1;
-        }
-    }
-    return 0;
-}
-
-// Locate xpkgs/<ns>-x-<name>/<ver>/ for a parsed pkg ref. Returns empty
-// path if no matching install exists.
-fs::path locate_base_pkg_(const PkgRef& ref) {
-    auto& p = Config::paths();
-    auto storeName = ref.ns.empty() ? ref.name : (ref.ns + "-x-" + ref.name);
-    auto base = p.dataDir / "xpkgs" / storeName;
-    if (!fs::is_directory(base)) return {};
-
-    // Specific version requested
-    if (!ref.ver.empty()) {
-        auto candidate = base / ref.ver;
-        return fs::is_directory(candidate) ? candidate : fs::path{};
-    }
-
-    // No version → take the highest-sorted installed version directory.
-    fs::path latest;
-    std::error_code ec;
-    for (auto it = fs::directory_iterator(base, ec);
-         !ec && it != std::default_sentinel; it.increment(ec)) {
-        if (it->is_directory(ec)) latest = it->path();
-    }
-    return latest;
-}
-
 } // namespace new_from_detail_
 
 export int new_from(const std::string& name, const fs::path& customDir,
                     sandbox::StorageMode storage, const std::string& imageSize,
                     const std::string& fromSpec, const std::string& runtime,
-                    EventStream& stream) {
-    auto& p = Config::paths();
-
-    fs::path baseDir;
-
-    if (new_from_detail_::is_pkg_spec_(fromSpec)) {
-        // ── pkg-spec path: locate or install the base xpkg ────────────
-        auto ref = new_from_detail_::parse_pkg_spec_(fromSpec);
-        baseDir = new_from_detail_::locate_base_pkg_(ref);
-
-        if (baseDir.empty()) {
-            // Auto-install (E5a): invoke `xlings install <spec>` so the
-            // base lands at xpkgs/<ns>-x-<name>/<ver>/. We use the host
-            // xlings binary (same process binary) so the install runs
-            // with the same context (XLINGS_HOME, mirror config, etc.).
-            log::info("base subos pkg '{}' not installed; auto-installing...",
-                      fromSpec);
-            auto xlings_bin = p.homeDir / "xlings";
-            if (!fs::exists(xlings_bin))
-                xlings_bin = p.homeDir / "bin" / "xlings";
-
-            auto cmd = std::format("{} install -y {}",
-                                   xlings_bin.string(), fromSpec);
-            auto rc = std::system(cmd.c_str());
-            if (rc != 0) {
-                stream.emit(ErrorEvent{
-                    .code = ErrorCode::Internal,
-                    .message = "auto-install of base '" + fromSpec
-                               + "' failed",
-                    .recoverable = true,
-                    .hint = "run manually: xlings install " + fromSpec,
-                });
-                return 1;
-            }
-            baseDir = new_from_detail_::locate_base_pkg_(ref);
-        }
-
-        if (baseDir.empty()) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::NotFound,
-                .message = "couldn't locate base pkg payload for '" + fromSpec
-                           + "' after install",
-                .recoverable = false,
-            });
-            return 1;
-        }
-    } else {
-        // ── local fork path: source is an existing subos by name ──────
-        baseDir = p.homeDir / "subos" / fromSpec;
-        if (!fs::is_directory(baseDir)) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::NotFound,
-                .message = "source subos '" + fromSpec + "' not found",
-                .recoverable = true,
-                .hint = "list available: xlings subos list",
-            });
-            return 1;
-        }
-    }
-
-    // Validate base shape: must contain .xlings.json for fork to make sense
-    if (!fs::is_regular_file(baseDir / ".xlings.json")) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = "source '" + fromSpec
-                       + "' has no .xlings.json (not a valid fork source)",
-            .recoverable = false,
-        });
-        return 1;
-    }
-
-    // Create target subos via standard `create`. This sets up
-    // bin/lib/usr/generations, writes initial .xlings.json, optionally
-    // creates home.img, and registers the subos.
-    if (auto rc = create(name, customDir, storage, imageSize, runtime, stream);
-        rc != 0) {
-        return rc;
-    }
-
-    auto dstDir = customDir.empty() ? (p.homeDir / "subos" / name) : customDir;
-
-    // Overlay base content on top — workspace (.xlings.json), any
-    // templates/static files. We re-issue create()'s file writes
-    // afterwards for storage/imageSize keys so the new subos's own
-    // storage choice wins over the base's. The base's .xlings.json
-    // workspace map is the data we want to inherit.
-    if (auto rc = new_from_detail_::copy_tree_(baseDir, dstDir, stream); rc != 0) {
-        return rc;
-    }
-
-    // Restore storage/imageSize fields in target's .xlings.json since
-    // copy_tree_ overwrote it with base's version (base usually has no
-    // explicit storage key — it inherits at fork time).
-    auto subosCfgPath = dstDir / ".xlings.json";
-    auto subosCfg = read_config_json_(subosCfgPath);
-    if (storage != sandbox::StorageMode::Shared)
-        subosCfg["storage"] = sandbox::storage_to_string_(storage);
-    else
-        subosCfg.erase("storage");
-    if (storage == sandbox::StorageMode::Image)
-        subosCfg["imageSize"] = imageSize;
-    else
-        subosCfg.erase("imageSize");
-    // Same restoration, same reason. copy_tree_ replaced the manifest create()
-    // wrote with the base's, and a base built before subos_info existed has
-    // none -- which would leave the fork registered and failing its own
-    // invariants. A base that does carry one keeps it: it describes the very
-    // content that was just copied in, envs included.
-    if (!subosCfg.contains("workspace"))
-        subosCfg["workspace"] = nlohmann::json::object();
-    if (!manifest::validate_block(subosCfg).empty()) {
-        subosCfg[std::string(manifest::BLOCK)] = manifest::make_block(
-            manifest::preserved_runtime(
-                subosCfg,
-                runtime.empty() ? manifest::DEFAULT_RUNTIME : runtime),
-            std::format("xlings {}", Info::VERSION),
-            platform::host_glibc_version());
-    }
-    write_config_json_(subosCfgPath, subosCfg);
-
-    // Re-mint subos shims (they may have been clobbered by copy_tree_
-    // if base happened to ship its own bin/ — defensive).
-    auto xlingsBin = p.homeDir / "xlings";
-    if (!fs::exists(xlingsBin))
-        xlingsBin = p.homeDir / "bin" / "xlings";
-    if (fs::exists(xlingsBin)) {
-        if (xself::ensure_subos_shims(dstDir / "bin", xlingsBin, p.homeDir) != 0) {
-            log::warn("some shims could not be written into {}; commands may "
-                      "not resolve inside this subos", (dstDir / "bin").string());
-        }
-    }
-
-    nlohmann::json payload;
-    payload["name"]    = name;
-    payload["from"]    = fromSpec;
-    payload["base"]    = baseDir.string();
-    payload["storage"] = sandbox::storage_to_string_(storage);
-    stream.emit(DataEvent{"subos_forked", payload.dump()});
-    return 0;
-}
+                    EventStream& stream);
 
 // `xlings subos use` modes:
 //
@@ -1229,195 +426,6 @@ inline void apply_subos_env_(const std::string& name) {
     }
 }
 
-} // namespace use_detail_
-
-// Internal — not exported. `xlings subos use --global <name>` and
-// the back-compat single-arg `use()` both route here.
-int use_global(const std::string& name, EventStream& stream) {
-    if (auto rc = use_detail_::validate_subos_(name, stream); rc != 0) return rc;
-
-    auto& p = Config::paths();
-    // The window here is short, but a full-document rewrite is a full-document
-    // rewrite: an install committing between the read and the write loses its
-    // `versions` entry all the same.
-    auto committed = update_home_config(p.homeDir, [&](nlohmann::json& json) {
-        json["activeSubos"] = name;
-        return true;
-    });
-    if (!committed) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::Internal,
-            .message = "failed to switch subos: " + committed.error(),
-            .recoverable = true,
-        });
-        return 1;
-    }
-
-    auto dir = Config::subos_dir(name);
-    update_current_symlink_(stream, p.homeDir, dir);
-
-    nlohmann::json payload;
-    payload["name"] = name;
-    payload["dir"]  = dir.string();
-    stream.emit(DataEvent{"subos_switched", payload.dump()});
-    return 0;
-}
-
-// Internal — not exported. Powers the hidden `--shell <kind>` flag,
-// kept available for tests and power users that want eval-able output
-// without a sub-shell layer. The default user-facing path is
-// use_spawn_shell; --shell is intentionally not in the help text.
-// Shell-level entry never activates storage isolation (V4 orthogonality
-// — see use_spawn_shell). Emit a single hint to stderr if the subos
-// was created with image/tmpfs storage so the user understands the
-// attribute is dormant in this entry. Writes to stderr (not stdout)
-// so the --shell <kind> path stays eval-safe.
-// `--sandbox` without `--gpu` on a machine that has one, for a subos that does
-// graphics: say so, once, before entering.
-//
-// bwrap's `--dev` builds a fresh /dev from a hard-coded whitelist that does not
-// include /dev/nvidia*, /dev/dri or /dev/dxg, so a sandbox without `--gpu` is a
-// software-rendering environment by construction. That default is CORRECT --
-// device passthrough should be a decision someone takes, not something a tool
-// does quietly -- and `--gpu` genuinely restores it: measured, GLX and Vulkan
-// come back byte-identical to the unsandboxed subos.
-//
-// So the gap is not capability, it is silence. Without the flag the user gets
-// "runs, draws a window, exits 0", indistinguishable from the GPU case except
-// in frame rate. That is this stack's whole failure mode: succeeding at the
-// wrong thing without saying so.
-//
-// THREE conditions, and the narrowness is the point. `warn_storage_dormant_on_
-// shell_` a few lines below is a hint that fired on every entry of its kind,
-// became noise, and is now commented out -- a hint that cannot be acted on is
-// worse than none. This one can only fire where acting on it changes the
-// outcome:
-//
-//   * the subos has a GL dispatch -- a subos that does no graphics is not
-//     missing anything (read, not probed: same state file `subos info` reads)
-//   * the host actually has GPU device nodes -- on a machine with no GPU,
-//     `--gpu` would expose nothing and the advice would be false
-//   * `--gpu` was not passed -- the user who asked does not need telling
-void warn_sandbox_without_gpu_(const std::string& name, bool gpu,
-                               EventStream& stream) {
-    if (gpu) return;
-    auto w = xlings::subos::graphics::read_graphics_wiring(Config::subos_dir(name));
-    if (!w.has_dispatch()) return;
-    if (!xlings::subos::gpu::host_has_gpu_devices()) return;
-    stream.emit(DataEvent{"tip", nlohmann::json{
-        {"message",
-         "this subos has a GL stack but the sandbox exposes no GPU device; "
-         "GL will render in software. Add --gpu to pass the host's GPU through."}
-    }.dump()});
-}
-
-void warn_storage_dormant_on_shell_(const std::string& name) {
-    auto& p = Config::paths();
-    auto storage = sandbox::read_storage_mode_(p.homeDir / "subos" / name);
-    if (storage == sandbox::StorageMode::Shared) return;
-    // Hint disabled: wording was ambiguous ("use --sandbox to activate"
-    // reads as either the verb or the `subos use` command) and it fired
-    // on every shell-level entry for image/tmpfs subos, becoming noise
-    // once the user already knows the layout. Revisit with a clearer
-    // one-time / opt-in form before re-enabling.
-    // std::println(stderr,
-    //              "[xlings] storage={} is sandbox-only; entering "
-    //              "shell-level (use --sandbox to activate)",
-    //              sandbox::storage_to_string_(storage));
-    (void)storage;
-}
-
-int use_emit_shell(const std::string& name,
-                          std::string_view shell_kind,
-                          EventStream& stream) {
-    if (auto rc = use_detail_::validate_subos_(name, stream); rc != 0) return rc;
-    warn_storage_dormant_on_shell_(name);
-
-    auto& p = Config::paths();
-    auto bin_dir = p.homeDir / "subos" / name / "bin";
-
-    bool is_fish = (shell_kind == "fish");
-    bool is_pwsh = (shell_kind == "pwsh" || shell_kind == "powershell" ||
-                    shell_kind == "ps1" || shell_kind == "ps");
-
-    // The subos's own declared environment (GL driver paths, EGL vendor dirs,
-    // and whatever else a package needs a *user's* binary to see). Emitted
-    // after the xvm/PATH lines so a declaration cannot displace them.
-    //
-    // UC-1 -- a variable the user already exported wins. The emitted code
-    // tests the live variable rather than what this process happens to see:
-    // `--shell` output is frequently captured once and eval'd later, in a
-    // shell whose environment has moved on.
-    const auto envVars = use_detail_::subos_env_for_(name);
-    use_detail_::report_injected_env_(name, envVars);
-
-    if (is_fish) {
-        std::println(R"(set -gx XLINGS_ACTIVE_SUBOS "{}";)", name);
-        std::println(R"(set -gx XLINGS_BIN "{}";)", bin_dir.string());
-        // Strip any old subos bin segments from PATH, then prepend the new
-        // bin. fish's $PATH is a list, so we use string match -v.
-        std::println(R"(set -gx PATH "{}" (string match -v -r "^{}/subos/[^/]+/bin$" -- $PATH);)",
-                     bin_dir.string(), p.homeDir.string());
-        for (const auto& v : envVars) {
-            if (v.unresolved) continue;
-            // R"SH(...)SH": the fish source below contains `)"`, which ends a
-            // plain R"(...)" literal early -- and the truncation compiles,
-            // because what is left is still a valid string.
-            if (v.op == manifest::OP_PREPEND) {
-                std::println(
-                    R"SH(if set -q {0}; set -gx {0} "{1}:${0}"; else; set -gx {0} "{1}"; end;)SH",
-                    v.var, v.value);
-            } else {
-                std::println(R"SH(if not set -q {0}; set -gx {0} "{1}"; end;)SH",
-                             v.var, v.value);
-            }
-        }
-        return 0;
-    }
-    if (is_pwsh) {
-        std::println(R"($env:XLINGS_ACTIVE_SUBOS = '{}')", name);
-        std::println(R"($env:XLINGS_BIN = '{}')", bin_dir.string());
-        std::println(R"($env:Path = '{}' + ';' + (($env:Path -split ';') -notmatch '^{}\\subos\\[^\\]+\\bin$' -join ';'))",
-                     bin_dir.string(), p.homeDir.string());
-        for (const auto& v : envVars) {
-            if (v.unresolved) continue;
-            // ';' rather than ':' -- these are path lists, and on Windows the
-            // separator is the one the platform's own tools split on.
-            if (v.op == manifest::OP_PREPEND) {
-                std::println(
-                    R"($env:{0} = if ($env:{0}) {{ '{1}' + ';' + $env:{0} }} else {{ '{1}' }})",
-                    v.var, v.value);
-            } else {
-                // `$null -eq`, not `-not`: PowerShell's `-not` is true for an
-                // empty string too, which would overwrite a value the user
-                // deliberately set to "".
-                std::println(R"(if ($null -eq $env:{0}) {{ $env:{0} = '{1}' }})",
-                             v.var, v.value);
-            }
-        }
-        return 0;
-    }
-    // POSIX (sh/bash/zsh) default
-    auto orig_path = utils::get_env_or_default("PATH");
-    auto new_path  = use_detail_::rebuild_path_for_subos_(
-        orig_path, p.homeDir, bin_dir);
-    std::println(R"(export XLINGS_ACTIVE_SUBOS="{}";)", name);
-    std::println(R"(export XLINGS_BIN="{}";)", bin_dir.string());
-    std::println(R"(export PATH="{}";)", new_path);
-    for (const auto& v : envVars) {
-        if (v.unresolved) continue;
-        if (v.op == manifest::OP_PREPEND) {
-            // ${VAR:+:$VAR} appends the separator only when VAR is non-empty,
-            // so an unset variable does not become a trailing ':' -- which an
-            // empty PATH-list element reads as "the current directory".
-            std::println(R"(export {0}="{1}${{{0}:+:${0}}}";)", v.var, v.value);
-        } else {
-            // `${VAR=v}`, NOT `${VAR:=v}`. The colon form also assigns when VAR
-            // is set-but-empty, which would overwrite a value the user chose.
-            std::println(R"(: "${{{0}={1}}}"; export {0};)", v.var, v.value);
-        }
-    }
-    return 0;
 }
 
 
@@ -1448,624 +456,17 @@ int use_spawn_shell(const std::string& name, EventStream& stream,
                     bool sandbox = false,
                     const std::string& sandbox_backend = "",
                     bool gpu = false,
-                    const std::string& cmd = "")
-{
-    // V5: --sandbox [backend] is a `use`-time modifier. Dispatch to the
-    // sandbox path when set; auto-detect backend (bwrap preferred, proot
-    // fallback) or use the explicitly requested one.
-    //
-    // Storage mode (image/tmpfs) and sandbox are orthogonal axes per
-    // V4 design: shell-level entry only swaps env/PATH and never
-    // mounts. Image / tmpfs only take effect when `--sandbox` is
-    // explicitly passed — earlier V6 auto-upgrade fused the two axes
-    // and made `subos use <image-subos>` silently require root, bwrap,
-    // and a working mount namespace just to switch shells.
-    //
-    // M3: `cmd` non-empty switches to non-interactive single-command
-    // execution — `shell -c <cmd>` instead of an interactive shell.
-    // Useful for scripts and agent workflows.
-    if (sandbox) {
-        // Before entering, not inside: the sandbox module cannot import this
-        // one (this one imports it), and proot/bwrap pass our environment
-        // through to the shell anyway. The home is bound at its own absolute
-        // path, so the payload paths in these values mean the same thing on
-        // both sides of the boundary.
-        if (auto rc = use_detail_::validate_subos_(name, stream); rc != 0) return rc;
-        use_detail_::apply_subos_env_(name);
-        warn_sandbox_without_gpu_(name, gpu, stream);
-        return sandbox::enter(name, stream, sandbox_backend, gpu, cmd);
-    }
-    warn_storage_dormant_on_shell_(name);
-
-    if (auto rc = use_detail_::validate_subos_(name, stream); rc != 0) return rc;
-
-    auto already = utils::get_env_or_default("XLINGS_ACTIVE_SUBOS");
-    if (already == name) {
-        nlohmann::json p; p["name"] = name;
-        stream.emit(DataEvent{"subos_already_in", p.dump()});
-        return 0;
-    }
-    if (!already.empty()) {
-        nlohmann::json p; p["from"] = already; p["to"] = name;
-        stream.emit(DataEvent{"subos_nesting", p.dump()});
-    }
-
-    auto& p = Config::paths();
-    auto bin_dir = p.homeDir / "subos" / name / "bin";
-
-    auto orig_path = utils::get_env_or_default("PATH");
-    auto new_path  = use_detail_::rebuild_path_for_subos_(
-        orig_path, p.homeDir, bin_dir);
-
-    // Set env BEFORE spawning so the child shell inherits it. The profile
-    // sourced by the child reads XLINGS_ACTIVE_SUBOS and re-computes
-    // XLINGS_BIN; XLINGS_BIN we set here is mostly defensive (covers the
-    // case where the child shell is started with --norc and never sources
-    // the profile).
-    platform::set_env_variable("XLINGS_ACTIVE_SUBOS", name);
-    platform::set_env_variable("XLINGS_BIN", bin_dir.string());
-    // E2a: the subos's library farm, DECLARED rather than derivable.
-    //
-    // Two consumers need it and neither should have to guess. The linker
-    // wrapper in the binutils payload writes it into `-rpath-link` (and, when
-    // not opted out, `-rpath`) so a program built in here can find the
-    // libraries it just linked against; mcpp reads it to know which directory
-    // to strip back out at pack time. Both reading one declaration is the
-    // difference between a contract and two derivations of the same decision
-    // that drift.
-    //
-    // `XLINGS_BIN` + "/../lib" would work today and is exactly the coincidence
-    // this replaces: it is true because of how the farm happens to be laid
-    // out, not because anything promised it.
-    platform::set_env_variable(
-        "XLINGS_SUBOS_LIB",
-        (p.homeDir / "subos" / name / "lib").string());
-    platform::set_env_variable("PATH", new_path);
-
-    // The subos's declared environment, applied to this process before it is
-    // replaced -- so the shell (or the single `--cmd`) inherits it, and so
-    // does every user binary run inside. This is the path that matters for
-    // issue #352: nothing xlings wraps needs LIBGL_DRIVERS_PATH, the user's
-    // own GL program does.
-    //
-    // UC-1 -- a variable already set in this environment is the user's, and
-    // `set` leaves it alone. `prepend` still contributes, since composing is
-    // what prepend means.
-    use_detail_::apply_subos_env_(name);
-
-    nlohmann::json payload;
-    payload["name"] = name;
-    payload["mode"] = "spawn";
-    stream.emit(DataEvent{"subos_entering", payload.dump()});
-
-    // Flush std streams before exec/CreateProcess — buffered output isn't
-    // preserved across execve(2), and on Windows the child shell may start
-    // writing before the parent's pending output drains; in either case
-    // CI capture (where stdout is a pipe rather than a TTY) loses any
-    // block-buffered bytes that didn't get flushed.
-    std::cout.flush();
-    std::cerr.flush();
-
-    return platform::run_shell(cmd, cmd.empty());
-}
+                    const std::string& cmd = "");
 
 // Back-compat single-arg entry point: keeps existing callers (anyone who
 // imports xlings::subos::use directly) on the legacy global behavior.
 // CLI dispatch goes through `run()` which uses the flag-aware path below.
-export int use(const std::string& name, EventStream& stream) {
-    auto resolved = resolve_use_name_(name, stream);
-    if (resolved.selected.empty()) return resolved.exitCode;
-    return use_global(resolved.selected, stream);
-}
-
-export int remove(const std::string& name, EventStream& stream) {
-    if (name == "default") {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = "cannot remove the 'default' subos",
-            .recoverable = false,
-        });
-        return 1;
-    }
-
-    auto& p = Config::paths();
-    if (p.activeSubos == name) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = "cannot remove the active subos '" + name + "'",
-            .recoverable = true,
-            .hint = "switch first: xlings subos use default",
-        });
-        return 1;
-    }
-
-    if (!read_home_config(p.homeDir).value("subos", nlohmann::json::object())
-             .contains(name)) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::NotFound,
-            .message = "subos '" + name + "' not found",
-            .recoverable = true,
-        });
-        return 1;
-    }
-
-    auto dir = Config::subos_dir(name);
-    if (fs::exists(dir)) {
-        // V6: image-storage subos has an ext4 mount at <subos>/.mountpoint.
-        // remove_all would either (a) hit EBUSY at the mountpoint, leaving
-        // a half-cleaned tree behind, or (b) silently recurse into the
-        // live mount and erase the image's contents before EBUSY surfaces.
-        // Detect and umount first.
-#if defined(__linux__)
-        auto mountpoint = dir / ".mountpoint";
-        if (fs::exists(mountpoint)
-            && sandbox::is_mounted_(mountpoint))
-        {
-            if (sandbox::unmount_image_(mountpoint) != 0) {
-                stream.emit(ErrorEvent{
-                    .code = ErrorCode::Permission,
-                    .message = "failed to unmount " + mountpoint.string()
-                               + " (image storage subos); refusing to "
-                                 "remove to avoid corrupting the live "
-                                 "filesystem",
-                    .recoverable = true,
-                    .hint = "ensure no shell is inside this subos, then "
-                            "retry — or manually: sudo umount "
-                            + mountpoint.string(),
-                });
-                return 1;
-            }
-        }
-#endif
-        std::error_code ec;
-        fs::remove_all(dir, ec);
-        if (ec) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::Permission,
-                .message = "failed to remove " + dir.string() + ": " + ec.message(),
-                .recoverable = false,
-            });
-            return 1;
-        }
-    }
-
-    // remove_all above walks the whole subos tree and can run for a long
-    // time on a big one. Deleting our key out of a document read before that
-    // walk would resurrect every other key's pre-walk value.
-    auto committed = update_home_config(p.homeDir, [&](nlohmann::json& json) {
-        if (!json.contains("subos") || !json["subos"].is_object()) return false;
-        return json["subos"].erase(name) > 0;
-    });
-    if (!committed) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::Internal,
-            .message = "subos '" + name + "' was deleted from disk but its "
-                       "entry could not be removed: " + committed.error(),
-            .recoverable = true,
-            .hint = "retry once the other xlings finishes",
-        });
-        return 1;
-    }
-
-    nlohmann::json payload;
-    payload["name"] = name;
-    stream.emit(DataEvent{"subos_removed", payload.dump()});
-    return 0;
-}
-
-export std::optional<SubosInfo> info(const std::string& name) {
-    auto& p = Config::paths();
-    auto dir = Config::subos_dir(name);
-    if (!fs::exists(dir)) return std::nullopt;
-
-    int toolCount = 0;
-    auto binDir = dir / "bin";
-    if (fs::exists(binDir)) {
-        for (auto& e : platform::dir_entries(binDir)) {
-            auto stem = e.path().stem().string();
-            if (!xself::is_builtin_shim(stem) && stem != "xvm-alias")
-                ++toolCount;
-        }
-    }
-    return SubosInfo{name, dir, p.activeSubos == name, toolCount};
-}
-
-int run_list_(EventStream& stream) {
-    auto all = candidate_view().candidates;
-    std::vector<std::tuple<std::string, std::string, int, bool>> entries;
-    for (auto& s : all) {
-        entries.emplace_back(s.name, s.dir.string(), s.toolCount, s.isActive);
-    }
-    nlohmann::json entriesJson = nlohmann::json::array();
-    for (auto& [n, d, tc, active] : entries) {
-        entriesJson.push_back({{"name", n}, {"dir", d}, {"pkgCount", tc}, {"active", active}});
-    }
-    nlohmann::json payload;
-    payload["entries"] = std::move(entriesJson);
-    stream.emit(DataEvent{"subos_list", payload.dump()});
-    return 0;
-}
-
-// The graphics section of `xlings subos info`.
-//
-// This is the ONLY channel the wiring verdict has. It was designed as the
-// second one: the graphics recipe logs a warning for every vendor it finds
-// broken, and that seemed sufficient. Measured on a real install — the config
-// hook's log does not surface on the success path at all, not the new
-// warnings and not the stack's own long-standing "GL renders on the GPU"
-// banner. A user whose NVIDIA vendor cannot load is told nothing, anywhere,
-// unless they run this command.
-//
-// Empty when the subos has no GL dispatch, so `subos info` is unchanged for
-// every subos that does no graphics — which is most of them.
-nlohmann::json graphics_fields_(const fs::path& subosDir) {
-    namespace gfx = xlings::subos::graphics;
-    auto w = gfx::read_graphics_wiring(subosDir);
-    nlohmann::json out = nlohmann::json::array();
-    if (!w.has_dispatch()) return out;
+export int use(const std::string& name, EventStream& stream);
 
-    auto row = [&](std::string label, std::string value, bool alert) {
-        out.push_back({{"label", std::move(label)}, {"value", std::move(value)},
-                       {"highlight", false}, {"alert", alert}});
-    };
-
-    row("GL dispatch", w.dispatchDir.string(), false);
-
-    switch (w.status) {
-    case gfx::WiringStatus::NoVendors:
-        // The failure this whole mechanism exists to remove, and the one case
-        // that needs no record to detect: glvnd with nothing to dispatch to
-        // falls back to software rendering and reports success.
-        row("vendors",
-            "NONE REGISTERED — every GL program in this subos falls back to "
-            "software rendering. Run 'xlings install graphics' to wire it.",
-            true);
-        return out;
-    case gfx::WiringStatus::Unrecorded:
-        row("vendors",
-            std::to_string(w.vendorFiles) + " registered, but this stack was "
-            "wired before xlings recorded whether they load. Re-run "
-            "'xlings install graphics' to check them.",
-            true);
-        return out;
-    default:
-        break;
-    }
+export int remove(const std::string& name, EventStream& stream);
 
-    // The one part of this stack we do not own is the host's NVIDIA driver,
-    // and it moves: a distribution update replaces it, the versioned SONAMEs
-    // our payload links to change, and the wiring below describes a driver
-    // that is no longer there. The detector already existed and worked
-    // (`xlings-gl-doctor`); what it lacked was a way to reach the user without
-    // being remembered. Reported before the per-vendor rows because when it
-    // fires, every row under it is about the old driver.
-    if (auto d = gfx::read_driver_stamp(w.dispatchDir / "lib" /
-                                        std::string(gfx::kVendorSubdir));
-        d.drifted()) {
-        row("host driver",
-            "CHANGED — this stack was wired for " + d.builtFor +
-            " and the host is now running " + d.hostNow +
-            ". Re-run 'xlings install graphics'; until then the states below "
-            "describe a driver that is no longer loaded.",
-            true);
-    }
+export std::optional<SubosInfo> info(const std::string& name);
 
-    if (w.dispatchMismatch) {
-        // The record describes libraries nobody in this subos will load.
-        // Reporting their states as this subos's would be a confident wrong
-        // answer, so say that first and keep the states clearly attributed.
-        row("stale wiring",
-            "recorded against " + w.recordedDispatch + ", which is not the "
-            "dispatch this subos loads. The states below may describe a "
-            "different stack — re-run 'xlings install graphics'.",
-            true);
-    }
-
-    for (const auto& v : w.vendors) {
-        auto lbl = gfx::label_for(v.soname);
-        auto label = lbl ? lbl->vendor + " " + lbl->api : v.soname;
-        // `needs-transitive-consumer` is marked too: it is not a failure for
-        // installed programs, but it IS the answer to "why does the GL app I
-        // just compiled render in software", and that question is why someone
-        // reads this panel.
-        row(std::move(label), gfx::describe(v),
-            v.stale || v.is_broken() || v.needs_transitive_consumer());
-    }
-    return out;
-}
-
-int run_info_(const std::string& name, EventStream& stream) {
-    auto& p = Config::paths();
-    auto target = name.empty() ? p.activeSubos : name;
-    auto si = info(target);
-    if (!si) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::NotFound,
-            .message = "subos '" + target + "' not found",
-            .recoverable = true,
-        });
-        return 1;
-    }
-    nlohmann::json fieldsJson = nlohmann::json::array();
-    fieldsJson.push_back({{"label", "active"}, {"value", si->isActive ? "yes" : "no"}, {"highlight", si->isActive}});
-    fieldsJson.push_back({{"label", "dir"}, {"value", si->dir.string()}, {"highlight", false}});
-    fieldsJson.push_back({{"label", "tools"}, {"value", std::to_string(si->toolCount)}, {"highlight", false}});
-    nlohmann::json payload;
-    payload["title"] = si->name;
-    payload["fields"] = std::move(fieldsJson);
-    auto gfx = graphics_fields_(si->dir);
-    if (!gfx.empty()) payload["extra_fields"] = std::move(gfx);
-    stream.emit(DataEvent{"info_panel", payload.dump()});
-    return 0;
-}
-
-export int run(int argc, char* argv[], EventStream& stream) {
-    // Drop the options root publishes as valid on every command before any
-    // subcommand's argv loop sees them. `subos new` and `subos use` end their
-    // loops with a catch-all `usageError`, so a documented global flag such as
-    // `--yes` -- which an agent is instructed to always pass -- would come
-    // back as "unknown option" from a command that has nothing to confirm.
-    std::vector<char*> filtered;
-    filtered.reserve(static_cast<std::size_t>(argc));
-    for (int i = 0; i < argc; ++i) {
-        if (i >= 3 && cli::spec::is_global_option(argv[i])) continue;
-        filtered.push_back(argv[i]);
-    }
-    argc = static_cast<int>(filtered.size());
-    argv = filtered.data();
-
-    if (argc < 3) return run_list_(stream);
-
-    std::string sub = argv[2];
-    if (sub == "ls") sub = "list";
-    if (sub == "rm") sub = "remove";
-    if (sub == "i")  sub = "info";
-
-    auto usageError = [&](std::string_view detail) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = std::string(detail),
-            .recoverable = false,
-            .hint = "usage: xlings subos <new|use|list|ls|remove|rm|info|i|stop> [name]",
-        });
-    };
-
-    if (sub == "new") {
-        if (argc < 4) { usageError("missing <name> for: xlings subos new"); return 1; }
-        // Parse: xlings subos new <name> [--storage <mode>] [--image-size <size>] [--from <spec>]
-        std::string name;
-        sandbox::StorageMode storage = sandbox::StorageMode::Shared;
-        std::string imageSize = "50G";
-        // M2: --from <spec> creates the new subos by forking an existing
-        // source. Spec containing `:` or `@` is treated as a pkg-spec
-        // (auto-installs the base xpkg if missing); bare name is treated
-        // as a local subos to fork from.
-        std::string fromSpec;
-        // --runtime <binding>: what this subos's binaries are built against
-        // ("glibc@2.39"). Creation-time, because changing it later would
-        // invalidate every payload already installed. Absent → the built-in
-        // default, so existing invocations keep working unchanged.
-        std::string runtime;
-        for (int i = 3; i < argc; ++i) {
-            std::string a = argv[i];
-            if (a == "--runtime" && i + 1 < argc) {
-                runtime = argv[++i];
-            }
-            else if (a.rfind("--runtime=", 0) == 0) {
-                runtime = a.substr(10);
-            }
-            else if (a == "--storage" && i + 1 < argc) {
-                auto s = std::string(argv[++i]);
-                if (s == "image") storage = sandbox::StorageMode::Image;
-                else if (s == "tmpfs") storage = sandbox::StorageMode::Tmpfs;
-                else if (s == "shared") storage = sandbox::StorageMode::Shared;
-                else {
-                    usageError("unknown storage mode: " + s
-                               + " (valid: shared, image, tmpfs)");
-                    return 1;
-                }
-            }
-            else if (a == "--image-size" && i + 1 < argc) {
-                imageSize = argv[++i];
-            }
-            else if (a == "--from" && i + 1 < argc) {
-                fromSpec = argv[++i];
-            }
-            else if (a.rfind("--from=", 0) == 0) {
-                fromSpec = a.substr(7);
-            }
-            else if (!a.empty() && a[0] != '-' && name.empty()) {
-                name = std::move(a);
-            }
-            else {
-                usageError("unknown option for `xlings subos new`: " + a);
-                return 1;
-            }
-        }
-        if (name.empty()) {
-            usageError("missing <name> for: xlings subos new");
-            return 1;
-        }
-        if (!fromSpec.empty()) {
-            return new_from(name, {}, storage, imageSize, fromSpec, runtime, stream);
-        }
-        return create(name, {}, storage, imageSize, runtime, stream);
-    }
-    if (sub == "use") {
-        // Flags supported:
-        //   --global         persist the choice into ~/.xlings.json + symlink
-        //                    (legacy behavior; affects every shell)
-        //   --shell <kind>   emit shell code on stdout for the user to
-        //                    eval/Invoke-Expression. <kind> ∈ {sh,bash,zsh,
-        //                    fish,pwsh}. Defaults to "sh" if not provided.
-        //   --sandbox        Linux-only: enter via proot fs-isolation. $HOME,
-        //                    /tmp, /etc/passwd are sandbox-private; ~/.xlings,
-        //                    /usr, /lib*, /etc/{resolv.conf,ld.so.cache} are
-        //                    bound from host. Same shell (`$SHELL`) as outside.
-        //                    Prompt switches from `[xsubos:<name>]` to
-        //                    `<xsubos:<name>>` so the user can tell at a glance.
-        //   (no flag)        spawn a fresh interactive shell with
-        //                    XLINGS_ACTIVE_SUBOS=<name> in env. Per-shell.
-        std::string name;
-        std::string mode = "spawn";        // default
-        std::string shell_kind = "sh";
-        bool sandbox = false;
-        std::string sandbox_backend;       // "" = auto, "bwrap", "proot"
-        // M3: --cmd <string> runs a single command non-interactively
-        // and exits with the command's exit code. Works in both shell-
-        // level and sandbox modes. Internally routed to `sh -c <cmd>`
-        // (POSIX) or `pwsh -Command <cmd>` / `cmd /c <cmd>` (Windows).
-        std::string cmd;
-        // M5: explicit keeper policy overrides (D9). The runtime auto-
-        // default (storage=image|tmpfs + sandbox + Linux → keeper on,
-        // TTL=5min) is encoded in keeper::should_auto_keeper. These
-        // flags let the user override per call:
-        //   --no-keep      force disable (one-shot, even if auto would)
-        //   --keep         never-expiring (use until `subos stop`)
-        //   --ttl <sec>    custom idle TTL
-        bool no_keep = false;
-        bool keep_forever = false;
-        int  ttl_sec = 0;                  // 0 = use default
-        // --gpu: opt-in NVIDIA + DRM device passthrough for bwrap
-        // sandbox. Missing devices are silently skipped. Requires
-        // --sandbox; ignored when the backend resolves to proot (proot
-        // already passes /dev and /sys through wholesale).
-        // Ref: .agents/docs/2026-05-22-subos-sandbox-gpu-passthrough.md
-        bool gpu = false;
-        for (int i = 3; i < argc; ++i) {
-            std::string a = argv[i];
-            if (a == "--global") { mode = "global"; }
-            else if (a == "--shell") {
-                mode = "shell";
-                if (i + 1 < argc && argv[i + 1][0] != '-') {
-                    shell_kind = argv[++i];
-                }
-            }
-            else if (a.rfind("--shell=", 0) == 0) {
-                mode = "shell";
-                shell_kind = a.substr(8);
-            }
-            else if (a == "--sandbox") {
-                sandbox = true;
-                // Optional backend argument: --sandbox bwrap | --sandbox proot
-                if (i + 1 < argc) {
-                    std::string next = argv[i + 1];
-                    if (next == "bwrap" || next == "proot") {
-                        sandbox_backend = next;
-                        ++i;
-                    }
-                }
-            }
-            else if (a == "--cmd" && i + 1 < argc) {
-                cmd = argv[++i];
-            }
-            else if (a.rfind("--cmd=", 0) == 0) {
-                cmd = a.substr(6);
-            }
-            // M5 keeper policy flags. The runtime spawning of the keeper
-            // is wired separately (see keeper.cppm); these flags are
-            // accepted on the CLI and threaded through for forward
-            // compatibility. Auto-default (D9) is governed by
-            // should_auto_keeper() at runtime.
-            else if (a == "--no-keep") {
-                no_keep = true;
-            }
-            else if (a == "--keep") {
-                keep_forever = true;
-            }
-            else if (a == "--ttl" && i + 1 < argc) {
-                try { ttl_sec = std::stoi(argv[++i]); }
-                catch (...) {
-                    usageError("--ttl expects an integer (seconds)");
-                    return 1;
-                }
-            }
-            else if (a.rfind("--ttl=", 0) == 0) {
-                try { ttl_sec = std::stoi(std::string(a.substr(6))); }
-                catch (...) {
-                    usageError("--ttl=<sec> expects an integer");
-                    return 1;
-                }
-            }
-            else if (a == "--gpu") {
-                gpu = true;
-            }
-            else if (!a.empty() && a[0] != '-' && name.empty()) {
-                name = std::move(a);
-            }
-            else {
-                usageError("unknown option for `xlings subos use`: " + a);
-                return 1;
-            }
-        }
-        if (no_keep && keep_forever) {
-            usageError("--no-keep and --keep are mutually exclusive");
-            return 1;
-        }
-
-        if (gpu && !sandbox) {
-            usageError("--gpu requires --sandbox "
-                       "(GPU passthrough only applies to bwrap-sandboxed sessions)");
-            return 1;
-        }
-
-        // No name is a request to SEE the candidates -- but only when the rest
-        // of the command asked for nothing else. Every other flag here names an
-        // effect: run this command, emit this shell code, persist this choice,
-        // enter this sandbox. Listing candidates and exiting 0 in their place
-        // reports success for work that never happened, and `--shell` makes it
-        // worse than a no-op: that stdout is eval'd by the caller, so a table
-        // lands where shell code was expected.
-        //
-        // The acceptance path for this whole release is
-        // `subos use <name> --sandbox --cmd ...`; a typo there has to fail, not
-        // print a list and return 0.
-        const bool discoveryOnly = mode == "spawn" && cmd.empty()
-            && !sandbox && !gpu && !no_keep && !keep_forever && ttl_sec == 0;
-        if (name.empty() && !discoveryOnly) {
-            usageError("missing <name> for: xlings subos use "
-                       "(run `xlings subos use` with no other arguments to "
-                       "list candidates)");
-            return 1;
-        }
-
-        auto resolved = resolve_use_name_(name, stream);
-        if (resolved.selected.empty()) return resolved.exitCode;
-        name = std::move(resolved.selected);
-
-        if (mode == "global") {
-            if (!cmd.empty()) {
-                usageError("--cmd is incompatible with --global "
-                           "(--global persists the active subos but doesn't spawn a shell)");
-                return 1;
-            }
-            return use_global(name, stream);
-        }
-        if (mode == "shell") {
-            if (!cmd.empty()) {
-                usageError("--cmd is incompatible with --shell <kind> "
-                           "(--shell emits env code; use plain `subos use --cmd` for non-interactive exec)");
-                return 1;
-            }
-            return use_emit_shell(name, shell_kind, stream);
-        }
-        return use_spawn_shell(name, stream, sandbox, sandbox_backend, gpu, cmd);
-    }
-    if (sub == "list")   return run_list_(stream);
-    if (sub == "remove") {
-        if (argc < 4) { usageError("missing <name> for: xlings subos remove|rm"); return 1; }
-        return remove(argv[3], stream);
-    }
-    if (sub == "info")   return run_info_(argc > 3 ? argv[3] : "", stream);
-    if (sub == "stop") {
-        // M4/D9: stop the auto-keeper for a sandboxed subos.
-        // Safe to invoke even when no keeper is running — it's a no-op.
-        if (argc < 4) { usageError("missing <name> for: xlings subos stop"); return 1; }
-        return keeper::stop_keeper(argv[3]);
-    }
-
-    usageError("unknown subcommand: " + sub);
-    return 1;
-}
+export int run(int argc, char* argv[], EventStream& stream);
 
 } // namespace xlings::subos
diff --git a/src/core/subos/graphics.cpp b/src/core/subos/graphics.cpp
new file mode 100644
index 00000000..251758ff
--- /dev/null
+++ b/src/core/subos/graphics.cpp
@@ -0,0 +1,313 @@
+// What this subos will actually render GL through -- read, never measured.
+//
+// WHY A READER AND NOT A PROBE
+//
+// The graphics stack's failure mode is that it succeeds. glvnd dlopens each
+// vendor library by name; when one fails to load it falls through to the next
+// with no diagnostic, so a machine whose NVIDIA vendor cannot load still draws
+// a window, still prints a GL_RENDERER, and still exits 0 -- on llvmpipe. The
+// only difference a user can observe is frame rate.
+//
+// The stack's installer already answers this question: it has `readelf` and
+// `patchelf` in hand at wiring time, probes every entry point each vendor
+// ships, and writes the verdict next to what it wired (xim-pkgindex
+// `graphics.record_wiring`). That record is the answer. This module reads it.
+//
+// It deliberately does NOT re-derive it. Two reasons, and the second is the
+// one that bites:
+//
+//   * `xlings subos info` is a local query, and local queries answer instantly
+//     (2026.8.10.1). Shelling out to readelf per vendor library would put a
+//     dozen subprocesses behind a command that currently touches only the
+//     filesystem.
+//   * A second answerer to a question already answered is how this codebase
+//     produces contradictions -- the doctor/repairer predicate drift, the
+//     reporter that says one thing while the fixer does another. The installer
+//     probed with the tools present; a reader that re-probes on a machine
+//     where they are absent would report a DIFFERENT verdict for the same
+//     wiring, and neither would be wrong.
+//
+// WHY THE ANCHOR IS `<subos>/lib/libGLX.so.0`
+//
+// The vendor directory lives inside libglvnd's payload, not inside the subos,
+// and a home can hold several libglvnd payloads at once. Asking "which
+// libglvnd is in the store" is the wrong question -- the answer is per-subos.
+//
+// So the anchor is the same edge the dynamic loader walks: a GL program in
+// this subos loads `<subos>/lib/libGLX.so.0`, which is a symlink into exactly
+// one payload, and glvnd finds its vendors through that library's own RPATH,
+// which points at `<payload>/lib/glx-vendor`. Following the symlink is
+// therefore not a lookup heuristic; it is the runtime's own resolution, done
+// with `readlink` instead of `dlopen`.
+//
+// The subdirectory name is shared with the writer as
+// `graphics.GLX_VENDOR_SUBDIR` in xim-pkgindex/libs/graphics.lua. If it ever
+// moves, both sides move together, and the "no dispatch" branch below is what
+// a mismatch looks like -- absence, not a wrong answer.
+//
+// THREE KINDS OF ABSENCE
+//
+// An unwritten record is not a healthy stack, and it is not one condition:
+//
+//   NoDispatch  -- no libGLX.so.0 in the farm. This subos does no GL at all;
+//                  there is nothing to report and nothing wrong.
+//   NoVendors   -- dispatch present, vendor directory empty. THIS is the
+//                  software-rendering failure, and it is visible without any
+//                  record at all.
+//   Unrecorded  -- vendors present, no record. Wired by a graphics recipe
+//                  older than the probe; the wiring may be fine, we cannot
+//                  say. Saying "ok" here would be the silent-success bug in a
+//                  new place.
+//
+// Refs: .agents/docs/2026-08-10-graphics-stack-architecture-review-and-plan.md
+module xlings.core.subos.graphics;
+
+import std;
+
+namespace xlings::subos::graphics {
+
+ParsedRecord parse_wiring_record(std::string_view text) {
+    ParsedRecord rec;
+
+    for (auto rawLine : split_(text, '\n')) {
+        auto line = trim_(rawLine);
+        if (line.empty()) continue;
+
+        // `dispatch=` takes the whole rest of the line: it is a path, and a
+        // path may contain spaces. Every other key is token-separated.
+        if (line.starts_with("dispatch=")) {
+            rec.dispatch = std::string(trim_(line.substr(9)));
+            continue;
+        }
+        if (!line.starts_with("vendor=")) continue;
+
+        VendorWiring v;
+        // `payload=` takes the whole rest of the line, for the same reason
+        // `dispatch=` does: it is a path and a path may contain a space. The
+        // writer puts it last so this split is unambiguous.
+        if (auto at = line.find(" payload="); at != std::string_view::npos) {
+            v.payload = std::string(trim_(line.substr(at + 9)));
+            line = trim_(line.substr(0, at));
+        }
+        for (auto& tok : split_(line, ' ')) {
+            auto t = trim_(tok);
+            if (t.empty()) continue;
+            auto eq = t.find('=');
+            if (eq == std::string_view::npos) continue;
+            auto key = t.substr(0, eq);
+            auto val = t.substr(eq + 1);
+            if (key == "vendor")      v.soname = std::string(val);
+            else if (key == "state")  v.state  = std::string(val);
+            else if (key == "reason") v.reason = std::string(val);
+            else if (key == "missing") {
+                for (auto& m : split_(val, ',')) {
+                    auto mm = trim_(m);
+                    if (!mm.empty()) v.missing.emplace_back(mm);
+                }
+            }
+        }
+        // A line naming no library describes nothing. Dropping it keeps a
+        // truncated write (a crash mid-`io.writefile`) from rendering as a
+        // vendor with an empty name and an unknown state.
+        if (v.soname.empty()) continue;
+        // An unrecognized state must not read as a pass. `is_ok()` already
+        // fails closed, but naming it keeps the panel's text honest.
+        if (v.state.empty()) v.state = "unverified";
+        rec.vendors.push_back(std::move(v));
+    }
+    return rec;
+}
+
+GraphicsWiring read_graphics_wiring(const fs::path& subosDir) {
+    GraphicsWiring w;
+
+    std::error_code ec;
+    auto dispatchLib = subosDir / "lib" / fs::path(std::string(kDispatchLib));
+    // `symlink_status`, not `exists`: a farm entry pointing at a payload that
+    // has been removed is a DANGLING symlink. `exists` follows it and says
+    // no, which would report "this subos does no GL" about a subos that is
+    // wired to something that is gone -- a broken stack read as an absent one.
+    auto st = fs::symlink_status(dispatchLib, ec);
+    if (ec || st.type() == fs::file_type::not_found) return w;
+
+    auto resolved = fs::weakly_canonical(dispatchLib, ec);
+    if (ec) resolved = dispatchLib;
+    w.dispatchDir = resolved.parent_path().parent_path();   // <payload>/lib/x -> <payload>
+
+    auto vendorDir = resolved.parent_path() / fs::path(std::string(kVendorSubdir));
+
+    w.status = WiringStatus::NoVendors;
+    if (fs::is_directory(vendorDir, ec)) {
+        for (auto it = fs::directory_iterator(vendorDir, ec);
+             !ec && it != fs::directory_iterator(); it.increment(ec)) {
+            auto name = it->path().filename().string();
+            if (name.starts_with(".")) continue;   // the record itself
+            ++w.vendorFiles;
+        }
+    }
+
+    std::string text;
+    {
+        std::ifstream in(vendorDir / fs::path(std::string(kRecordName)),
+                         std::ios::binary);
+        if (in) {
+            in.seekg(0, std::ios::end);
+            auto sz = in.tellg();
+            if (sz > 0) {
+                text.resize(static_cast<std::size_t>(sz));
+                in.seekg(0, std::ios::beg);
+                in.read(text.data(), sz);
+                text.resize(static_cast<std::size_t>(in.gcount()));
+            }
+        }
+    }
+
+    if (text.empty()) {
+        // No record. Which absence it is depends on the directory, not on the
+        // file: an empty vendor directory is the software-rendering failure
+        // whether or not anything wrote a record.
+        if (w.vendorFiles > 0) w.status = WiringStatus::Unrecorded;
+        return w;
+    }
+
+    auto rec = parse_wiring_record(text);
+    w.recordedDispatch = rec.dispatch;
+    w.vendors = std::move(rec.vendors);
+    w.dispatchMismatch = !same_path_(rec.dispatch, w.dispatchDir);
+    recompute_staleness_(w.vendors, vendorDir);
+    // A record listing no vendor is not a record of a wired stack. Fall back
+    // to what the directory says rather than rendering an empty vendor table
+    // under a "recorded" heading.
+    w.status = w.vendors.empty()
+                   ? (w.vendorFiles > 0 ? WiringStatus::Unrecorded
+                                        : WiringStatus::NoVendors)
+                   : WiringStatus::Recorded;
+    return w;
+}
+
+DriverStamp read_driver_stamp(const fs::path& vendorDir) {
+    DriverStamp d;
+    std::error_code ec;
+    for (auto it = fs::directory_iterator(vendorDir, ec);
+         !ec && it != fs::directory_iterator(); it.increment(ec)) {
+        auto name = it->path().filename().string();
+        if (name.find("nvidia") == std::string::npos) continue;
+        auto real = fs::weakly_canonical(it->path(), ec);
+        if (ec) continue;
+        // <payload>/lib/<soname> -> <payload>
+        auto payload = real.parent_path().parent_path();
+        auto stamp = payload / ".host-driver-version";
+        if (!fs::exists(stamp, ec)) continue;
+        d.known = true;
+        d.builtFor = read_trimmed_(stamp);
+        break;
+    }
+    if (d.known) d.hostNow = read_trimmed_("/sys/module/nvidia/version");
+    return d;
+}
+
+std::optional<VendorLabel> label_for(std::string_view soname) {
+    struct Pat { std::string_view prefix, suffix, api; };
+    static constexpr Pat kPats[] = {
+        {"libGLX_",       ".so.0", "GLX"},
+        {"libEGL_",       ".so.0", "EGL"},
+        {"libGLESv1_CM_", ".so.1", "GLESv1"},
+        {"libGLESv2_",    ".so.2", "GLESv2"},
+    };
+    for (auto& p : kPats) {
+        if (soname.starts_with(p.prefix) && soname.ends_with(p.suffix)) {
+            auto mid = soname.substr(
+                p.prefix.size(), soname.size() - p.prefix.size() - p.suffix.size());
+            if (mid.empty()) continue;
+            return VendorLabel{std::string(mid), std::string(p.api)};
+        }
+    }
+    return std::nullopt;
+}
+
+std::string describe(const VendorWiring& v) {
+    // FIRST, and it replaces the recorded verdict rather than decorating it.
+    //
+    // A stale record's state is a measurement of a payload that is no longer
+    // what this subos loads. Printing "ok" with a footnote would leave the
+    // reassuring word on the screen, and the whole reason this field exists is
+    // that six confident `native` rows once described a stack wired to nothing.
+    if (v.stale) {
+        return "STALE — this verdict was measured against a payload that is "
+               "no longer the one in place (" + v.staleDetail +
+               "). Re-run 'xlings install graphics' to re-measure";
+    }
+    if (v.state == "native")
+        return "ok  (built by xlings — no host driver behind it)";
+    if (v.state == "ok")
+        return "ok  (the host driver behind it is reachable)";
+    if (v.state == "needs-transitive-consumer")
+        return "ok for installed programs — but a program you build here "
+               "cannot load it: your build gets DT_RUNPATH, which is not "
+               "transitive (see xlings#532). Installed packages get DT_RPATH "
+               "and reach the GPU through it";
+    if (v.state == "unverified")
+        return "unverified — the installer could not read this library; "
+               "if it is broken, GL renders elsewhere and says nothing";
+    if (v.state == "broken") {
+        std::string why = v.reason == "runpath-not-transitive"
+            ? "it carries DT_RUNPATH, which is not transitive, so the host "
+              "driver behind it reaches none of our payloads"
+            : (!v.missing.empty()
+                   ? "the host driver behind it needs " +
+                     [&] {
+                         std::string s;
+                         for (auto& m : v.missing) {
+                             if (!s.empty()) s += ", ";
+                             s += m;
+                         }
+                         return s;
+                     }() +
+                     ", which nothing on its search path provides"
+                   : (v.reason.empty() ? "the installer did not say why"
+                                       : v.reason));
+        return "BROKEN — " + why +
+               ". GL still renders, on a different driver, without saying so";
+    }
+    // A verdict this client has never heard of. The index ships independently
+    // of the client, so a newer recipe WILL reach an older xlings, and showing
+    // the bare word ("quarantined") would read as a state that is fine. Say
+    // that this xlings cannot interpret it, and what to do about that.
+    return "state '" + v.state + "' is newer than this xlings — upgrade to "
+           "read it; until then this vendor is unassessed";
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::subos::graphics {
+
+bool VendorWiring::is_broken() const { return state == "broken"; }
+
+bool VendorWiring::needs_transitive_consumer() const {
+    return state == "needs-transitive-consumer";
+}
+
+bool VendorWiring::is_ok() const {
+    return !stale && (state == "ok" || state == "native");
+}
+
+bool GraphicsWiring::has_dispatch() const { return status != WiringStatus::NoDispatch; }
+
+int GraphicsWiring::broken_count() const {
+    return static_cast<int>(std::ranges::count_if(
+        vendors, [](const VendorWiring& v) { return v.is_broken(); }));
+}
+
+bool DriverStamp::drifted() const {
+    // Only a DISAGREEMENT is drift. An unknown on either side is not:
+    // a machine whose module is not loaded right now (`hostNow` empty)
+    // has not changed driver, it has no driver running, and reporting
+    // that as drift would cry wolf on every laptop with the GPU asleep.
+    return known && !builtFor.empty() && !hostNow.empty()
+           && builtFor != hostNow;
+}
+
+} // namespace xlings::subos::graphics
diff --git a/src/core/subos/graphics.cppm b/src/core/subos/graphics.cppm
index b0be7f36..8ba82b71 100644
--- a/src/core/subos/graphics.cppm
+++ b/src/core/subos/graphics.cppm
@@ -93,7 +93,7 @@ struct VendorWiring {
     bool stale { false };
     std::string staleDetail;
 
-    bool is_broken() const { return state == "broken"; }
+    bool is_broken() const;
 
     // The verdict that depends on WHO OPENS IT.
     //
@@ -113,9 +113,7 @@ struct VendorWiring {
     // that is not there, and it hides the one that is — programs the user
     // builds are still DT_RUNPATH (#532), and this is exactly the state that
     // says so.
-    bool needs_transitive_consumer() const {
-        return state == "needs-transitive-consumer";
-    }
+    bool needs_transitive_consumer() const;
     // `native` means the probe found no host driver behind this vendor -- it
     // is one of our own builds, so there is no host closure to complete. That
     // is a pass, and it is NOT the same fact as `ok`, which means a host
@@ -126,9 +124,7 @@ struct VendorWiring {
     // production consumer of this module renders `describe()` -- which already
     // replaces the verdict -- so nothing changes; the point is that the next
     // caller cannot read `ok` off a record that has expired.
-    bool is_ok() const {
-        return !stale && (state == "ok" || state == "native");
-    }
+    bool is_ok() const;
 };
 
 enum class WiringStatus {
@@ -149,11 +145,8 @@ struct GraphicsWiring {
     int vendorFiles { 0 };              // entries in glx-vendor/, record excluded
     std::vector<VendorWiring> vendors;
 
-    bool has_dispatch() const { return status != WiringStatus::NoDispatch; }
-    int broken_count() const {
-        return static_cast<int>(std::ranges::count_if(
-            vendors, [](const VendorWiring& v) { return v.is_broken(); }));
-    }
+    bool has_dispatch() const;
+    int broken_count() const;
 };
 
 // ─── record parsing ────────────────────────────────────────────────────────
@@ -192,57 +185,7 @@ inline std::string_view trim_(std::string_view s) {
     return s;
 }
 
-ParsedRecord parse_wiring_record(std::string_view text) {
-    ParsedRecord rec;
-
-    for (auto rawLine : split_(text, '\n')) {
-        auto line = trim_(rawLine);
-        if (line.empty()) continue;
-
-        // `dispatch=` takes the whole rest of the line: it is a path, and a
-        // path may contain spaces. Every other key is token-separated.
-        if (line.starts_with("dispatch=")) {
-            rec.dispatch = std::string(trim_(line.substr(9)));
-            continue;
-        }
-        if (!line.starts_with("vendor=")) continue;
-
-        VendorWiring v;
-        // `payload=` takes the whole rest of the line, for the same reason
-        // `dispatch=` does: it is a path and a path may contain a space. The
-        // writer puts it last so this split is unambiguous.
-        if (auto at = line.find(" payload="); at != std::string_view::npos) {
-            v.payload = std::string(trim_(line.substr(at + 9)));
-            line = trim_(line.substr(0, at));
-        }
-        for (auto& tok : split_(line, ' ')) {
-            auto t = trim_(tok);
-            if (t.empty()) continue;
-            auto eq = t.find('=');
-            if (eq == std::string_view::npos) continue;
-            auto key = t.substr(0, eq);
-            auto val = t.substr(eq + 1);
-            if (key == "vendor")      v.soname = std::string(val);
-            else if (key == "state")  v.state  = std::string(val);
-            else if (key == "reason") v.reason = std::string(val);
-            else if (key == "missing") {
-                for (auto& m : split_(val, ',')) {
-                    auto mm = trim_(m);
-                    if (!mm.empty()) v.missing.emplace_back(mm);
-                }
-            }
-        }
-        // A line naming no library describes nothing. Dropping it keeps a
-        // truncated write (a crash mid-`io.writefile`) from rendering as a
-        // vendor with an empty name and an unknown state.
-        if (v.soname.empty()) continue;
-        // An unrecognized state must not read as a pass. `is_ok()` already
-        // fails closed, but naming it keeps the panel's text honest.
-        if (v.state.empty()) v.state = "unverified";
-        rec.vendors.push_back(std::move(v));
-    }
-    return rec;
-}
+ParsedRecord parse_wiring_record(std::string_view text);
 
 // ─── filesystem read ───────────────────────────────────────────────────────
 
@@ -328,72 +271,7 @@ inline void recompute_staleness_(std::vector<VendorWiring>& vendors,
     }
 }
 
-GraphicsWiring read_graphics_wiring(const fs::path& subosDir) {
-    GraphicsWiring w;
-
-    std::error_code ec;
-    auto dispatchLib = subosDir / "lib" / fs::path(std::string(kDispatchLib));
-    // `symlink_status`, not `exists`: a farm entry pointing at a payload that
-    // has been removed is a DANGLING symlink. `exists` follows it and says
-    // no, which would report "this subos does no GL" about a subos that is
-    // wired to something that is gone -- a broken stack read as an absent one.
-    auto st = fs::symlink_status(dispatchLib, ec);
-    if (ec || st.type() == fs::file_type::not_found) return w;
-
-    auto resolved = fs::weakly_canonical(dispatchLib, ec);
-    if (ec) resolved = dispatchLib;
-    w.dispatchDir = resolved.parent_path().parent_path();   // <payload>/lib/x -> <payload>
-
-    auto vendorDir = resolved.parent_path() / fs::path(std::string(kVendorSubdir));
-
-    w.status = WiringStatus::NoVendors;
-    if (fs::is_directory(vendorDir, ec)) {
-        for (auto it = fs::directory_iterator(vendorDir, ec);
-             !ec && it != fs::directory_iterator(); it.increment(ec)) {
-            auto name = it->path().filename().string();
-            if (name.starts_with(".")) continue;   // the record itself
-            ++w.vendorFiles;
-        }
-    }
-
-    std::string text;
-    {
-        std::ifstream in(vendorDir / fs::path(std::string(kRecordName)),
-                         std::ios::binary);
-        if (in) {
-            in.seekg(0, std::ios::end);
-            auto sz = in.tellg();
-            if (sz > 0) {
-                text.resize(static_cast<std::size_t>(sz));
-                in.seekg(0, std::ios::beg);
-                in.read(text.data(), sz);
-                text.resize(static_cast<std::size_t>(in.gcount()));
-            }
-        }
-    }
-
-    if (text.empty()) {
-        // No record. Which absence it is depends on the directory, not on the
-        // file: an empty vendor directory is the software-rendering failure
-        // whether or not anything wrote a record.
-        if (w.vendorFiles > 0) w.status = WiringStatus::Unrecorded;
-        return w;
-    }
-
-    auto rec = parse_wiring_record(text);
-    w.recordedDispatch = rec.dispatch;
-    w.vendors = std::move(rec.vendors);
-    w.dispatchMismatch = !same_path_(rec.dispatch, w.dispatchDir);
-    recompute_staleness_(w.vendors, vendorDir);
-    // A record listing no vendor is not a record of a wired stack. Fall back
-    // to what the directory says rather than rendering an empty vendor table
-    // under a "recorded" heading.
-    w.status = w.vendors.empty()
-                   ? (w.vendorFiles > 0 ? WiringStatus::Unrecorded
-                                        : WiringStatus::NoVendors)
-                   : WiringStatus::Recorded;
-    return w;
-}
+GraphicsWiring read_graphics_wiring(const fs::path& subosDir);
 
 // ─── host driver drift ─────────────────────────────────────────────────────
 //
@@ -420,14 +298,7 @@ struct DriverStamp {
     bool known { false };        // the payload recorded a version at install
     std::string builtFor;        // <nvidia payload>/.host-driver-version
     std::string hostNow;         // /sys/module/nvidia/version
-    bool drifted() const {
-        // Only a DISAGREEMENT is drift. An unknown on either side is not:
-        // a machine whose module is not loaded right now (`hostNow` empty)
-        // has not changed driver, it has no driver running, and reporting
-        // that as drift would cry wolf on every laptop with the GPU asleep.
-        return known && !builtFor.empty() && !hostNow.empty()
-               && builtFor != hostNow;
-    }
+    bool drifted() const;
 };
 
 inline std::string read_trimmed_(const fs::path& p) {
@@ -444,26 +315,7 @@ inline std::string read_trimmed_(const fs::path& p) {
 // symlink into the nvidia payload, so the payload root — and the stamp beside
 // it — is reached the same way everything else here is reached: by following
 // the link the loader would follow, not by searching the store.
-DriverStamp read_driver_stamp(const fs::path& vendorDir) {
-    DriverStamp d;
-    std::error_code ec;
-    for (auto it = fs::directory_iterator(vendorDir, ec);
-         !ec && it != fs::directory_iterator(); it.increment(ec)) {
-        auto name = it->path().filename().string();
-        if (name.find("nvidia") == std::string::npos) continue;
-        auto real = fs::weakly_canonical(it->path(), ec);
-        if (ec) continue;
-        // <payload>/lib/<soname> -> <payload>
-        auto payload = real.parent_path().parent_path();
-        auto stamp = payload / ".host-driver-version";
-        if (!fs::exists(stamp, ec)) continue;
-        d.known = true;
-        d.builtFor = read_trimmed_(stamp);
-        break;
-    }
-    if (d.known) d.hostNow = read_trimmed_("/sys/module/nvidia/version");
-    return d;
-}
+DriverStamp read_driver_stamp(const fs::path& vendorDir);
 
 // ─── display ───────────────────────────────────────────────────────────────
 //
@@ -476,75 +328,8 @@ struct VendorLabel {
     std::string api;      // GLX
 };
 
-std::optional<VendorLabel> label_for(std::string_view soname) {
-    struct Pat { std::string_view prefix, suffix, api; };
-    static constexpr Pat kPats[] = {
-        {"libGLX_",       ".so.0", "GLX"},
-        {"libEGL_",       ".so.0", "EGL"},
-        {"libGLESv1_CM_", ".so.1", "GLESv1"},
-        {"libGLESv2_",    ".so.2", "GLESv2"},
-    };
-    for (auto& p : kPats) {
-        if (soname.starts_with(p.prefix) && soname.ends_with(p.suffix)) {
-            auto mid = soname.substr(
-                p.prefix.size(), soname.size() - p.prefix.size() - p.suffix.size());
-            if (mid.empty()) continue;
-            return VendorLabel{std::string(mid), std::string(p.api)};
-        }
-    }
-    return std::nullopt;
-}
+std::optional<VendorLabel> label_for(std::string_view soname);
 
-std::string describe(const VendorWiring& v) {
-    // FIRST, and it replaces the recorded verdict rather than decorating it.
-    //
-    // A stale record's state is a measurement of a payload that is no longer
-    // what this subos loads. Printing "ok" with a footnote would leave the
-    // reassuring word on the screen, and the whole reason this field exists is
-    // that six confident `native` rows once described a stack wired to nothing.
-    if (v.stale) {
-        return "STALE — this verdict was measured against a payload that is "
-               "no longer the one in place (" + v.staleDetail +
-               "). Re-run 'xlings install graphics' to re-measure";
-    }
-    if (v.state == "native")
-        return "ok  (built by xlings — no host driver behind it)";
-    if (v.state == "ok")
-        return "ok  (the host driver behind it is reachable)";
-    if (v.state == "needs-transitive-consumer")
-        return "ok for installed programs — but a program you build here "
-               "cannot load it: your build gets DT_RUNPATH, which is not "
-               "transitive (see xlings#532). Installed packages get DT_RPATH "
-               "and reach the GPU through it";
-    if (v.state == "unverified")
-        return "unverified — the installer could not read this library; "
-               "if it is broken, GL renders elsewhere and says nothing";
-    if (v.state == "broken") {
-        std::string why = v.reason == "runpath-not-transitive"
-            ? "it carries DT_RUNPATH, which is not transitive, so the host "
-              "driver behind it reaches none of our payloads"
-            : (!v.missing.empty()
-                   ? "the host driver behind it needs " +
-                     [&] {
-                         std::string s;
-                         for (auto& m : v.missing) {
-                             if (!s.empty()) s += ", ";
-                             s += m;
-                         }
-                         return s;
-                     }() +
-                     ", which nothing on its search path provides"
-                   : (v.reason.empty() ? "the installer did not say why"
-                                       : v.reason));
-        return "BROKEN — " + why +
-               ". GL still renders, on a different driver, without saying so";
-    }
-    // A verdict this client has never heard of. The index ships independently
-    // of the client, so a newer recipe WILL reach an older xlings, and showing
-    // the bare word ("quarantined") would read as a state that is fine. Say
-    // that this xlings cannot interpret it, and what to do about that.
-    return "state '" + v.state + "' is newer than this xlings — upgrade to "
-           "read it; until then this vendor is unassessed";
-}
+std::string describe(const VendorWiring& v);
 
 } // namespace xlings::subos::graphics
diff --git a/src/core/subos/keeper.cppm b/src/core/subos/keeper.cppm
index f6f43983..ba72e4f3 100644
--- a/src/core/subos/keeper.cppm
+++ b/src/core/subos/keeper.cppm
@@ -44,7 +44,6 @@ export module xlings.core.subos.keeper;
 
 import std;
 import xlings.core.config;
-import xlings.core.log;
 
 export namespace xlings::subos::keeper {
 
diff --git a/src/core/subos/manifest.cpp b/src/core/subos/manifest.cpp
new file mode 100644
index 00000000..2d8aeae7
--- /dev/null
+++ b/src/core/subos/manifest.cpp
@@ -0,0 +1,482 @@
+module xlings.core.subos.manifest;
+
+import std;
+import xlings.libs.json;
+import xlings.platform;
+
+namespace xlings::subos::manifest {
+
+std::string family_of(std::string_view runtime, std::string_view arch) {
+    const auto at   = runtime.find('@');
+    const auto name = runtime.substr(0, at == std::string_view::npos
+                                        ? runtime.size() : at);
+    if (name == "glibc")     return std::format("linux-{}-glibc", arch);
+    if (name == "musl")      return std::format("linux-{}-musl", arch);
+    if (name == "wasi-libc") return "wasm32-wasi";
+    if (name == "macos_sdk") return std::format("darwin-{}", arch);
+    if (name == "ucrt")      return std::format("windows-{}-ucrt", arch);
+    return "unknown";
+}
+
+bool is_binding(std::string_view s) {
+    const auto at = s.find('@');
+    return at != std::string_view::npos && at > 0 && at + 1 < s.size();
+}
+
+std::string_view binding_name(std::string_view binding) {
+    const auto at = binding.find('@');
+    return at == std::string_view::npos ? binding : binding.substr(0, at);
+}
+
+std::string_view binding_version(std::string_view binding) {
+    const auto at = binding.find('@');
+    return at == std::string_view::npos ? std::string_view{}
+                                        : binding.substr(at + 1);
+}
+
+std::vector<DuplicateBinding> duplicate_bindings(const Info& info) {
+    std::map<std::string, std::vector<std::string>> byName;
+    for (const auto& p : info.envs) {
+        if (!is_binding(p.binding)) continue;
+        byName[std::string(binding_name(p.binding))].push_back(p.binding);
+    }
+    std::vector<DuplicateBinding> out;
+    for (auto& [name, bindings] : byName) {
+        if (bindings.size() < 2) continue;
+        std::ranges::sort(bindings);
+        bindings.erase(std::ranges::unique(bindings).begin(), bindings.end());
+        if (bindings.size() < 2) continue;   // one version listed twice is not two
+        out.push_back({.name = name, .bindings = std::move(bindings)});
+    }
+    return out;
+}
+
+std::map<std::string, std::string> active_versions(const nlohmann::json& doc) {
+    std::map<std::string, std::string> out;
+    if (!doc.contains("workspace") || !doc["workspace"].is_object()) return out;
+    for (auto it = doc["workspace"].begin(); it != doc["workspace"].end(); ++it) {
+        if (!it.value().is_object()) continue;
+        auto active = it.value().value("active", std::string{});
+        if (!active.empty()) out[it.key()] = std::move(active);
+    }
+    return out;
+}
+
+std::optional<RuntimeActivationMismatch>
+check_runtime_activation(const Info& info,
+                         std::string_view activeVersion,
+                         bool payloadExists) {
+    if (!is_binding(info.runtime)) return std::nullopt;
+
+    const auto declaredVersion = binding_version(info.runtime);
+    if (version_is_active(declaredVersion, activeVersion) && payloadExists) {
+        return std::nullopt;
+    }
+
+    std::string active;
+    if (!activeVersion.empty()) {
+        auto displayVersion = activeVersion;
+        if (const auto colon = displayVersion.find(':');
+            colon != std::string_view::npos) {
+            displayVersion.remove_prefix(colon + 1);
+        }
+        active = std::format("{}@{}", binding_name(info.runtime),
+                             displayVersion);
+    }
+    return RuntimeActivationMismatch{
+        .declared = info.runtime,
+        .active = std::move(active),
+        .payloadMissing = !payloadExists,
+    };
+}
+
+Info select_effective(const Info& info,
+                      const std::map<std::string, std::string>& active) {
+    Info out = info;
+    out.envs.clear();
+    for (const auto& p : info.envs) {
+        if (is_binding(p.binding)) {
+            const auto it = active.find(std::string(binding_name(p.binding)));
+            if (it != active.end()
+                && !version_is_active(binding_version(p.binding), it->second)) {
+                continue;
+            }
+        }
+        out.envs.push_back(p);
+    }
+    return out;
+}
+
+std::vector<DuplicateBinding>
+contested_bindings(const Info& info,
+                   const std::map<std::string, std::string>& active) {
+    std::vector<DuplicateBinding> out;
+    for (auto& dup : duplicate_bindings(info)) {
+        if (active.contains(dup.name)) continue;
+        out.push_back(std::move(dup));
+    }
+    return out;
+}
+
+std::string_view describe(Defect d) {
+    switch (d) {
+        case Defect::DirMissing:        return "subos directory is missing";
+        case Defect::ConfigMissing:     return "subos has no .xlings.json";
+        case Defect::ConfigUnreadable:  return ".xlings.json is not readable JSON";
+        case Defect::BlockMissing:      return "no subos_info block";
+        case Defect::SchemaUnsupported: return "unsupported subos_info schema_version";
+        case Defect::RuntimeMalformed:  return "runtime is not <name>@<version>";
+        case Defect::EnvsMalformed:     return "envs is not an object of provider sections";
+        case Defect::EnvDeclMalformed:  return "env declaration is malformed";
+        case Defect::ProvenanceMissing: return "created_at / created_by missing";
+    }
+    return "unknown defect";
+}
+
+fs::path config_path(const fs::path& subosDir) {
+    return subosDir / ".xlings.json";
+}
+
+std::optional<nlohmann::json> read_document(const fs::path& subosDir) {
+    const auto path = config_path(subosDir);
+    std::error_code ec;
+    if (!fs::exists(path, ec) || ec) return std::nullopt;
+    try {
+        auto content = platform::read_file_to_string(path.string());
+        auto parsed  = nlohmann::json::parse(content, nullptr, false);
+        if (parsed.is_discarded() || !parsed.is_object()) return std::nullopt;
+        return parsed;
+    } catch (...) { return std::nullopt; }
+}
+
+std::vector<Finding> validate_block(const nlohmann::json& doc) {
+    std::vector<Finding> out;
+
+    if (!doc.contains(std::string(BLOCK)) || !doc[std::string(BLOCK)].is_object()) {
+        out.push_back({Defect::BlockMissing, std::string(BLOCK)});
+        return out;   // nothing below can be checked
+    }
+    const auto& b = doc[std::string(BLOCK)];
+
+    if (!b.contains("schema_version") || !b["schema_version"].is_number_integer()
+        || b["schema_version"].get<int>() != SCHEMA_VERSION) {
+        out.push_back({Defect::SchemaUnsupported,
+                       b.contains("schema_version") ? b["schema_version"].dump()
+                                                    : "absent"});
+    }
+
+    const auto runtime = b.value("runtime", std::string{});
+    if (!is_binding(runtime)) {
+        out.push_back({Defect::RuntimeMalformed,
+                       runtime.empty() ? "absent" : runtime});
+    }
+
+    // "An empty collection is not a missing one": `envs` is written as {} at
+    // creation and stays {} when the last provider is removed, so no reader
+    // has to treat absent and empty as the same thing.
+    if (!b.contains("envs") || !b["envs"].is_object()) {
+        out.push_back({Defect::EnvsMalformed,
+                       b.contains("envs") ? b["envs"].type_name() : "absent"});
+    } else {
+        for (auto it = b["envs"].begin(); it != b["envs"].end(); ++it) {
+            if (!is_binding(it.key())) {
+                out.push_back({Defect::EnvsMalformed,
+                               std::format("provider key '{}' is not <name>@<version>",
+                                           it.key())});
+                continue;
+            }
+            if (!it.value().is_array()) {
+                out.push_back({Defect::EnvsMalformed,
+                               std::format("provider '{}' is not an array", it.key())});
+                continue;
+            }
+            for (const auto& d : it.value()) {
+                const auto var = d.is_object() ? d.value("var", std::string{})
+                                               : std::string{};
+                const auto op  = d.is_object() ? d.value("op", std::string{})
+                                               : std::string{};
+                if (var.empty() || (op != OP_SET && op != OP_PREPEND)) {
+                    out.push_back({Defect::EnvDeclMalformed,
+                                   std::format("{}: {}", it.key(), d.dump())});
+                }
+            }
+        }
+    }
+
+    if (b.value("created_at", std::string{}).empty()
+        || b.value("created_by", std::string{}).empty()) {
+        out.push_back({Defect::ProvenanceMissing, ""});
+    }
+    return out;
+}
+
+std::vector<Finding> validate(const fs::path& subosDir) {
+    std::error_code ec;
+    if (!fs::is_directory(subosDir, ec) || ec)
+        return {{Defect::DirMissing, subosDir.string()}};
+    if (!fs::exists(config_path(subosDir), ec) || ec)
+        return {{Defect::ConfigMissing, config_path(subosDir).string()}};
+
+    auto doc = read_document(subosDir);
+    if (!doc) return {{Defect::ConfigUnreadable, config_path(subosDir).string()}};
+    return validate_block(*doc);
+}
+
+Info parse(const nlohmann::json& doc) {
+    Info info;
+    if (!doc.contains(std::string(BLOCK)) || !doc[std::string(BLOCK)].is_object())
+        return info;
+    const auto& b = doc[std::string(BLOCK)];
+
+    info.schema_version = b.value("schema_version", 0);
+    info.runtime        = b.value("runtime", std::string{});
+    info.created_at     = b.value("created_at", std::string{});
+    info.created_by     = b.value("created_by", std::string{});
+    info.host_glibc     = b.value("host_glibc", std::string{});
+
+    if (b.contains("envs") && b["envs"].is_object()) {
+        for (auto it = b["envs"].begin(); it != b["envs"].end(); ++it) {
+            if (!it.value().is_array()) continue;
+            Provider p{.binding = it.key()};
+            for (const auto& d : it.value()) {
+                if (!d.is_object()) continue;
+                EnvDecl e{
+                    .var   = d.value("var", std::string{}),
+                    .op    = d.value("op", std::string{}),
+                    .value = d.value("value", std::string{}),
+                };
+                if (e.var.empty()) continue;
+                if (e.op != OP_SET && e.op != OP_PREPEND) continue;
+                p.decls.push_back(std::move(e));
+            }
+            info.envs.push_back(std::move(p));
+        }
+    }
+    std::ranges::sort(info.envs, {}, &Provider::binding);
+    return info;
+}
+
+std::string utc_now_iso() {
+    const auto now = std::chrono::system_clock::to_time_t(
+        std::chrono::system_clock::now());
+    char buf[32];
+    std::strftime(buf, sizeof(buf), "%Y-%m-%dT%H:%M:%SZ", std::gmtime(&now));
+    return buf;
+}
+
+nlohmann::json make_block(std::string_view runtime, std::string_view createdBy, std::string_view hostGlibc) {
+    nlohmann::json b;
+    b["schema_version"] = SCHEMA_VERSION;
+    b["runtime"]        = std::string(runtime);
+    b["envs"]           = nlohmann::json::object();
+    b["created_at"]     = utc_now_iso();
+    b["created_by"]     = std::string(createdBy);
+    if (!hostGlibc.empty()) b["host_glibc"] = std::string(hostGlibc);
+    return b;
+}
+
+std::string observed_runtime(const nlohmann::json& doc,
+                             std::string_view family) {
+    if (family.empty()) return {};
+    if (!doc.contains("workspace") || !doc["workspace"].is_object()) return {};
+    const auto& ws = doc["workspace"];
+    const std::string key(family);
+    if (!ws.contains(key) || !ws[key].is_object()) return {};
+    auto active = ws[key].value("active", std::string{});
+    // Workspace versions may carry the provider namespace (`xim:2.39`); the
+    // binding never does.
+    if (const auto colon = active.find(':'); colon != std::string::npos) {
+        active = active.substr(colon + 1);
+    }
+    if (active.empty()) return {};
+    const auto binding = std::format("{}@{}", family, active);
+    return is_binding(binding) ? binding : std::string{};
+}
+
+std::string preserved_runtime(const nlohmann::json& doc,
+                              std::string_view fallback) {
+    if (doc.contains(std::string(BLOCK)) && doc[std::string(BLOCK)].is_object()) {
+        const auto r = doc[std::string(BLOCK)].value("runtime", std::string{});
+        if (is_binding(r)) return r;
+    }
+    if (auto observed = observed_runtime(doc, binding_name(fallback));
+        !observed.empty()) {
+        return observed;
+    }
+    return std::string(fallback);
+}
+
+bool add_env(nlohmann::json& doc, std::string_view binding, const EnvDecl& decl) {
+    auto& b = doc[std::string(BLOCK)];
+    if (!b.is_object()) b = nlohmann::json::object();
+    if (!b.contains("envs") || !b["envs"].is_object())
+        b["envs"] = nlohmann::json::object();
+
+    auto& section = b["envs"][std::string(binding)];
+    if (!section.is_array()) section = nlohmann::json::array();
+
+    for (const auto& existing : section) {
+        if (existing.value("var", std::string{}) == decl.var
+            && existing.value("op", std::string{}) == decl.op
+            && existing.value("value", std::string{}) == decl.value) {
+            return false;
+        }
+    }
+    section.push_back({{"var", decl.var}, {"op", decl.op}, {"value", decl.value}});
+    return true;
+}
+
+bool set_env_section(nlohmann::json& doc, std::string_view binding,
+                     const std::vector<EnvDecl>& decls) {
+    auto& b = doc[std::string(BLOCK)];
+    if (!b.is_object()) b = nlohmann::json::object();
+    if (!b.contains("envs") || !b["envs"].is_object())
+        b["envs"] = nlohmann::json::object();
+
+    auto next = nlohmann::json::array();
+    for (const auto& d : decls) {
+        // Within one run a package may legitimately compute the same
+        // declaration twice (a shared helper called from two places); recording
+        // it twice would double the value in the resolved variable.
+        bool dup = false;
+        for (const auto& existing : next) {
+            if (existing.value("var", std::string{}) == d.var
+                && existing.value("op", std::string{}) == d.op
+                && existing.value("value", std::string{}) == d.value) {
+                dup = true;
+                break;
+            }
+        }
+        if (!dup)
+            next.push_back({{"var", d.var}, {"op", d.op}, {"value", d.value}});
+    }
+
+    auto& section = b["envs"][std::string(binding)];
+    if (section == next) return false;
+    section = std::move(next);
+    return true;
+}
+
+bool remove_provider(nlohmann::json& doc, std::string_view binding) {
+    if (!doc.contains(std::string(BLOCK))) return false;
+    auto& b = doc[std::string(BLOCK)];
+    if (!b.is_object() || !b.contains("envs") || !b["envs"].is_object())
+        return false;
+    return b["envs"].erase(std::string(binding)) > 0;
+}
+
+std::vector<std::string> providers_named(const nlohmann::json& doc,
+                                         std::string_view name) {
+    std::vector<std::string> out;
+    if (!doc.contains(std::string(BLOCK))) return out;
+    const auto& b = doc[std::string(BLOCK)];
+    if (!b.is_object() || !b.contains("envs") || !b["envs"].is_object()) return out;
+    for (auto it = b["envs"].begin(); it != b["envs"].end(); ++it)
+        if (binding_name(it.key()) == name) out.push_back(it.key());
+    return out;
+}
+
+std::string expand(std::string_view value, std::string_view binding,
+                   const Placeholders& ph) {
+    std::string out;
+    out.reserve(value.size());
+
+    for (std::size_t i = 0; i < value.size();) {
+        if (value[i] != '$' || i + 1 >= value.size() || value[i + 1] != '{') {
+            out += value[i++];
+            continue;
+        }
+        const auto close = value.find('}', i + 2);
+        if (close == std::string_view::npos) {           // unterminated: verbatim
+            out += value.substr(i);
+            break;
+        }
+        const auto name = value.substr(i + 2, close - i - 2);
+        fs::path resolved;
+        bool known = true;
+        if      (name == "subosdir")    resolved = ph.subosdir;
+        else if (name == "home")        resolved = ph.home;
+        else if (name == "xlings_home") resolved = ph.xlings_home;
+        else if (name == "pkgdir")      resolved = ph.pkgdir_of ? ph.pkgdir_of(binding)
+                                                                : fs::path{};
+        else known = false;
+
+        if (!known || resolved.empty()) out += value.substr(i, close - i + 1);
+        else                            out += resolved.string();
+        i = close + 1;
+    }
+    return out;
+}
+
+bool has_unresolved(std::string_view expanded) {
+    return expanded.find("${") != std::string_view::npos;
+}
+
+std::vector<Resolved> resolve(const Info& info, const Placeholders& ph) {
+    struct Acc {
+        std::string              setValue;
+        bool                     hasSet = false;
+        std::vector<std::string> prepends;   // front-most last
+        std::vector<std::string> providers;
+        bool                     unresolved = false;
+        std::size_t              order = 0;  // first appearance, for stable output
+    };
+    std::map<std::string, Acc> acc;
+    std::size_t seen = 0;
+
+    for (const auto& p : info.envs) {          // already sorted by binding
+        for (const auto& d : p.decls) {
+            auto expanded = expand(d.value, p.binding, ph);
+            auto& a = acc[d.var];
+            if (a.providers.empty()) a.order = seen++;
+            a.providers.push_back(p.binding);
+            if (has_unresolved(expanded)) a.unresolved = true;
+            if (d.op == OP_SET) { a.setValue = std::move(expanded); a.hasSet = true; }
+            else                { a.prepends.push_back(std::move(expanded)); }
+        }
+    }
+
+    std::vector<Resolved> out;
+    out.reserve(acc.size());
+    for (auto& [var, a] : acc) {
+        Resolved r{.var = var, .providers = a.providers, .unresolved = a.unresolved};
+        // More than one declaration for a variable is a conflict unless they
+        // are all prepends, which compose by construction.
+        r.conflicted = a.providers.size() > 1
+                       && !(!a.hasSet && !a.prepends.empty());
+        if (a.hasSet) {
+            r.op    = std::string(OP_SET);
+            r.value = std::move(a.setValue);
+            if (!a.prepends.empty()) r.conflicted = true;
+        } else {
+            r.op = std::string(OP_PREPEND);
+            // Later provider nearer the front, matching "the newest thing
+            // installed is found first".
+            //
+            // De-duplicated, because two providers naming the same directory is
+            // not a mistake to preserve -- it is the intended arrangement. mesa
+            // and nvidia-gl-host-link both declare the SHARED glvnd vendor
+            // directory precisely so that either package being absent does not
+            // remove it for the other, and joining them verbatim put that path
+            // on __EGL_VENDOR_LIBRARY_DIRS twice.
+            //
+            // The shim side already did this (xvm/shim.cppm
+            // merge_shim_env_value, added when a doubled GIT_SSL_CAINFO broke
+            // every HTTPS git transport). Two answers to one question; this is
+            // the second one agreeing with the first.
+            std::set<std::string> seen;
+            for (auto it = a.prepends.rbegin(); it != a.prepends.rend(); ++it) {
+                if (!seen.insert(*it).second) continue;
+                if (!r.value.empty()) r.value += ':';
+                r.value += *it;
+            }
+        }
+        out.push_back(std::move(r));
+    }
+    // Stable, and stable for a reason: this list is echoed to the user and
+    // diffed in tests, so it must not reorder because a map rehashed.
+    std::ranges::sort(out, {}, &Resolved::var);
+    return out;
+}
+
+}
diff --git a/src/core/subos/manifest.cppm b/src/core/subos/manifest.cppm
index 6d4c1290..f76a425c 100644
--- a/src/core/subos/manifest.cppm
+++ b/src/core/subos/manifest.cppm
@@ -3,7 +3,6 @@ export module xlings.core.subos.manifest;
 import std;
 
 import xlings.libs.json;
-import xlings.platform;
 
 // `subos_info` — what a subos is, recorded in the subos's own `.xlings.json`.
 //
@@ -95,35 +94,15 @@ struct Info {
 //
 // Slice 1 needs only the glibc row. The rest are listed to make the shape of
 // the mapping explicit — a new OS adds a row, not a schema field.
-std::string family_of(std::string_view runtime, std::string_view arch = "x86_64") {
-    const auto at   = runtime.find('@');
-    const auto name = runtime.substr(0, at == std::string_view::npos
-                                        ? runtime.size() : at);
-    if (name == "glibc")     return std::format("linux-{}-glibc", arch);
-    if (name == "musl")      return std::format("linux-{}-musl", arch);
-    if (name == "wasi-libc") return "wasm32-wasi";
-    if (name == "macos_sdk") return std::format("darwin-{}", arch);
-    if (name == "ucrt")      return std::format("windows-{}-ucrt", arch);
-    return "unknown";
-}
+std::string family_of(std::string_view runtime, std::string_view arch = "x86_64");
 
 // "<name>@<version>", both halves non-empty. Used for `runtime` and for every
 // envs key.
-bool is_binding(std::string_view s) {
-    const auto at = s.find('@');
-    return at != std::string_view::npos && at > 0 && at + 1 < s.size();
-}
+bool is_binding(std::string_view s);
 
-std::string_view binding_name(std::string_view binding) {
-    const auto at = binding.find('@');
-    return at == std::string_view::npos ? binding : binding.substr(0, at);
-}
+std::string_view binding_name(std::string_view binding);
 
-std::string_view binding_version(std::string_view binding) {
-    const auto at = binding.find('@');
-    return at == std::string_view::npos ? std::string_view{}
-                                        : binding.substr(at + 1);
-}
+std::string_view binding_version(std::string_view binding);
 
 // ── the subos layer's "exactly one" ─────────────────────────────────────
 //
@@ -149,22 +128,7 @@ struct DuplicateBinding {
     std::vector<std::string> bindings;   // every binding for that name, sorted
 };
 
-std::vector<DuplicateBinding> duplicate_bindings(const Info& info) {
-    std::map<std::string, std::vector<std::string>> byName;
-    for (const auto& p : info.envs) {
-        if (!is_binding(p.binding)) continue;
-        byName[std::string(binding_name(p.binding))].push_back(p.binding);
-    }
-    std::vector<DuplicateBinding> out;
-    for (auto& [name, bindings] : byName) {
-        if (bindings.size() < 2) continue;
-        std::ranges::sort(bindings);
-        bindings.erase(std::ranges::unique(bindings).begin(), bindings.end());
-        if (bindings.size() < 2) continue;   // one version listed twice is not two
-        out.push_back({.name = name, .bindings = std::move(bindings)});
-    }
-    return out;
-}
+std::vector<DuplicateBinding> duplicate_bindings(const Info& info);
 
 // Which version of each package THIS subos has active.
 //
@@ -172,16 +136,7 @@ std::vector<DuplicateBinding> duplicate_bindings(const Info& info) {
 // holds both `workspace` (name -> active/installed) and `subos_info.envs`
 // (binding -> declarations) -- two records of "what is in this subos", in one
 // file. That is the whole of P1 in eleven lines of JSON.
-std::map<std::string, std::string> active_versions(const nlohmann::json& doc) {
-    std::map<std::string, std::string> out;
-    if (!doc.contains("workspace") || !doc["workspace"].is_object()) return out;
-    for (auto it = doc["workspace"].begin(); it != doc["workspace"].end(); ++it) {
-        if (!it.value().is_object()) continue;
-        auto active = it.value().value("active", std::string{});
-        if (!active.empty()) out[it.key()] = std::move(active);
-    }
-    return out;
-}
+std::map<std::string, std::string> active_versions(const nlohmann::json& doc);
 
 // True when `version` is the one `active` names, allowing for the `<ns>:<ver>`
 // form a namespaced install records.
@@ -204,30 +159,7 @@ struct RuntimeActivationMismatch {
 std::optional<RuntimeActivationMismatch>
 check_runtime_activation(const Info& info,
                          std::string_view activeVersion,
-                         bool payloadExists) {
-    if (!is_binding(info.runtime)) return std::nullopt;
-
-    const auto declaredVersion = binding_version(info.runtime);
-    if (version_is_active(declaredVersion, activeVersion) && payloadExists) {
-        return std::nullopt;
-    }
-
-    std::string active;
-    if (!activeVersion.empty()) {
-        auto displayVersion = activeVersion;
-        if (const auto colon = displayVersion.find(':');
-            colon != std::string_view::npos) {
-            displayVersion.remove_prefix(colon + 1);
-        }
-        active = std::format("{}@{}", binding_name(info.runtime),
-                             displayVersion);
-    }
-    return RuntimeActivationMismatch{
-        .declared = info.runtime,
-        .active = std::move(active),
-        .payloadMissing = !payloadExists,
-    };
-}
+                         bool payloadExists);
 
 // The providers that actually take effect, out of everything the manifest
 // records.
@@ -252,21 +184,7 @@ check_runtime_activation(const Info& info,
 // several versions are declared with no active one, nothing can say which is
 // meant; that state is reported rather than guessed at.
 Info select_effective(const Info& info,
-                      const std::map<std::string, std::string>& active) {
-    Info out = info;
-    out.envs.clear();
-    for (const auto& p : info.envs) {
-        if (is_binding(p.binding)) {
-            const auto it = active.find(std::string(binding_name(p.binding)));
-            if (it != active.end()
-                && !version_is_active(binding_version(p.binding), it->second)) {
-                continue;
-            }
-        }
-        out.envs.push_back(p);
-    }
-    return out;
-}
+                      const std::map<std::string, std::string>& active);
 
 // A package bound at several versions with nothing able to say which is meant.
 //
@@ -277,14 +195,7 @@ Info select_effective(const Info& info,
 // it takes a lost workspace record, not an ordinary install.
 std::vector<DuplicateBinding>
 contested_bindings(const Info& info,
-                   const std::map<std::string, std::string>& active) {
-    std::vector<DuplicateBinding> out;
-    for (auto& dup : duplicate_bindings(info)) {
-        if (active.contains(dup.name)) continue;
-        out.push_back(std::move(dup));
-    }
-    return out;
-}
+                   const std::map<std::string, std::string>& active);
 
 // ── invariants ──────────────────────────────────────────────────────────
 
@@ -305,181 +216,40 @@ struct Finding {
     std::string detail;
 };
 
-std::string_view describe(Defect d) {
-    switch (d) {
-        case Defect::DirMissing:        return "subos directory is missing";
-        case Defect::ConfigMissing:     return "subos has no .xlings.json";
-        case Defect::ConfigUnreadable:  return ".xlings.json is not readable JSON";
-        case Defect::BlockMissing:      return "no subos_info block";
-        case Defect::SchemaUnsupported: return "unsupported subos_info schema_version";
-        case Defect::RuntimeMalformed:  return "runtime is not <name>@<version>";
-        case Defect::EnvsMalformed:     return "envs is not an object of provider sections";
-        case Defect::EnvDeclMalformed:  return "env declaration is malformed";
-        case Defect::ProvenanceMissing: return "created_at / created_by missing";
-    }
-    return "unknown defect";
-}
+std::string_view describe(Defect d);
 
-fs::path config_path(const fs::path& subosDir) {
-    return subosDir / ".xlings.json";
-}
+fs::path config_path(const fs::path& subosDir);
 
 // Read the whole document. An unreadable or malformed file yields nullopt, and
 // the caller must not paper over it with an empty object: for the home config
 // "corrupt means absent" is the historical behavior, but here it would let
 // `--fix` rewrite a file it never managed to read.
-std::optional<nlohmann::json> read_document(const fs::path& subosDir) {
-    const auto path = config_path(subosDir);
-    std::error_code ec;
-    if (!fs::exists(path, ec) || ec) return std::nullopt;
-    try {
-        auto content = platform::read_file_to_string(path.string());
-        auto parsed  = nlohmann::json::parse(content, nullptr, false);
-        if (parsed.is_discarded() || !parsed.is_object()) return std::nullopt;
-        return parsed;
-    } catch (...) { return std::nullopt; }
-}
+std::optional<nlohmann::json> read_document(const fs::path& subosDir);
 
 // I4–I8, over a document already in hand. Split out from validate() so a
 // caller that has just built a document in memory can check it before writing.
-std::vector<Finding> validate_block(const nlohmann::json& doc) {
-    std::vector<Finding> out;
-
-    if (!doc.contains(std::string(BLOCK)) || !doc[std::string(BLOCK)].is_object()) {
-        out.push_back({Defect::BlockMissing, std::string(BLOCK)});
-        return out;   // nothing below can be checked
-    }
-    const auto& b = doc[std::string(BLOCK)];
-
-    if (!b.contains("schema_version") || !b["schema_version"].is_number_integer()
-        || b["schema_version"].get<int>() != SCHEMA_VERSION) {
-        out.push_back({Defect::SchemaUnsupported,
-                       b.contains("schema_version") ? b["schema_version"].dump()
-                                                    : "absent"});
-    }
-
-    const auto runtime = b.value("runtime", std::string{});
-    if (!is_binding(runtime)) {
-        out.push_back({Defect::RuntimeMalformed,
-                       runtime.empty() ? "absent" : runtime});
-    }
-
-    // "An empty collection is not a missing one": `envs` is written as {} at
-    // creation and stays {} when the last provider is removed, so no reader
-    // has to treat absent and empty as the same thing.
-    if (!b.contains("envs") || !b["envs"].is_object()) {
-        out.push_back({Defect::EnvsMalformed,
-                       b.contains("envs") ? b["envs"].type_name() : "absent"});
-    } else {
-        for (auto it = b["envs"].begin(); it != b["envs"].end(); ++it) {
-            if (!is_binding(it.key())) {
-                out.push_back({Defect::EnvsMalformed,
-                               std::format("provider key '{}' is not <name>@<version>",
-                                           it.key())});
-                continue;
-            }
-            if (!it.value().is_array()) {
-                out.push_back({Defect::EnvsMalformed,
-                               std::format("provider '{}' is not an array", it.key())});
-                continue;
-            }
-            for (const auto& d : it.value()) {
-                const auto var = d.is_object() ? d.value("var", std::string{})
-                                               : std::string{};
-                const auto op  = d.is_object() ? d.value("op", std::string{})
-                                               : std::string{};
-                if (var.empty() || (op != OP_SET && op != OP_PREPEND)) {
-                    out.push_back({Defect::EnvDeclMalformed,
-                                   std::format("{}: {}", it.key(), d.dump())});
-                }
-            }
-        }
-    }
-
-    if (b.value("created_at", std::string{}).empty()
-        || b.value("created_by", std::string{}).empty()) {
-        out.push_back({Defect::ProvenanceMissing, ""});
-    }
-    return out;
-}
+std::vector<Finding> validate_block(const nlohmann::json& doc);
 
 // I1–I8 for a subos on disk. The single predicate the doctor reporter and the
 // repairer both call — two descriptions of the same rule is how a reporter
 // ends up flagging what `--fix` will not touch.
-std::vector<Finding> validate(const fs::path& subosDir) {
-    std::error_code ec;
-    if (!fs::is_directory(subosDir, ec) || ec)
-        return {{Defect::DirMissing, subosDir.string()}};
-    if (!fs::exists(config_path(subosDir), ec) || ec)
-        return {{Defect::ConfigMissing, config_path(subosDir).string()}};
-
-    auto doc = read_document(subosDir);
-    if (!doc) return {{Defect::ConfigUnreadable, config_path(subosDir).string()}};
-    return validate_block(*doc);
-}
+std::vector<Finding> validate(const fs::path& subosDir);
 
 // ── parse / build ───────────────────────────────────────────────────────
 
 // Providers come back sorted by binding. That ordering is the resolution order
 // (see resolve) and it is derived from the data rather than from install
 // history, so two homes holding the same manifest resolve it identically.
-Info parse(const nlohmann::json& doc) {
-    Info info;
-    if (!doc.contains(std::string(BLOCK)) || !doc[std::string(BLOCK)].is_object())
-        return info;
-    const auto& b = doc[std::string(BLOCK)];
-
-    info.schema_version = b.value("schema_version", 0);
-    info.runtime        = b.value("runtime", std::string{});
-    info.created_at     = b.value("created_at", std::string{});
-    info.created_by     = b.value("created_by", std::string{});
-    info.host_glibc     = b.value("host_glibc", std::string{});
-
-    if (b.contains("envs") && b["envs"].is_object()) {
-        for (auto it = b["envs"].begin(); it != b["envs"].end(); ++it) {
-            if (!it.value().is_array()) continue;
-            Provider p{.binding = it.key()};
-            for (const auto& d : it.value()) {
-                if (!d.is_object()) continue;
-                EnvDecl e{
-                    .var   = d.value("var", std::string{}),
-                    .op    = d.value("op", std::string{}),
-                    .value = d.value("value", std::string{}),
-                };
-                if (e.var.empty()) continue;
-                if (e.op != OP_SET && e.op != OP_PREPEND) continue;
-                p.decls.push_back(std::move(e));
-            }
-            info.envs.push_back(std::move(p));
-        }
-    }
-    std::ranges::sort(info.envs, {}, &Provider::binding);
-    return info;
-}
+Info parse(const nlohmann::json& doc);
 
-std::string utc_now_iso() {
-    const auto now = std::chrono::system_clock::to_time_t(
-        std::chrono::system_clock::now());
-    char buf[32];
-    std::strftime(buf, sizeof(buf), "%Y-%m-%dT%H:%M:%SZ", std::gmtime(&now));
-    return buf;
-}
+std::string utc_now_iso();
 
 // The block a freshly created subos gets. `envs` is an explicit empty object.
 // `hostGlibc` is written only when known — an absent key is the documented
 // spelling of "unknown", so a pre-C1 manifest and a failed probe read the
 // same way.
 nlohmann::json make_block(std::string_view runtime, std::string_view createdBy,
-                          std::string_view hostGlibc = {}) {
-    nlohmann::json b;
-    b["schema_version"] = SCHEMA_VERSION;
-    b["runtime"]        = std::string(runtime);
-    b["envs"]           = nlohmann::json::object();
-    b["created_at"]     = utc_now_iso();
-    b["created_by"]     = std::string(createdBy);
-    if (!hostGlibc.empty()) b["host_glibc"] = std::string(hostGlibc);
-    return b;
-}
+                          std::string_view hostGlibc = {});
 
 // What a subos is OBSERVED to run, out of the workspace in its own manifest.
 //
@@ -491,22 +261,7 @@ nlohmann::json make_block(std::string_view runtime, std::string_view createdBy,
 // The family comes from the caller's fallback rather than a literal, so this
 // says nothing about which family a platform uses.
 std::string observed_runtime(const nlohmann::json& doc,
-                             std::string_view family) {
-    if (family.empty()) return {};
-    if (!doc.contains("workspace") || !doc["workspace"].is_object()) return {};
-    const auto& ws = doc["workspace"];
-    const std::string key(family);
-    if (!ws.contains(key) || !ws[key].is_object()) return {};
-    auto active = ws[key].value("active", std::string{});
-    // Workspace versions may carry the provider namespace (`xim:2.39`); the
-    // binding never does.
-    if (const auto colon = active.find(':'); colon != std::string::npos) {
-        active = active.substr(colon + 1);
-    }
-    if (active.empty()) return {};
-    const auto binding = std::format("{}@{}", family, active);
-    return is_binding(binding) ? binding : std::string{};
-}
+                             std::string_view family);
 
 // The runtime a REBUILT block should carry. A block can be invalid for
 // reasons that have nothing to do with its runtime (schema_version, envs,
@@ -531,17 +286,7 @@ std::string observed_runtime(const nlohmann::json& doc,
 // `self doctor` calls them broken and `use` refuses to activate the runtime
 // they were already on.
 std::string preserved_runtime(const nlohmann::json& doc,
-                              std::string_view fallback) {
-    if (doc.contains(std::string(BLOCK)) && doc[std::string(BLOCK)].is_object()) {
-        const auto r = doc[std::string(BLOCK)].value("runtime", std::string{});
-        if (is_binding(r)) return r;
-    }
-    if (auto observed = observed_runtime(doc, binding_name(fallback));
-        !observed.empty()) {
-        return observed;
-    }
-    return std::string(fallback);
-}
+                              std::string_view fallback);
 
 // ── env declarations ────────────────────────────────────────────────────
 
@@ -550,25 +295,7 @@ std::string preserved_runtime(const nlohmann::json& doc,
 // a re-run must not grow the section.
 //
 // Returns whether the document changed, so a caller can skip a write.
-bool add_env(nlohmann::json& doc, std::string_view binding, const EnvDecl& decl) {
-    auto& b = doc[std::string(BLOCK)];
-    if (!b.is_object()) b = nlohmann::json::object();
-    if (!b.contains("envs") || !b["envs"].is_object())
-        b["envs"] = nlohmann::json::object();
-
-    auto& section = b["envs"][std::string(binding)];
-    if (!section.is_array()) section = nlohmann::json::array();
-
-    for (const auto& existing : section) {
-        if (existing.value("var", std::string{}) == decl.var
-            && existing.value("op", std::string{}) == decl.op
-            && existing.value("value", std::string{}) == decl.value) {
-            return false;
-        }
-    }
-    section.push_back({{"var", decl.var}, {"op", decl.op}, {"value", decl.value}});
-    return true;
-}
+bool add_env(nlohmann::json& doc, std::string_view binding, const EnvDecl& decl);
 
 // Replace a provider's whole section with what it declared THIS run.
 //
@@ -590,63 +317,21 @@ bool add_env(nlohmann::json& doc, std::string_view binding, const EnvDecl& decl)
 // Returns whether the document changed, so a caller can skip a write. Order is
 // preserved as declared: `prepend` composition depends on it.
 bool set_env_section(nlohmann::json& doc, std::string_view binding,
-                     const std::vector<EnvDecl>& decls) {
-    auto& b = doc[std::string(BLOCK)];
-    if (!b.is_object()) b = nlohmann::json::object();
-    if (!b.contains("envs") || !b["envs"].is_object())
-        b["envs"] = nlohmann::json::object();
-
-    auto next = nlohmann::json::array();
-    for (const auto& d : decls) {
-        // Within one run a package may legitimately compute the same
-        // declaration twice (a shared helper called from two places); recording
-        // it twice would double the value in the resolved variable.
-        bool dup = false;
-        for (const auto& existing : next) {
-            if (existing.value("var", std::string{}) == d.var
-                && existing.value("op", std::string{}) == d.op
-                && existing.value("value", std::string{}) == d.value) {
-                dup = true;
-                break;
-            }
-        }
-        if (!dup)
-            next.push_back({{"var", d.var}, {"op", d.op}, {"value", d.value}});
-    }
-
-    auto& section = b["envs"][std::string(binding)];
-    if (section == next) return false;
-    section = std::move(next);
-    return true;
-}
+                     const std::vector<EnvDecl>& decls);
 
 // Drop a provider's whole section — the uninstall counterpart of add_env. The
 // package never writes cleanup code for this; ownership is by binding, so
 // removing the key removes exactly what that package added and nothing else.
 //
 // The `envs` object itself stays, empty, per the invariant above.
-bool remove_provider(nlohmann::json& doc, std::string_view binding) {
-    if (!doc.contains(std::string(BLOCK))) return false;
-    auto& b = doc[std::string(BLOCK)];
-    if (!b.is_object() || !b.contains("envs") || !b["envs"].is_object())
-        return false;
-    return b["envs"].erase(std::string(binding)) > 0;
-}
+bool remove_provider(nlohmann::json& doc, std::string_view binding);
 
 // Every provider whose package name matches, regardless of version. Uninstall
 // knows the name and version it removed, but a home that installed the same
 // package twice under different versions can hold a stale section from the
 // earlier one; matching on name is what lets doctor see it.
 std::vector<std::string> providers_named(const nlohmann::json& doc,
-                                         std::string_view name) {
-    std::vector<std::string> out;
-    if (!doc.contains(std::string(BLOCK))) return out;
-    const auto& b = doc[std::string(BLOCK)];
-    if (!b.is_object() || !b.contains("envs") || !b["envs"].is_object()) return out;
-    for (auto it = b["envs"].begin(); it != b["envs"].end(); ++it)
-        if (binding_name(it.key()) == name) out.push_back(it.key());
-    return out;
-}
+                                         std::string_view name);
 
 // ── placeholders ────────────────────────────────────────────────────────
 
@@ -671,43 +356,12 @@ struct Placeholders {
 // a real path, on the host, outside the subos. Leaving the text intact makes
 // the failure visible to doctor D3 instead of pointing a driver search at /.
 std::string expand(std::string_view value, std::string_view binding,
-                   const Placeholders& ph) {
-    std::string out;
-    out.reserve(value.size());
-
-    for (std::size_t i = 0; i < value.size();) {
-        if (value[i] != '$' || i + 1 >= value.size() || value[i + 1] != '{') {
-            out += value[i++];
-            continue;
-        }
-        const auto close = value.find('}', i + 2);
-        if (close == std::string_view::npos) {           // unterminated: verbatim
-            out += value.substr(i);
-            break;
-        }
-        const auto name = value.substr(i + 2, close - i - 2);
-        fs::path resolved;
-        bool known = true;
-        if      (name == "subosdir")    resolved = ph.subosdir;
-        else if (name == "home")        resolved = ph.home;
-        else if (name == "xlings_home") resolved = ph.xlings_home;
-        else if (name == "pkgdir")      resolved = ph.pkgdir_of ? ph.pkgdir_of(binding)
-                                                                : fs::path{};
-        else known = false;
-
-        if (!known || resolved.empty()) out += value.substr(i, close - i + 1);
-        else                            out += resolved.string();
-        i = close + 1;
-    }
-    return out;
-}
+                   const Placeholders& ph);
 
 // True once expansion left any `${...}` behind — i.e. something could not be
 // resolved. Doctor D3 reports on this rather than on the directory existing,
 // because an unexpanded value is a defect regardless of what is on disk.
-bool has_unresolved(std::string_view expanded) {
-    return expanded.find("${") != std::string_view::npos;
-}
+bool has_unresolved(std::string_view expanded);
 
 // ── privileged declarations ─────────────────────────────────────────────
 //
@@ -801,71 +455,6 @@ struct Resolved {
 // manifests would then export different values. Sorting by binding keeps the
 // manifest the whole answer. Every conflict is reported (doctor D4) rather than
 // resolved quietly.
-std::vector<Resolved> resolve(const Info& info, const Placeholders& ph) {
-    struct Acc {
-        std::string              setValue;
-        bool                     hasSet = false;
-        std::vector<std::string> prepends;   // front-most last
-        std::vector<std::string> providers;
-        bool                     unresolved = false;
-        std::size_t              order = 0;  // first appearance, for stable output
-    };
-    std::map<std::string, Acc> acc;
-    std::size_t seen = 0;
-
-    for (const auto& p : info.envs) {          // already sorted by binding
-        for (const auto& d : p.decls) {
-            auto expanded = expand(d.value, p.binding, ph);
-            auto& a = acc[d.var];
-            if (a.providers.empty()) a.order = seen++;
-            a.providers.push_back(p.binding);
-            if (has_unresolved(expanded)) a.unresolved = true;
-            if (d.op == OP_SET) { a.setValue = std::move(expanded); a.hasSet = true; }
-            else                { a.prepends.push_back(std::move(expanded)); }
-        }
-    }
-
-    std::vector<Resolved> out;
-    out.reserve(acc.size());
-    for (auto& [var, a] : acc) {
-        Resolved r{.var = var, .providers = a.providers, .unresolved = a.unresolved};
-        // More than one declaration for a variable is a conflict unless they
-        // are all prepends, which compose by construction.
-        r.conflicted = a.providers.size() > 1
-                       && !(!a.hasSet && !a.prepends.empty());
-        if (a.hasSet) {
-            r.op    = std::string(OP_SET);
-            r.value = std::move(a.setValue);
-            if (!a.prepends.empty()) r.conflicted = true;
-        } else {
-            r.op = std::string(OP_PREPEND);
-            // Later provider nearer the front, matching "the newest thing
-            // installed is found first".
-            //
-            // De-duplicated, because two providers naming the same directory is
-            // not a mistake to preserve -- it is the intended arrangement. mesa
-            // and nvidia-gl-host-link both declare the SHARED glvnd vendor
-            // directory precisely so that either package being absent does not
-            // remove it for the other, and joining them verbatim put that path
-            // on __EGL_VENDOR_LIBRARY_DIRS twice.
-            //
-            // The shim side already did this (xvm/shim.cppm
-            // merge_shim_env_value, added when a doubled GIT_SSL_CAINFO broke
-            // every HTTPS git transport). Two answers to one question; this is
-            // the second one agreeing with the first.
-            std::set<std::string> seen;
-            for (auto it = a.prepends.rbegin(); it != a.prepends.rend(); ++it) {
-                if (!seen.insert(*it).second) continue;
-                if (!r.value.empty()) r.value += ':';
-                r.value += *it;
-            }
-        }
-        out.push_back(std::move(r));
-    }
-    // Stable, and stable for a reason: this list is echoed to the user and
-    // diffed in tests, so it must not reorder because a map rehashed.
-    std::ranges::sort(out, {}, &Resolved::var);
-    return out;
-}
+std::vector<Resolved> resolve(const Info& info, const Placeholders& ph);
 
 } // namespace xlings::subos::manifest
diff --git a/src/core/subos/sandbox.cpp b/src/core/subos/sandbox.cpp
new file mode 100644
index 00000000..c952310a
--- /dev/null
+++ b/src/core/subos/sandbox.cpp
@@ -0,0 +1,1060 @@
+module;
+
+// System headers used by the sandbox backends only. `import std;` does not
+// pull these in, and the named-module purview forbids including them there.
+#include <cstdio>
+#if defined(_WIN32)
+#define WIN32_LEAN_AND_MEAN
+// See src/core/subos.cppm: windows.h's min/max macros break std::min({...}).
+// Not yet triggered here, and that is exactly why it is worth closing --
+// the failure only appears on Windows, and only once someone writes the call.
+#define NOMINMAX
+#include <windows.h>
+#else
+#include <cerrno>
+#include <cstring>
+#include <unistd.h>
+#include <sys/wait.h>
+#endif
+
+module xlings.core.subos.sandbox;
+
+import std;
+import xlings.core.config;
+import xlings.libs.json;
+import xlings.core.log;
+import xlings.platform;
+import xlings.runtime;
+import xlings.core.utils;
+import xlings.core.xim.commands;
+import xlings.core.xim.compatibility;
+import xlings.core.subos.gpu;
+import xlings.core.xvm.shim;
+
+namespace xlings::subos::sandbox {
+
+nlohmann::json read_config_json_(const fs::path& path) {
+    if (!fs::exists(path)) return nlohmann::json::object();
+    try {
+        auto content = platform::read_file_to_string(path.string());
+        auto json = nlohmann::json::parse(content, nullptr, false);
+        return json.is_discarded() ? nlohmann::json::object() : json;
+    } catch (...) { return nlohmann::json::object(); }
+}
+
+StorageMode read_storage_mode_(const fs::path& subos_dir) {
+    auto cfg = subos_dir / ".xlings.json";
+    if (!fs::exists(cfg)) return StorageMode::Shared;
+    auto json = read_config_json_(cfg);
+    if (json.contains("storage") && json["storage"].is_string())
+        return storage_from_string_(json["storage"].get<std::string>());
+    return StorageMode::Shared;
+}
+
+// /etc/* template builders + sandbox dir layout init. uid_t / gid_t
+// are POSIX types — Windows MSVC doesn't have them. Sandbox is
+// Linux-only by design (proot uses ptrace + Linux syscall semantics);
+// the only caller (use_sandbox_mode_) is also Linux-guarded, so we
+// guard these helpers too rather than fight the type system with
+// platform-portable substitutes.
+#if defined(__linux__) || defined(__APPLE__)
+
+// We write per-user passwd/group at sandbox init time so getpwuid
+// (real_uid) inside the sandbox returns the real user's home
+// (= /home/<user>) and shell — most CLI tools depend on this. Root
+// is also included so anything that does getpwuid(0) (scripts that
+// assume "root must exist") doesn't bail.
+std::string make_etc_passwd_(const std::string& user, uid_t uid, gid_t gid) {
+    auto home = "/home/" + user;
+    // When running as root (uid 0), emit a SINGLE uid-0 entry whose home is
+    // the sandbox home (/home/<user>), so getpwuid(0)->pw_dir agrees with
+    // $HOME and the bind-mounted home. The historical extra
+    // "root:x:0:0:root:/root" line would otherwise create a second,
+    // conflicting uid-0 record that getpwuid(0) resolves to /root — an
+    // empty, unbound path — breaking `cd ~`, ~/.config, and profile sourcing
+    // for the root user inside the sandbox.
+    if (uid == 0) {
+        return std::format("{}:x:0:0:{}:{}:/bin/sh\n", user, user, home);
+    }
+    return std::format(
+        "root:x:0:0:root:/root:/bin/sh\n"
+        "{}:x:{}:{}:{}:{}:/bin/sh\n",
+        user, uid, gid, user, home);
+}
+
+std::string make_etc_group_(const std::string& user, gid_t gid) {
+    // Mirror passwd: a single gid-0 entry when running as root avoids a
+    // duplicate group-0 record (root + <user> both gid 0).
+    if (gid == 0) {
+        return std::format("{}:x:0:\n", user);
+    }
+    return std::format(
+        "root:x:0:\n"
+        "{}:x:{}:\n",
+        user, gid);
+}
+
+// Initialize the sandbox-specific dirs / templates inside an existing
+// subos. Idempotent: only writes files that don't yet exist, so a
+// returning sandbox session won't clobber user customizations and a
+// repeated `subos use --sandbox` is cheap.
+void init_sandbox_dirs_(const fs::path& subos_dir,
+                        const std::string& user,
+                        uid_t uid, gid_t gid)
+{
+    auto user_home = subos_dir / "home" / user;
+    fs::create_directories(user_home);
+    fs::create_directories(subos_dir / "tmp");
+    auto etc = subos_dir / "etc";
+    fs::create_directories(etc);
+
+    // Empty `subos/` marker dir at sandbox root. xlings's project
+    // discovery walks cwd → / looking for `.xlings.json`; it stops at
+    // any dir that ALSO contains a `subos/` sibling (xlings-home
+    // boundary check, see config.cppm load_project_config_). Without
+    // this marker, the sandbox's own `<subos>/.xlings.json` (the
+    // workspace file, which appears at `/.xlings.json` inside the
+    // chroot) gets misinterpreted as an anonymous-project root, which
+    // OVERRIDES the per-shell XLINGS_ACTIVE_SUBOS=<name> and routes
+    // all install / shim / workspace paths into a phantom
+    // `<subos>/.xlings/subos/_/` tree disjoint from where PATH points.
+    // Empty `<subos>/subos/` ≈ "this is an xlings-managed dir, not a
+    // user project root" — boundary check terminates the walk.
+    fs::create_directories(subos_dir / "subos");
+
+    // Pseudo-root for proot chroot (`-r`). Using an empty directory
+    // that is NOT the subos_dir itself avoids a proot detranslate_path
+    // bug: when the subos rootfs is under `~/.xlings/` and proot
+    // also has `--bind=~/.xlings:~/.xlings`, the host path
+    // `~/.xlings/subos/<name>/usr` is ambiguously interpretable as
+    // both "rootfs + /usr" (→ matches --bind=/usr:/usr) and "~/.xlings
+    // bind + subos/<name>/usr" (→ the real subos dir). proot chooses
+    // the former, causing `cd subos/<name>/usr && ls` to show host
+    // /usr instead of the subos's own usr/.
+    //
+    // Fix: use `<subos>/sandbox-root/` (always empty, mode 0555) as
+    // the proot chroot root. Since `sandbox-root/usr` never exists,
+    // the detranslate prefix-strip cannot produce `/usr`, and the
+    // ambiguity disappears. All real content is bind-mounted in.
+    {
+        auto sandbox_root = subos_dir / "sandbox-root";
+        fs::create_directories(sandbox_root);
+        std::error_code perm_ec;
+        fs::permissions(sandbox_root,
+                        fs::perms::owner_read | fs::perms::owner_exec |
+                        fs::perms::group_read | fs::perms::group_exec |
+                        fs::perms::others_read | fs::perms::others_exec,
+                        fs::perm_options::replace, perm_ec);
+    }
+
+    auto try_write = [&](const fs::path& path, std::string_view body) {
+        if (fs::exists(path)) return;
+        platform::write_string_to_file(path.string(), std::string(body));
+    };
+    try_write(etc / "passwd", make_etc_passwd_(user, uid, gid));
+    try_write(etc / "group", make_etc_group_(user, gid));
+    try_write(etc / "hosts", kEtcHosts);
+    try_write(etc / "nsswitch.conf", kEtcNsswitch);
+
+    // Seed shell rc files so the xlings profile gets sourced (PATH +
+    // prompt pill). Sandbox-private; user can edit freely.
+    write_sandbox_rc_(user_home);
+    auto fish_config_dir = user_home / ".config" / "fish";
+    fs::create_directories(fish_config_dir);
+    try_write(fish_config_dir / "config.fish", kSandboxFishConfig);
+}
+
+#endif // __linux__ / __APPLE__
+
+int init_image_(const fs::path& img, const std::string& size) {
+    if (fs::exists(img)) return 0;
+    auto truncate_cmd = "truncate -s " + size + " " + img.string();
+    if (std::system(truncate_cmd.c_str()) != 0) return 1;
+    auto mkfs_cmd = "mkfs.ext4 -F -m 0 -q " + img.string() + " 2>/dev/null";
+    return std::system(mkfs_cmd.c_str());
+}
+
+bool is_mounted_(const fs::path& path) {
+    auto cmd = "mountpoint -q " + path.string() + " 2>/dev/null";
+    return std::system(cmd.c_str()) == 0;
+}
+
+// Mount an image file at mountpoint. Supports multi-terminal reuse.
+// After mount, chown the mountpoint root to the calling user so
+// subsequent directory/file creation doesn't need sudo.
+int mount_image_(const fs::path& img, const fs::path& mountpoint,
+                 const std::string& user = {}) {
+    fs::create_directories(mountpoint);
+    if (is_mounted_(mountpoint)) return 0;  // already mounted
+
+    // mount (privileged). priv_prefix() is "" when already root — sudo is
+    // redundant and frequently absent in minimal root containers, where the
+    // old hardcoded "sudo mount" died with "sudo: command not found".
+    auto cmd = platform::priv_prefix() + "mount -o loop " + img.string() + " "
+               + mountpoint.string();
+    auto rc = std::system(cmd.c_str());
+    if (rc != 0) return rc;
+
+    // ext4 root dir is owned by root after mkfs; chown to real user
+    // so sandbox init can create dirs without sudo.
+    if (!user.empty()) {
+        auto chown_cmd = platform::priv_prefix() + "chown " + user + ":" + user
+                         + " " + mountpoint.string();
+        std::system(chown_cmd.c_str());
+    }
+    return 0;
+}
+
+int unmount_image_(const fs::path& mountpoint) {
+    if (!is_mounted_(mountpoint)) return 0;
+    auto cmd = platform::priv_prefix() + "umount " + mountpoint.string()
+               + " 2>/dev/null";
+    return std::system(cmd.c_str());
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Sandbox subos entry — proot-based fs-isolated session.
+//
+// Triggered when `subos use <name>` reads a subos config that has the
+// `sandbox-shell` field. Only available on Linux (proot uses ptrace +
+// Linux syscall conventions). On non-Linux platforms the sandbox config
+// is rejected at create time, so this code path is unreachable there;
+// guard with #if defined(__linux__) and stub elsewhere.
+//
+// See docs/plans/2026-05-09-subos-sandbox-design.md for full rationale.
+// ─────────────────────────────────────────────────────────────────────
+
+
+// Probe order for the proot binary:
+//   1. <home>/data/xpkgs/xim-x-proot/<ver>/bin/proot   the PAYLOAD
+//   2. <home>/runtimedir/proot                         auto-fetch cache
+//   3. /usr/bin/proot, /usr/local/bin/proot            the HOST (reported)
+//
+// PATH is deliberately absent -- see (3) below. The same rule, in the same
+// shape, as libxpkg's elfpatch tool lookup: payload, then a named fallback
+// that says so. Both implement R6 (internal consumers bind the payload, not
+// the view), .agents/docs/2026-08-06-subos-architecture-proposal.md §1.5.
+//
+// Returns the path to a usable proot, or unexpected with a hint string.
+std::expected<fs::path, std::string>
+locate_proot_(const fs::path& home_dir) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+
+    // (1) xpkg-managed (look at versions DB)
+    //
+    // Iterating with explicit directory_iterator + sentinel comparison
+    // (not range-for over a wrapper) sidesteps a libstdc++ copy-ctor
+    // visibility issue we hit on gcc 15.1.0 musl-cross when this header
+    // is exposed via BMI: the range-for path required `directory_iterator
+    // (directory_iterator const&)` to be visible at the inline expansion
+    // site inside another module's TU, and the cross-toolchain link
+    // surfaced it as "undefined reference to __cxx11::directory_iterator
+    // ctor" in capabilities.cppm. Using sentinel `{}` comparison avoids
+    // the copy entirely.
+    auto xpkgs_dir = home_dir / "data" / "xpkgs";
+    auto xpkg_proot_root = xpkgs_dir / "xim-x-proot";
+    if (fs::is_directory(xpkg_proot_root, ec)) {
+        // Sentinel form (`it != default_sentinel`) instead of comparing
+        // two directory_iterators directly. Clang/libc++ only provides
+        // the sentinel comparison in C++20+; comparing two
+        // directory_iterators yields "invalid operands to binary
+        // expression" on macOS clang. Sentinel form works on both
+        // libstdc++ (Linux gcc) and libc++ (macOS clang).
+        std::error_code it_ec;
+        for (auto it = fs::directory_iterator(xpkg_proot_root, it_ec);
+             !it_ec && it != std::default_sentinel;
+             it.increment(it_ec))
+        {
+            auto candidate = it->path() / "bin" / "proot";
+            if (fs::is_regular_file(candidate, ec)) return candidate;
+        }
+    }
+
+    // (2) auto-fetch cache
+    auto runtime_proot = home_dir / "runtimedir" / "proot";
+    if (fs::is_regular_file(runtime_proot, ec)) return runtime_proot;
+
+    // (3) The host's proot, at the two paths a distribution puts it.
+    //
+    // There is no PATH step. An earlier version walked PATH and rejected the
+    // candidates that turned out to be xlings shims; that fixed the symptom
+    // and left the cause. By R6 the whole step is wrong for internal use: PATH
+    // is a *view*, it is what the user selected, and letting it decide which
+    // proot runs makes the sandbox's own identity depend on the environment
+    // the sandbox was launched from. A shim on PATH is the worst case -- it
+    // re-enters xlings, anchors to the home that owns it, and re-exports
+    // XLINGS_HOME to match, so an isolated home with no backend installed
+    // would silently run against the developer's real home, and every
+    // measurement taken inside would be of the wrong home while looking
+    // exactly like a measurement of the right one.
+    //
+    // These two paths are different in kind: they are the host's, they are
+    // named here rather than discovered, and using one is reported. Per §2.8
+    // of the architecture proposal, depending on the host is allowed when it
+    // is DECLARED -- what is not allowed is depending on it by accident.
+    for (const auto* p : {"/usr/bin/proot", "/usr/local/bin/proot"}) {
+        auto candidate = fs::path(p);
+        if (!fs::is_regular_file(candidate, ec)) continue;
+        // Defensive: a home that installed itself under /usr/local would put
+        // a shim on one of these paths, and it is still a shim.
+        if (auto owner = xvm::resolve_owner_home(candidate)) {
+            log::debug("skipping {}: an xlings shim owned by {}, not the "
+                       "host's proot", candidate.string(), owner->string());
+            continue;
+        }
+        log::warn("using the host's proot ({}) -- no proot payload in {}. "
+                  "Run `xlings install proot` to make this deterministic.",
+                  candidate.string(), home_dir.string());
+        return candidate;
+    }
+
+    // Naming the home rather than "~/.xlings": with an isolated XLINGS_HOME
+    // the tilde form points somewhere the caller is not using, and a
+    // reader who follows it lands on the very home this search excluded.
+    return std::unexpected(std::format(
+        "proot not found in {}. Run `xlings install proot`, or place a proot "
+        "binary at {}/runtimedir/proot. The host's proot at /usr/bin/proot is "
+        "used when present (`sudo apt install proot`), but PATH is not "
+        "searched: a `proot` on PATH may be an xlings shim, and running it "
+        "would move the whole session to whichever home owns it.",
+        home_dir.string(), home_dir.string()));
+}
+
+std::vector<SandboxBind>
+sandbox_binds_(const fs::path& subos_dir,
+               const fs::path& host_xlings_home,
+               const std::string& user,
+               StorageMode storage = StorageMode::Shared,
+               const fs::path& mountpoint = {})
+{
+    auto etc = subos_dir / "etc";
+    auto user_home = "/home/" + user;
+
+    std::error_code ec;
+
+    auto try_ro = [&](std::vector<SandboxBind>& v,
+                      const char* src, const char* dst) {
+        if (fs::exists(src, ec))
+            v.push_back({src, dst, true});
+    };
+
+    std::vector<SandboxBind> binds;
+
+    // ── Host RO: POSIX userland (tools + libs + loader) ──
+    try_ro(binds, "/usr", "/usr");
+    try_ro(binds, "/bin", "/bin");
+    try_ro(binds, "/usr/lib", "/lib");
+    try_ro(binds, "/usr/lib64", "/lib64");
+
+    // ── Host RO: /etc (by-need) ──
+    try_ro(binds, "/etc/resolv.conf", "/etc/resolv.conf");
+    try_ro(binds, "/etc/ld.so.cache", "/etc/ld.so.cache");
+    try_ro(binds, "/etc/ssl", "/etc/ssl");
+    try_ro(binds, "/etc/pki", "/etc/pki");
+    try_ro(binds, "/etc/alternatives", "/etc/alternatives");
+    try_ro(binds, "/etc/localtime", "/etc/localtime");
+
+    // ── Sandbox RW: private overrides (storage-dependent) ──
+    if (storage == StorageMode::Shared) {
+        binds.push_back({(subos_dir / "home").string(), "/home", false});
+        binds.push_back({(subos_dir / "tmp").string(), "/tmp", false});
+    } else if (storage == StorageMode::Image) {
+        // home from mounted image; tmp uses bwrap --tmpfs (added in argv)
+        binds.push_back({mountpoint.string(), "/home", false});
+    }
+    // tmpfs: home and tmp handled by bwrap --tmpfs (no bind needed)
+
+    // xlings shared — always bound regardless of storage mode, and always
+    // at its OWN absolute path.
+    //
+    // xvm alias targets, RPATH and INTERP are absolute host paths baked at
+    // install time, and nothing rewrites them on the way in; the home has
+    // to answer to the same spelling in here that it does outside. Mapping
+    // it to <user_home>/.xlings instead strands all of them, and mapping it
+    // to both makes one directory reachable by two real paths — which a
+    // bind mount does not collapse, so canonicalising does not save you and
+    // a shim ends up reporting a conflict with itself. For the default home
+    // this bind IS <user_home>/.xlings; that coincidence is the only reason
+    // the remapped form ever appeared to work.
+    binds.push_back({host_xlings_home.string(), host_xlings_home.string(), false});
+
+    // ── Sandbox: NSS templates ──
+    binds.push_back({(etc / "passwd").string(), "/etc/passwd", false});
+    binds.push_back({(etc / "group").string(), "/etc/group", false});
+    binds.push_back({(etc / "hosts").string(), "/etc/hosts", false});
+    binds.push_back({(etc / "nsswitch.conf").string(), "/etc/nsswitch.conf", false});
+
+    return binds;
+}
+
+// Build proot argv from unified bind list. When `cmd` is non-empty, ends
+// in `<shell> -c <cmd>` for non-interactive single-command exec (M3);
+// otherwise just `<shell>` for the standard interactive entry.
+std::vector<std::string>
+build_proot_argv_(const fs::path& proot_bin,
+                  const fs::path& subos_dir,
+                  const fs::path& host_xlings_home,
+                  const std::string& user,
+                  const std::string& shell_path,
+                  const std::string& cmd = "")
+{
+    auto user_home = "/home/" + user;
+    // Use sandbox-root/ as the chroot root instead of subos_dir itself.
+    // This avoids the proot detranslate_path bug where host paths under
+    // subos_dir (e.g. subos/<name>/usr) get mis-translated to /usr when
+    // the rootfs prefix is stripped. See init_sandbox_dirs_ for details.
+    auto proot_root = subos_dir / "sandbox-root";
+    std::vector<std::string> argv = {
+        proot_bin.string(),
+        "-r", proot_root.string(),
+        "--bind=/proc:/proc",
+        "--bind=/sys:/sys",
+        "--bind=/dev:/dev",
+    };
+
+    for (auto& b : sandbox_binds_(subos_dir, host_xlings_home, user)) {
+        argv.push_back(std::format("--bind={}:{}", b.src, b.dst));
+    }
+
+    argv.push_back(std::format("--cwd={}", user_home));
+    argv.push_back(shell_path);
+    if (!cmd.empty()) {
+        argv.push_back("-c");
+        argv.push_back(cmd);
+    }
+    return argv;
+}
+
+// ── bwrap backend (V5) ────────────────────────────────────────────────
+
+// Locate bwrap binary — only searches xim:bwrap pool.
+// System-installed bwrap (/usr/bin/bwrap) is intentionally skipped:
+// distro packages lack setuid, and AppArmor/kernel restrictions on
+// unprivileged user namespaces make system binaries unreliable on
+// Ubuntu 24+, Fedora, etc. xim:bwrap is built with
+// `-Dsupport_setuid=true` (xlings-res/bwrap mirror) and its install
+// hook sets the binary setuid root (chmod 4755) — that combination is
+// what makes the xim-managed binary work across distros where unpriv
+// userns is restricted.
+std::expected<fs::path, std::string>
+locate_bwrap_(const fs::path& home_dir) {
+    std::error_code ec;
+
+    auto xpkg_root = home_dir / "data" / "xpkgs" / "xim-x-bwrap";
+    if (fs::is_directory(xpkg_root, ec)) {
+        std::error_code it_ec;
+        for (auto it = fs::directory_iterator(xpkg_root, it_ec);
+             !it_ec && it != std::default_sentinel;
+             it.increment(it_ec))
+        {
+            auto candidate = it->path() / "bin" / "bwrap";
+            if (fs::is_regular_file(candidate, ec)) return candidate;
+        }
+    }
+
+    return std::unexpected(
+        "bwrap not installed, run: xlings install bwrap");
+}
+
+// Probe whether a bwrap binary can actually create a sandbox.
+// Returns {ok, output}. `output` captures stdout+stderr (the platform
+// helper appends `2>&1` internally) so callers can classify the
+// failure cause — see classify_bwrap_probe_error_ for the known modes.
+std::pair<bool, std::string>
+probe_bwrap_(const fs::path& bwrap_bin) {
+    auto cmd = platform::shell_quote(bwrap_bin.string())
+             + " --ro-bind / / -- /bin/true";
+    auto [status, output] = platform::run_command_capture(cmd);
+    return { status == 0, std::move(output) };
+}
+
+// Translate a failed bwrap probe's captured output into an actionable
+// hint. Three known modes; anything else falls through to "show the
+// raw stderr" so users always see the truth instead of a stale
+// "xlings install bwrap" suggestion that won't help.
+std::string classify_bwrap_probe_error_(const std::string& output,
+                                         const fs::path& bin) {
+    if (output.find("setuid use of bubblewrap is not supported")
+        != std::string::npos)
+    {
+        return "xim:bwrap binary was built without setuid support; "
+               "rebuild xlings-res/bwrap mirror with "
+               "`-Dsupport_setuid=true` and bump the version\n"
+               "  binary: " + bin.string();
+    }
+    if (output.find("setting up uid map: Permission denied")
+        != std::string::npos
+        || output.find("write to uid_map failed")
+        != std::string::npos)
+    {
+        return "kernel restricts unprivileged user namespaces "
+               "(LSM/AppArmor)\n"
+               "  check: cat /proc/sys/kernel/"
+               "apparmor_restrict_unprivileged_userns\n"
+               "  workaround: sudo sysctl -w "
+               "kernel.apparmor_restrict_unprivileged_userns=0";
+    }
+    if (output.find("clone() failed: Operation not permitted")
+        != std::string::npos
+        || output.find("user namespaces are not enabled")
+        != std::string::npos)
+    {
+        return "kernel disables unprivileged_userns_clone\n"
+               "  check: cat /proc/sys/kernel/"
+               "unprivileged_userns_clone";
+    }
+    auto trimmed = output;
+    while (!trimmed.empty() &&
+           (trimmed.back() == '\n' || trimmed.back() == '\r'))
+        trimmed.pop_back();
+    return "bwrap probe failed; raw output:\n  " + trimmed;
+}
+
+// Build bwrap argv from unified bind list. Uses targeted --ro-bind
+// instead of `--ro-bind / /` to match proot's security profile
+// (same host paths exposed, same sandbox-private paths).
+// When `cmd` is non-empty, ends with `<shell> -c <cmd>` for non-
+// interactive single-command exec (M3); otherwise interactive shell.
+std::vector<std::string>
+build_bwrap_argv_(const fs::path& bwrap_bin,
+                  const fs::path& subos_dir,
+                  const fs::path& host_xlings_home,
+                  const std::string& user,
+                  const std::string& shell_path,
+                  bool interactive_shell,
+                  StorageMode storage = StorageMode::Shared,
+                  const fs::path& mountpoint = {},
+                  bool gpu = false,
+                  const std::string& cmd = "")
+{
+    auto user_home = "/home/" + user;
+    std::vector<std::string> argv = {
+        bwrap_bin.string(),
+        "--dev", "/dev",
+        "--proc", "/proc",
+    };
+
+    for (auto& b : sandbox_binds_(subos_dir, host_xlings_home, user,
+                                   storage, mountpoint)) {
+        if (b.readonly) {
+            argv.insert(argv.end(), {"--ro-bind", b.src, b.dst});
+        } else {
+            argv.insert(argv.end(), {"--bind", b.src, b.dst});
+        }
+    }
+
+    // GPU passthrough: must come after `--dev /dev` (which creates the
+    // empty tmpfs we'll mount nodes onto). Each --dev-bind is host-path
+    // → sandbox-path; missing nodes are silently skipped by gpu.cppm.
+    if (gpu) {
+        auto extra = xlings::subos::gpu::passthrough_args();
+        argv.insert(argv.end(), extra.begin(), extra.end());
+    }
+
+    // tmpfs mode: home and tmp are pure memory (exit = gone)
+    if (storage == StorageMode::Tmpfs) {
+        argv.insert(argv.end(), {"--tmpfs", user_home});
+        argv.insert(argv.end(), {"--tmpfs", "/tmp"});
+    }
+    // image mode: tmp uses tmpfs (home is bind-mounted from .mountpoint)
+    if (storage == StorageMode::Image) {
+        argv.insert(argv.end(), {"--tmpfs", "/tmp"});
+    }
+
+    argv.insert(argv.end(), {"--chdir", user_home, "--", shell_path});
+    if (!cmd.empty()) {
+        // Non-interactive single-command exec: shell -c <cmd>. The -i
+        // flag would print prompts/job-control warnings to captured
+        // stdout, so we omit it even if interactive_shell=true.
+        argv.push_back("-c");
+        argv.push_back(cmd);
+    } else if (interactive_shell) {
+        argv.push_back("-i");
+    }
+    return argv;
+}
+
+// Show bwrap hint — only on first sandbox use of a subos (detected by
+// whether <subos>/home/ exists; init_sandbox_dirs_ creates it, so if
+// it's missing, this is the first --sandbox entry for this subos).
+void maybe_show_bwrap_hint_(const fs::path& subos_dir) {
+    std::error_code ec;
+    if (fs::is_directory(subos_dir / "home", ec)) return;
+
+    log::info("bwrap not installed or namespace probe failed");
+    log::info("  to enable bwrap (recommended): xlings install bwrap");
+    log::info("  using proot fallback for now");
+}
+
+std::optional<BackendInfo>
+detect_backend_(const fs::path& home_dir,
+                const fs::path& subos_dir = {}) {
+    // 1. bwrap (xim pool) — preferred for native compat
+    if (auto bin = locate_bwrap_(home_dir)) {
+        if (probe_bwrap_(*bin).first)
+            return BackendInfo{ SandboxBackend::Bwrap, *bin };
+    }
+
+    // bwrap found but probe failed → show hint (first use only)
+    if (locate_bwrap_(home_dir) && !subos_dir.empty()) {
+        maybe_show_bwrap_hint_(subos_dir);
+    }
+
+    // 2. proot — zero-privilege fallback
+    if (auto bin = locate_proot_(home_dir))
+        return BackendInfo{ SandboxBackend::Proot, *bin };
+
+    return std::nullopt;
+}
+
+// Should we even try to fetch a sandbox backend for this host? Answered from
+// the on-disk index, with no network access.
+//
+// The evidence rule here is deliberately stricter than the one `xlings
+// install` uses, and the difference is who asked. A package-level `archs`
+// union is weak evidence -- it went unenforced for all of spec V1 and is
+// routinely under-declared -- so it must never veto an install the USER named:
+// being wrong there means refusing a package that works, and the user has no
+// way around it.
+//
+// This install is one nobody asked for. `--sandbox` triggers it implicitly,
+// and being wrong costs only a skipped auto-install that
+// `xlings install bwrap` still overrides. Being wrong the other way costs
+// every `--sandbox` invocation on the arch a download that 404s, ~45s of
+// waiting, and a diagnostic that blames the installer rather than naming the
+// target. So a weak signal is enough to decline here.
+//
+// What it is NOT is a compile-time `#if defined(__aarch64__)`, which is what
+// this replaced: that freezes a claim about the package index into the binary,
+// so the day an aarch64 backend is published every client in the field still
+// refuses. This is re-read from the index on every call.
+std::optional<std::string> backend_target_unavailable_() {
+    auto& catalog = xim::get_catalog(xim::CatalogAccess::LocalOnly);
+    if (!catalog.is_loaded()) return std::nullopt;
+
+    const auto hostArch = xim::host_architecture();
+    std::string target;
+    for (const auto* name : {"bwrap", "proot"}) {
+        auto match = catalog.resolve_target(name, "linux");
+        if (!match) return std::nullopt;          // cannot say -> let it try
+        auto pkg = catalog.load_package(*match);
+        if (!pkg) return std::nullopt;
+        const auto* entry = xim::find_entry(*pkg, "linux", match->version);
+        const auto compatibility = xim::check_target_compatibility(
+            *pkg, entry, "linux", hostArch);
+        target = compatibility.target;
+        // Supported AND not merely "we could not tell": an advisory means the
+        // recipe does not claim this arch, which is as much as an
+        // auto-install needs to hear.
+        if (compatibility.supported && compatibility.advisory.empty()) {
+            return std::nullopt;
+        }
+    }
+    return std::format(
+        "E_UNSUPPORTED_TARGET: no sandbox backend has a {} artifact", target);
+}
+
+int auto_install_backend_(const fs::path& home_dir, EventStream& stream) {
+    // Try bwrap first (build from source, config hook sets setuid)
+    log::info("installing sandbox backend...");
+    {
+        std::vector<std::string> t = {"xim:bwrap"};
+        xim::cmd_install(t, /*yes=*/true, /*noDeps=*/false, stream);
+        auto bin = locate_bwrap_(home_dir);
+        if (bin && probe_bwrap_(*bin).first) return 0;
+    }
+
+    // bwrap installed but namespace restricted → proot fallback
+    // (hint already shown by detect_backend_ on first use)
+
+    std::vector<std::string> t = {"xim:proot"};
+    return xim::cmd_install(t, /*yes=*/true, /*noDeps=*/false, stream);
+}
+
+int enter(const std::string& name, EventStream& stream, const std::string& preferred_backend, bool gpu, const std::string& cmd) {
+
+    // Refuse nested sandbox entry.
+    if (utils::get_env_or_default("XLINGS_SUBOS_MODE") == "sandbox") {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = "cannot enter sandbox from inside another sandbox",
+            .recoverable = true,
+            .hint = "type 'exit' first to leave the current one",
+        });
+        return 1;
+    }
+
+    auto& p = Config::paths();
+    auto subos_dir = p.homeDir / "subos" / name;
+
+    // ── Storage mode (V6) ──
+    auto storage = read_storage_mode_(subos_dir);
+
+    // ── Resolve user ──
+#if defined(_WIN32)
+    auto user = utils::get_env_or_default("USERNAME");
+    if (user.empty()) user = "user";
+#else
+    auto user = utils::get_env_or_default("USER");
+    if (user.empty()) user = "user";
+#endif
+
+    auto sandbox_home = (subos_dir / "home" / user).string();
+    auto sandbox_tmp = (subos_dir / "tmp").string();
+
+    // Image mountpoint (populated in the Linux block below if image mode)
+    fs::path image_mountpoint;
+    if (storage == StorageMode::Image)
+        image_mountpoint = subos_dir / ".mountpoint";
+
+    // ── Lazy init sandbox dirs (shared mode only) ──
+    if (storage == StorageMode::Shared) {
+        fs::create_directories(subos_dir / "home" / user);
+        fs::create_directories(subos_dir / "tmp");
+    }
+
+#if defined(__linux__) || defined(__APPLE__)
+    // Seed shell rc files so profile is sourced (prompt pill + PATH).
+    // For image mode, rc files go into the mounted image (deferred until
+    // after mount in the Linux block below). For shared/tmpfs, seed now.
+    if (storage == StorageMode::Shared) {
+        auto user_home_dir = subos_dir / "home" / user;
+        fs::create_directories(user_home_dir);
+        write_sandbox_rc_(user_home_dir);
+    }
+#endif
+
+    // ── Common env (all platforms) ──
+    platform::set_env_variable("XLINGS_ACTIVE_SUBOS", name);
+    platform::set_env_variable("XLINGS_SUBOS_MODE", "sandbox");
+    // E2a, same declaration as the non-sandbox path. Declared here too and
+    // not only there: a contract that holds in one of the two ways users
+    // enter a subos is a contract consumers cannot rely on, and the sandbox
+    // is the mode the graphics acceptance tooling runs in.
+    platform::set_env_variable("XLINGS_SUBOS_LIB",
+                               (subos_dir / "lib").string());
+
+    nlohmann::json payload;
+    payload["name"] = name;
+    payload["mode"] = "sandbox";
+
+    std::cout.flush();
+    std::cerr.flush();
+
+#if defined(__linux__)
+    // ═══════════════════════════════════════════════════════════════
+    // Linux L3: FS view isolation via bwrap/proot
+    // ═══════════════════════════════════════════════════════════════
+
+    // image/tmpfs storage requires bwrap (mount namespace needed)
+    if (storage != StorageMode::Shared && !preferred_backend.empty()
+        && preferred_backend == "proot") {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = "image/tmpfs storage requires bwrap sandbox backend",
+            .recoverable = false,
+            .hint = "run: xlings install bwrap",
+        });
+        return 1;
+    }
+
+    // ── Image mode: mount image before sandbox entry ──
+    if (storage == StorageMode::Image) {
+        auto img = subos_dir / "home.img";
+        if (!fs::exists(img)) {
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::NotFound,
+                .message = "home.img not found — was this subos created with --storage image?",
+                .recoverable = false,
+            });
+            return 1;
+        }
+        auto rc = mount_image_(img, image_mountpoint, user);
+        if (rc != 0) {
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::Internal,
+                .message = "failed to mount home.img",
+                .recoverable = false,
+                .hint = "ensure you have sudo permission for mount",
+            });
+            return 1;
+        }
+    }
+
+    // /etc templates for Linux sandbox (NSS)
+    {
+        auto uid = ::getuid();
+        auto gid = ::getgid();
+        init_sandbox_dirs_(subos_dir, user, uid, gid);
+        // For image mode, init home and seed shell rc files inside the mount
+        if (storage == StorageMode::Image) {
+            auto mp_home = image_mountpoint / user;
+            fs::create_directories(mp_home);
+            write_sandbox_rc_(mp_home);
+        }
+    }
+
+    // Backend selection (the using-declarations that stood here named
+    // sandbox_detail_:: and are redundant now that this IS that namespace)
+    std::optional<BackendInfo> backend;
+
+    if (preferred_backend == "bwrap") {
+        auto bin = locate_bwrap_(p.homeDir);
+        if (!bin) {
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::NotFound,
+                .message = "bwrap not installed",
+                .recoverable = false,
+                .hint = "run: xlings install bwrap",
+            });
+            return 1;
+        }
+        if (auto probe = probe_bwrap_(*bin); !probe.first) {
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::NotFound,
+                .message = "bwrap probe failed",
+                .recoverable = false,
+                .hint = classify_bwrap_probe_error_(
+                            probe.second, *bin),
+            });
+            return 1;
+        }
+        backend = BackendInfo{ SandboxBackend::Bwrap, *bin };
+    } else if (preferred_backend == "proot") {
+        auto bin = locate_proot_(p.homeDir);
+        if (!bin) {
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::NotFound,
+                .message = std::move(bin).error(),
+                .recoverable = false,
+                .hint = "run: xlings install proot",
+            });
+            return 1;
+        }
+        backend = BackendInfo{ SandboxBackend::Proot, *bin };
+    } else {
+        backend = detect_backend_(p.homeDir, subos_dir);
+        if (!backend) {
+            // Ask the index whether it ships a backend for this target before
+            // touching the network, so an unsupported host gets one causal
+            // error and zero download requests.
+            //
+            // This used to be `#if defined(__aarch64__)`, which is a claim
+            // about the package index frozen into the binary at compile time:
+            // the day xim-pkgindex publishes an aarch64 bwrap, every client
+            // already in the field would still refuse. Reading the on-disk
+            // index costs nothing and is right both before and after that day.
+            if (auto unavailable = backend_target_unavailable_(); unavailable) {
+                stream.emit(ErrorEvent{
+                    .code = ErrorCode::InvalidInput,
+                    .message = *unavailable,
+                    .recoverable = false,
+                    .hint = "use shell isolation, install your distribution's "
+                            "bubblewrap package, or `xlings install bwrap` to "
+                            "try anyway",
+                });
+                return 1;
+            }
+            auto rc = auto_install_backend_(p.homeDir, stream);
+            if (rc != 0) {
+                stream.emit(ErrorEvent{
+                    .code = ErrorCode::NotFound,
+                    .message = "failed to install sandbox backend",
+                    .recoverable = false,
+                    .hint = "manually: xlings install bwrap (or: xlings install proot)",
+                });
+                return 1;
+            }
+            backend = detect_backend_(p.homeDir, subos_dir);
+            if (!backend) {
+                stream.emit(ErrorEvent{
+                    .code = ErrorCode::NotFound,
+                    .message = "no sandbox backend available after install attempt",
+                    .recoverable = false,
+                });
+                return 1;
+            }
+        }
+    }
+
+    // image/tmpfs requires bwrap — reject proot after auto-detect
+    if (storage != StorageMode::Shared
+        && backend->type != SandboxBackend::Bwrap) {
+        // If bwrap is actually installed but probe failed (the common
+        // case that triggers the proot fallback), surface the real
+        // probe error rather than the misleading "xlings install bwrap"
+        // suggestion that won't help.
+        std::string hint = "run: xlings install bwrap";
+        if (auto bin = locate_bwrap_(p.homeDir)) {
+            if (auto probe = probe_bwrap_(*bin);
+                !probe.first)
+            {
+                hint = classify_bwrap_probe_error_(
+                            probe.second, *bin);
+            }
+        }
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = storage_to_string_(storage)
+                       + " storage requires bwrap (proot does not support mount namespace)",
+            .recoverable = false,
+            .hint = std::move(hint),
+        });
+        if (storage == StorageMode::Image)
+            unmount_image_(image_mountpoint);
+        return 1;
+    }
+
+    auto backend_name = (backend->type == SandboxBackend::Bwrap) ? "bwrap" : "proot";
+    log::debug("sandbox backend: {} storage: {}", backend_name,
+               storage_to_string_(storage));
+
+    auto user_home = "/home/" + user;
+    auto shell = utils::get_env_or_default("SHELL");
+    if (shell.empty()) shell = "/bin/sh";
+
+    payload["backend"] = backend_name;
+    payload["shell"] = shell;
+    payload["storage"] = storage_to_string_(storage);
+    stream.emit(DataEvent{"subos_entering", payload.dump()});
+
+    platform::set_env_variable("HOME", user_home);
+    // Pin the home explicitly rather than relying on inheritance: it is
+    // reachable at its own absolute path in here (see sandbox_binds_), and
+    // every path baked at install time — xvm targets, RPATH, INTERP —
+    // assumes exactly that spelling.
+    platform::set_env_variable("XLINGS_HOME", p.homeDir.string());
+    // Same spelling as XLINGS_HOME above. A shim decides which home owns it
+    // by comparing the path it was invoked through against XLINGS_HOME as
+    // strings; spelling the home two ways here makes it warn about a
+    // conflict with itself.
+    platform::set_env_variable("PATH", std::format(
+        "{0}/subos/{1}/bin:{0}/bin:/usr/local/bin:/usr/bin:/bin",
+        p.homeDir.string(), name));
+    // bwrap `sh -i` prints prompts/job-control warnings into piped CI
+    // commands; keep `-i` only for real terminal sessions.
+    const bool interactive_shell = ::isatty(STDIN_FILENO) == 1;
+
+    std::vector<std::string> argv;
+    if (backend->type == SandboxBackend::Bwrap) {
+        argv = build_bwrap_argv_(
+            backend->binary, subos_dir, p.homeDir, user, shell,
+            interactive_shell, storage, image_mountpoint, gpu, cmd);
+    } else {
+        // proot already exposes the full host /dev and /sys via
+        // `--bind=/dev:/dev --bind=/sys:/sys`, so GPU devices are
+        // visible for free. --gpu is a no-op here.
+        argv = build_proot_argv_(
+            backend->binary, subos_dir, p.homeDir, user, shell, cmd);
+        platform::set_env_variable("PROOT_NO_SECCOMP", "1");
+    }
+
+    std::vector<char*> c_argv;
+    c_argv.reserve(argv.size() + 1);
+    for (auto& s : argv) c_argv.push_back(const_cast<char*>(s.c_str()));
+    c_argv.push_back(nullptr);
+
+    // Image mode: fork+exec+wait so we can unmount after sandbox exits.
+    // Shared/tmpfs: execvp replaces the process (no cleanup needed).
+    if (storage == StorageMode::Image) {
+        auto pid = ::fork();
+        if (pid < 0) {
+            log::error("fork failed: {}", std::strerror(errno));
+            unmount_image_(image_mountpoint);
+            return 1;
+        }
+        if (pid == 0) {
+            // Child: enter sandbox
+            ::execvp(c_argv[0], c_argv.data());
+            log::error("failed to exec {}: {}", backend_name, std::strerror(errno));
+            ::_exit(127);
+        }
+        // Parent: wait then unmount
+        int status = 0;
+        ::waitpid(pid, &status, 0);
+        unmount_image_(image_mountpoint);
+        return WIFEXITED(status) ? WEXITSTATUS(status) : 1;
+    }
+
+    ::execvp(c_argv[0], c_argv.data());
+    log::error("failed to exec {} '{}': {}", backend_name,
+               backend->binary.string(), std::strerror(errno));
+    return 127;
+
+#elif defined(__APPLE__)
+    // ═══════════════════════════════════════════════════════════════
+    // macOS L2: HOME redirect (dotfile isolation)
+    // ═══════════════════════════════════════════════════════════════
+
+    // Ask the same resolver the launch is about to use. Deriving the reported
+    // shell here independently is how `subos_entering` came to announce
+    // `/bin/zsh` while the process that started was `/bin/sh`: two fallbacks
+    // for the same question, in two places, that only agree when SHELL is set.
+    // Say it where the person is, not only in the README. A user who reaches
+    // for `--sandbox` to run something they do not trust is exactly the user
+    // who did not read the isolation matrix, and on these two platforms this
+    // is a dotfile redirect -- no filesystem, network or process boundary.
+    //
+    // Only on interactive entry: a `--cmd` run is a script, and a warning it
+    // emits on every invocation is noise nobody reads. `--quiet` silences it.
+    if (cmd.empty()) {
+        log::warn("sandbox on {} redirects the home directory only -- "
+                  "it does not contain the filesystem, network or processes. "
+                  "Use an OS sandbox or a VM for untrusted code.",
+                  "macOS");
+    }
+
+    payload["backend"] = "home-redirect";
+    payload["shell"] = platform::resolve_shell();
+    stream.emit(DataEvent{"subos_entering", payload.dump()});
+
+    platform::set_env_variable("HOME", sandbox_home);
+    platform::set_env_variable("TMPDIR", sandbox_tmp);
+    platform::set_env_variable("XDG_CONFIG_HOME", sandbox_home + "/.config");
+    platform::set_env_variable("XDG_DATA_HOME", sandbox_home + "/.local/share");
+    platform::set_env_variable("XDG_CACHE_HOME", sandbox_home + "/.cache");
+    platform::set_env_variable("XDG_STATE_HOME", sandbox_home + "/.local/state");
+
+    return platform::run_shell(cmd, cmd.empty());
+
+#elif defined(_WIN32)
+    // ═══════════════════════════════════════════════════════════════
+    // Windows L2: USERPROFILE redirect (dotfile isolation)
+    // ═══════════════════════════════════════════════════════════════
+
+    // Pre-create AppData structure
+    fs::create_directories(fs::path(sandbox_home) / "AppData" / "Roaming");
+    fs::create_directories(fs::path(sandbox_home) / "AppData" / "Local");
+
+    // Say it where the person is, not only in the README. A user who reaches
+    // for `--sandbox` to run something they do not trust is exactly the user
+    // who did not read the isolation matrix, and on these two platforms this
+    // is a dotfile redirect -- no filesystem, network or process boundary.
+    //
+    // Only on interactive entry: a `--cmd` run is a script, and a warning it
+    // emits on every invocation is noise nobody reads. `--quiet` silences it.
+    if (cmd.empty()) {
+        log::warn("sandbox on {} redirects the home directory only -- "
+                  "it does not contain the filesystem, network or processes. "
+                  "Use an OS sandbox or a VM for untrusted code.",
+                  "Windows");
+    }
+
+    payload["backend"] = "home-redirect";
+    stream.emit(DataEvent{"subos_entering", payload.dump()});
+
+    platform::set_env_variable("USERPROFILE", sandbox_home);
+    platform::set_env_variable("APPDATA", sandbox_home + "\\AppData\\Roaming");
+    platform::set_env_variable("LOCALAPPDATA", sandbox_home + "\\AppData\\Local");
+    platform::set_env_variable("TEMP", sandbox_tmp);
+    platform::set_env_variable("TMP", sandbox_tmp);
+    platform::set_env_variable("XDG_CONFIG_HOME", sandbox_home + "\\.config");
+    platform::set_env_variable("XDG_DATA_HOME", sandbox_home + "\\.local\\share");
+    platform::set_env_variable("XDG_CACHE_HOME", sandbox_home + "\\.cache");
+
+    return platform::run_shell(cmd, cmd.empty());
+#endif
+}
+
+}
diff --git a/src/core/subos/sandbox.cppm b/src/core/subos/sandbox.cppm
index 581461fa..b132ae15 100644
--- a/src/core/subos/sandbox.cppm
+++ b/src/core/subos/sandbox.cppm
@@ -22,13 +22,9 @@ export module xlings.core.subos.sandbox;
 import std;
 
 import xlings.core.config;
-import xlings.libs.json;
-import xlings.core.log;
 import xlings.platform;
 import xlings.runtime;
-import xlings.core.utils;
 import xlings.core.xim.commands;  // auto_install_backend_ needs cmd_install
-import xlings.core.xim.compatibility;
 import xlings.core.subos.gpu;
 import xlings.core.xvm.shim;   // resolve_owner_home: reject another home's shim
 
@@ -58,15 +54,6 @@ namespace xlings::subos::sandbox {
 
 namespace fs = std::filesystem;
 
-nlohmann::json read_config_json_(const fs::path& path) {
-    if (!fs::exists(path)) return nlohmann::json::object();
-    try {
-        auto content = platform::read_file_to_string(path.string());
-        auto json = nlohmann::json::parse(content, nullptr, false);
-        return json.is_discarded() ? nlohmann::json::object() : json;
-    } catch (...) { return nlohmann::json::object(); }
-}
-
 // ── Storage mode (V6) ──────────────────────────────────────────────
 // Storage isolation mode for sandbox data. Set at subos creation time
 // via `--storage <mode>`, persisted in subos/.xlings.json["storage"].
@@ -90,14 +77,7 @@ export inline StorageMode storage_from_string_(const std::string& s) {
 }
 
 // Read storage mode from subos config file.
-export StorageMode read_storage_mode_(const fs::path& subos_dir) {
-    auto cfg = subos_dir / ".xlings.json";
-    if (!fs::exists(cfg)) return StorageMode::Shared;
-    auto json = read_config_json_(cfg);
-    if (json.contains("storage") && json["storage"].is_string())
-        return storage_from_string_(json["storage"].get<std::string>());
-    return StorageMode::Shared;
-}
+export StorageMode read_storage_mode_(const fs::path& subos_dir);
 
 
 // /etc/* template builders + sandbox dir layout init. uid_t / gid_t
@@ -108,39 +88,6 @@ export StorageMode read_storage_mode_(const fs::path& subos_dir) {
 // platform-portable substitutes.
 #if defined(__linux__) || defined(__APPLE__)
 
-// We write per-user passwd/group at sandbox init time so getpwuid
-// (real_uid) inside the sandbox returns the real user's home
-// (= /home/<user>) and shell — most CLI tools depend on this. Root
-// is also included so anything that does getpwuid(0) (scripts that
-// assume "root must exist") doesn't bail.
-std::string make_etc_passwd_(const std::string& user, uid_t uid, gid_t gid) {
-    auto home = "/home/" + user;
-    // When running as root (uid 0), emit a SINGLE uid-0 entry whose home is
-    // the sandbox home (/home/<user>), so getpwuid(0)->pw_dir agrees with
-    // $HOME and the bind-mounted home. The historical extra
-    // "root:x:0:0:root:/root" line would otherwise create a second,
-    // conflicting uid-0 record that getpwuid(0) resolves to /root — an
-    // empty, unbound path — breaking `cd ~`, ~/.config, and profile sourcing
-    // for the root user inside the sandbox.
-    if (uid == 0) {
-        return std::format("{}:x:0:0:{}:{}:/bin/sh\n", user, user, home);
-    }
-    return std::format(
-        "root:x:0:0:root:/root:/bin/sh\n"
-        "{}:x:{}:{}:{}:{}:/bin/sh\n",
-        user, uid, gid, user, home);
-}
-std::string make_etc_group_(const std::string& user, gid_t gid) {
-    // Mirror passwd: a single gid-0 entry when running as root avoids a
-    // duplicate group-0 record (root + <user> both gid 0).
-    if (gid == 0) {
-        return std::format("{}:x:0:\n", user);
-    }
-    return std::format(
-        "root:x:0:\n"
-        "{}:x:{}:\n",
-        user, gid);
-}
 inline constexpr std::string_view kEtcHosts =
     "127.0.0.1 localhost\n::1 localhost\n";
 inline constexpr std::string_view kEtcNsswitch =
@@ -210,238 +157,18 @@ inline void write_sandbox_rc_(const fs::path& home_dir) {
     try_write(fish_dir / "config.fish", kSandboxFishConfig);
 }
 
-// Initialize the sandbox-specific dirs / templates inside an existing
-// subos. Idempotent: only writes files that don't yet exist, so a
-// returning sandbox session won't clobber user customizations and a
-// repeated `subos use --sandbox` is cheap.
-void init_sandbox_dirs_(const fs::path& subos_dir,
-                        const std::string& user,
-                        uid_t uid, gid_t gid)
-{
-    auto user_home = subos_dir / "home" / user;
-    fs::create_directories(user_home);
-    fs::create_directories(subos_dir / "tmp");
-    auto etc = subos_dir / "etc";
-    fs::create_directories(etc);
-
-    // Empty `subos/` marker dir at sandbox root. xlings's project
-    // discovery walks cwd → / looking for `.xlings.json`; it stops at
-    // any dir that ALSO contains a `subos/` sibling (xlings-home
-    // boundary check, see config.cppm load_project_config_). Without
-    // this marker, the sandbox's own `<subos>/.xlings.json` (the
-    // workspace file, which appears at `/.xlings.json` inside the
-    // chroot) gets misinterpreted as an anonymous-project root, which
-    // OVERRIDES the per-shell XLINGS_ACTIVE_SUBOS=<name> and routes
-    // all install / shim / workspace paths into a phantom
-    // `<subos>/.xlings/subos/_/` tree disjoint from where PATH points.
-    // Empty `<subos>/subos/` ≈ "this is an xlings-managed dir, not a
-    // user project root" — boundary check terminates the walk.
-    fs::create_directories(subos_dir / "subos");
-
-    // Pseudo-root for proot chroot (`-r`). Using an empty directory
-    // that is NOT the subos_dir itself avoids a proot detranslate_path
-    // bug: when the subos rootfs is under `~/.xlings/` and proot
-    // also has `--bind=~/.xlings:~/.xlings`, the host path
-    // `~/.xlings/subos/<name>/usr` is ambiguously interpretable as
-    // both "rootfs + /usr" (→ matches --bind=/usr:/usr) and "~/.xlings
-    // bind + subos/<name>/usr" (→ the real subos dir). proot chooses
-    // the former, causing `cd subos/<name>/usr && ls` to show host
-    // /usr instead of the subos's own usr/.
-    //
-    // Fix: use `<subos>/sandbox-root/` (always empty, mode 0555) as
-    // the proot chroot root. Since `sandbox-root/usr` never exists,
-    // the detranslate prefix-strip cannot produce `/usr`, and the
-    // ambiguity disappears. All real content is bind-mounted in.
-    {
-        auto sandbox_root = subos_dir / "sandbox-root";
-        fs::create_directories(sandbox_root);
-        std::error_code perm_ec;
-        fs::permissions(sandbox_root,
-                        fs::perms::owner_read | fs::perms::owner_exec |
-                        fs::perms::group_read | fs::perms::group_exec |
-                        fs::perms::others_read | fs::perms::others_exec,
-                        fs::perm_options::replace, perm_ec);
-    }
-
-    auto try_write = [&](const fs::path& path, std::string_view body) {
-        if (fs::exists(path)) return;
-        platform::write_string_to_file(path.string(), std::string(body));
-    };
-    try_write(etc / "passwd", make_etc_passwd_(user, uid, gid));
-    try_write(etc / "group", make_etc_group_(user, gid));
-    try_write(etc / "hosts", kEtcHosts);
-    try_write(etc / "nsswitch.conf", kEtcNsswitch);
-
-    // Seed shell rc files so the xlings profile gets sourced (PATH +
-    // prompt pill). Sandbox-private; user can edit freely.
-    write_sandbox_rc_(user_home);
-    auto fish_config_dir = user_home / ".config" / "fish";
-    fs::create_directories(fish_config_dir);
-    try_write(fish_config_dir / "config.fish", kSandboxFishConfig);
-}
-
 #endif // __linux__ / __APPLE__
 
 // ── Image storage helpers (V6) ────────────────────────────────────
 
 // Create a sparse ext4 image file. Idempotent.
-export int init_image_(const fs::path& img, const std::string& size) {
-    if (fs::exists(img)) return 0;
-    auto truncate_cmd = "truncate -s " + size + " " + img.string();
-    if (std::system(truncate_cmd.c_str()) != 0) return 1;
-    auto mkfs_cmd = "mkfs.ext4 -F -m 0 -q " + img.string() + " 2>/dev/null";
-    return std::system(mkfs_cmd.c_str());
-}
+export int init_image_(const fs::path& img, const std::string& size);
 
 // Check if a path is already a mountpoint.
-export bool is_mounted_(const fs::path& path) {
-    auto cmd = "mountpoint -q " + path.string() + " 2>/dev/null";
-    return std::system(cmd.c_str()) == 0;
-}
-
-// Mount an image file at mountpoint. Supports multi-terminal reuse.
-// After mount, chown the mountpoint root to the calling user so
-// subsequent directory/file creation doesn't need sudo.
-int mount_image_(const fs::path& img, const fs::path& mountpoint,
-                 const std::string& user = {}) {
-    fs::create_directories(mountpoint);
-    if (is_mounted_(mountpoint)) return 0;  // already mounted
-
-    // mount (privileged). priv_prefix() is "" when already root — sudo is
-    // redundant and frequently absent in minimal root containers, where the
-    // old hardcoded "sudo mount" died with "sudo: command not found".
-    auto cmd = platform::priv_prefix() + "mount -o loop " + img.string() + " "
-               + mountpoint.string();
-    auto rc = std::system(cmd.c_str());
-    if (rc != 0) return rc;
-
-    // ext4 root dir is owned by root after mkfs; chown to real user
-    // so sandbox init can create dirs without sudo.
-    if (!user.empty()) {
-        auto chown_cmd = platform::priv_prefix() + "chown " + user + ":" + user
-                         + " " + mountpoint.string();
-        std::system(chown_cmd.c_str());
-    }
-    return 0;
-}
+export bool is_mounted_(const fs::path& path);
 
 // Unmount an image file.
-export int unmount_image_(const fs::path& mountpoint) {
-    if (!is_mounted_(mountpoint)) return 0;
-    auto cmd = platform::priv_prefix() + "umount " + mountpoint.string()
-               + " 2>/dev/null";
-    return std::system(cmd.c_str());
-}
-
-
-// ─────────────────────────────────────────────────────────────────────
-// Sandbox subos entry — proot-based fs-isolated session.
-//
-// Triggered when `subos use <name>` reads a subos config that has the
-// `sandbox-shell` field. Only available on Linux (proot uses ptrace +
-// Linux syscall conventions). On non-Linux platforms the sandbox config
-// is rejected at create time, so this code path is unreachable there;
-// guard with #if defined(__linux__) and stub elsewhere.
-//
-// See docs/plans/2026-05-09-subos-sandbox-design.md for full rationale.
-// ─────────────────────────────────────────────────────────────────────
-
-
-// Probe order for the proot binary:
-//   1. <home>/data/xpkgs/xim-x-proot/<ver>/bin/proot   the PAYLOAD
-//   2. <home>/runtimedir/proot                         auto-fetch cache
-//   3. /usr/bin/proot, /usr/local/bin/proot            the HOST (reported)
-//
-// PATH is deliberately absent -- see (3) below. The same rule, in the same
-// shape, as libxpkg's elfpatch tool lookup: payload, then a named fallback
-// that says so. Both implement R6 (internal consumers bind the payload, not
-// the view), .agents/docs/2026-08-06-subos-architecture-proposal.md §1.5.
-//
-// Returns the path to a usable proot, or unexpected with a hint string.
-std::expected<fs::path, std::string>
-locate_proot_(const fs::path& home_dir) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-
-    // (1) xpkg-managed (look at versions DB)
-    //
-    // Iterating with explicit directory_iterator + sentinel comparison
-    // (not range-for over a wrapper) sidesteps a libstdc++ copy-ctor
-    // visibility issue we hit on gcc 15.1.0 musl-cross when this header
-    // is exposed via BMI: the range-for path required `directory_iterator
-    // (directory_iterator const&)` to be visible at the inline expansion
-    // site inside another module's TU, and the cross-toolchain link
-    // surfaced it as "undefined reference to __cxx11::directory_iterator
-    // ctor" in capabilities.cppm. Using sentinel `{}` comparison avoids
-    // the copy entirely.
-    auto xpkgs_dir = home_dir / "data" / "xpkgs";
-    auto xpkg_proot_root = xpkgs_dir / "xim-x-proot";
-    if (fs::is_directory(xpkg_proot_root, ec)) {
-        // Sentinel form (`it != default_sentinel`) instead of comparing
-        // two directory_iterators directly. Clang/libc++ only provides
-        // the sentinel comparison in C++20+; comparing two
-        // directory_iterators yields "invalid operands to binary
-        // expression" on macOS clang. Sentinel form works on both
-        // libstdc++ (Linux gcc) and libc++ (macOS clang).
-        std::error_code it_ec;
-        for (auto it = fs::directory_iterator(xpkg_proot_root, it_ec);
-             !it_ec && it != std::default_sentinel;
-             it.increment(it_ec))
-        {
-            auto candidate = it->path() / "bin" / "proot";
-            if (fs::is_regular_file(candidate, ec)) return candidate;
-        }
-    }
-
-    // (2) auto-fetch cache
-    auto runtime_proot = home_dir / "runtimedir" / "proot";
-    if (fs::is_regular_file(runtime_proot, ec)) return runtime_proot;
-
-    // (3) The host's proot, at the two paths a distribution puts it.
-    //
-    // There is no PATH step. An earlier version walked PATH and rejected the
-    // candidates that turned out to be xlings shims; that fixed the symptom
-    // and left the cause. By R6 the whole step is wrong for internal use: PATH
-    // is a *view*, it is what the user selected, and letting it decide which
-    // proot runs makes the sandbox's own identity depend on the environment
-    // the sandbox was launched from. A shim on PATH is the worst case -- it
-    // re-enters xlings, anchors to the home that owns it, and re-exports
-    // XLINGS_HOME to match, so an isolated home with no backend installed
-    // would silently run against the developer's real home, and every
-    // measurement taken inside would be of the wrong home while looking
-    // exactly like a measurement of the right one.
-    //
-    // These two paths are different in kind: they are the host's, they are
-    // named here rather than discovered, and using one is reported. Per §2.8
-    // of the architecture proposal, depending on the host is allowed when it
-    // is DECLARED -- what is not allowed is depending on it by accident.
-    for (const auto* p : {"/usr/bin/proot", "/usr/local/bin/proot"}) {
-        auto candidate = fs::path(p);
-        if (!fs::is_regular_file(candidate, ec)) continue;
-        // Defensive: a home that installed itself under /usr/local would put
-        // a shim on one of these paths, and it is still a shim.
-        if (auto owner = xvm::resolve_owner_home(candidate)) {
-            log::debug("skipping {}: an xlings shim owned by {}, not the "
-                       "host's proot", candidate.string(), owner->string());
-            continue;
-        }
-        log::warn("using the host's proot ({}) -- no proot payload in {}. "
-                  "Run `xlings install proot` to make this deterministic.",
-                  candidate.string(), home_dir.string());
-        return candidate;
-    }
-
-    // Naming the home rather than "~/.xlings": with an isolated XLINGS_HOME
-    // the tilde form points somewhere the caller is not using, and a
-    // reader who follows it lands on the very home this search excluded.
-    return std::unexpected(std::format(
-        "proot not found in {}. Run `xlings install proot`, or place a proot "
-        "binary at {}/runtimedir/proot. The host's proot at /usr/bin/proot is "
-        "used when present (`sudo apt install proot`), but PATH is not "
-        "searched: a `proot` on PATH may be an xlings shim, and running it "
-        "would move the whole session to whichever home owns it.",
-        home_dir.string(), home_dir.string()));
-}
+export int unmount_image_(const fs::path& mountpoint);
 
 // ── Unified bind list (shared by proot + bwrap) ──────────────────────
 //
@@ -463,260 +190,6 @@ struct SandboxBind {
     bool readonly;   // true = host RO; false = sandbox RW override
 };
 
-std::vector<SandboxBind>
-sandbox_binds_(const fs::path& subos_dir,
-               const fs::path& host_xlings_home,
-               const std::string& user,
-               StorageMode storage = StorageMode::Shared,
-               const fs::path& mountpoint = {})
-{
-    auto etc = subos_dir / "etc";
-    auto user_home = "/home/" + user;
-
-    std::error_code ec;
-
-    auto try_ro = [&](std::vector<SandboxBind>& v,
-                      const char* src, const char* dst) {
-        if (fs::exists(src, ec))
-            v.push_back({src, dst, true});
-    };
-
-    std::vector<SandboxBind> binds;
-
-    // ── Host RO: POSIX userland (tools + libs + loader) ──
-    try_ro(binds, "/usr", "/usr");
-    try_ro(binds, "/bin", "/bin");
-    try_ro(binds, "/usr/lib", "/lib");
-    try_ro(binds, "/usr/lib64", "/lib64");
-
-    // ── Host RO: /etc (by-need) ──
-    try_ro(binds, "/etc/resolv.conf", "/etc/resolv.conf");
-    try_ro(binds, "/etc/ld.so.cache", "/etc/ld.so.cache");
-    try_ro(binds, "/etc/ssl", "/etc/ssl");
-    try_ro(binds, "/etc/pki", "/etc/pki");
-    try_ro(binds, "/etc/alternatives", "/etc/alternatives");
-    try_ro(binds, "/etc/localtime", "/etc/localtime");
-
-    // ── Sandbox RW: private overrides (storage-dependent) ──
-    if (storage == StorageMode::Shared) {
-        binds.push_back({(subos_dir / "home").string(), "/home", false});
-        binds.push_back({(subos_dir / "tmp").string(), "/tmp", false});
-    } else if (storage == StorageMode::Image) {
-        // home from mounted image; tmp uses bwrap --tmpfs (added in argv)
-        binds.push_back({mountpoint.string(), "/home", false});
-    }
-    // tmpfs: home and tmp handled by bwrap --tmpfs (no bind needed)
-
-    // xlings shared — always bound regardless of storage mode, and always
-    // at its OWN absolute path.
-    //
-    // xvm alias targets, RPATH and INTERP are absolute host paths baked at
-    // install time, and nothing rewrites them on the way in; the home has
-    // to answer to the same spelling in here that it does outside. Mapping
-    // it to <user_home>/.xlings instead strands all of them, and mapping it
-    // to both makes one directory reachable by two real paths — which a
-    // bind mount does not collapse, so canonicalising does not save you and
-    // a shim ends up reporting a conflict with itself. For the default home
-    // this bind IS <user_home>/.xlings; that coincidence is the only reason
-    // the remapped form ever appeared to work.
-    binds.push_back({host_xlings_home.string(), host_xlings_home.string(), false});
-
-    // ── Sandbox: NSS templates ──
-    binds.push_back({(etc / "passwd").string(), "/etc/passwd", false});
-    binds.push_back({(etc / "group").string(), "/etc/group", false});
-    binds.push_back({(etc / "hosts").string(), "/etc/hosts", false});
-    binds.push_back({(etc / "nsswitch.conf").string(), "/etc/nsswitch.conf", false});
-
-    return binds;
-}
-
-// Build proot argv from unified bind list. When `cmd` is non-empty, ends
-// in `<shell> -c <cmd>` for non-interactive single-command exec (M3);
-// otherwise just `<shell>` for the standard interactive entry.
-std::vector<std::string>
-build_proot_argv_(const fs::path& proot_bin,
-                  const fs::path& subos_dir,
-                  const fs::path& host_xlings_home,
-                  const std::string& user,
-                  const std::string& shell_path,
-                  const std::string& cmd = "")
-{
-    auto user_home = "/home/" + user;
-    // Use sandbox-root/ as the chroot root instead of subos_dir itself.
-    // This avoids the proot detranslate_path bug where host paths under
-    // subos_dir (e.g. subos/<name>/usr) get mis-translated to /usr when
-    // the rootfs prefix is stripped. See init_sandbox_dirs_ for details.
-    auto proot_root = subos_dir / "sandbox-root";
-    std::vector<std::string> argv = {
-        proot_bin.string(),
-        "-r", proot_root.string(),
-        "--bind=/proc:/proc",
-        "--bind=/sys:/sys",
-        "--bind=/dev:/dev",
-    };
-
-    for (auto& b : sandbox_binds_(subos_dir, host_xlings_home, user)) {
-        argv.push_back(std::format("--bind={}:{}", b.src, b.dst));
-    }
-
-    argv.push_back(std::format("--cwd={}", user_home));
-    argv.push_back(shell_path);
-    if (!cmd.empty()) {
-        argv.push_back("-c");
-        argv.push_back(cmd);
-    }
-    return argv;
-}
-
-// ── bwrap backend (V5) ────────────────────────────────────────────────
-
-// Locate bwrap binary — only searches xim:bwrap pool.
-// System-installed bwrap (/usr/bin/bwrap) is intentionally skipped:
-// distro packages lack setuid, and AppArmor/kernel restrictions on
-// unprivileged user namespaces make system binaries unreliable on
-// Ubuntu 24+, Fedora, etc. xim:bwrap is built with
-// `-Dsupport_setuid=true` (xlings-res/bwrap mirror) and its install
-// hook sets the binary setuid root (chmod 4755) — that combination is
-// what makes the xim-managed binary work across distros where unpriv
-// userns is restricted.
-std::expected<fs::path, std::string>
-locate_bwrap_(const fs::path& home_dir) {
-    std::error_code ec;
-
-    auto xpkg_root = home_dir / "data" / "xpkgs" / "xim-x-bwrap";
-    if (fs::is_directory(xpkg_root, ec)) {
-        std::error_code it_ec;
-        for (auto it = fs::directory_iterator(xpkg_root, it_ec);
-             !it_ec && it != std::default_sentinel;
-             it.increment(it_ec))
-        {
-            auto candidate = it->path() / "bin" / "bwrap";
-            if (fs::is_regular_file(candidate, ec)) return candidate;
-        }
-    }
-
-    return std::unexpected(
-        "bwrap not installed, run: xlings install bwrap");
-}
-
-// Probe whether a bwrap binary can actually create a sandbox.
-// Returns {ok, output}. `output` captures stdout+stderr (the platform
-// helper appends `2>&1` internally) so callers can classify the
-// failure cause — see classify_bwrap_probe_error_ for the known modes.
-std::pair<bool, std::string>
-probe_bwrap_(const fs::path& bwrap_bin) {
-    auto cmd = platform::shell_quote(bwrap_bin.string())
-             + " --ro-bind / / -- /bin/true";
-    auto [status, output] = platform::run_command_capture(cmd);
-    return { status == 0, std::move(output) };
-}
-
-// Translate a failed bwrap probe's captured output into an actionable
-// hint. Three known modes; anything else falls through to "show the
-// raw stderr" so users always see the truth instead of a stale
-// "xlings install bwrap" suggestion that won't help.
-std::string classify_bwrap_probe_error_(const std::string& output,
-                                         const fs::path& bin) {
-    if (output.find("setuid use of bubblewrap is not supported")
-        != std::string::npos)
-    {
-        return "xim:bwrap binary was built without setuid support; "
-               "rebuild xlings-res/bwrap mirror with "
-               "`-Dsupport_setuid=true` and bump the version\n"
-               "  binary: " + bin.string();
-    }
-    if (output.find("setting up uid map: Permission denied")
-        != std::string::npos
-        || output.find("write to uid_map failed")
-        != std::string::npos)
-    {
-        return "kernel restricts unprivileged user namespaces "
-               "(LSM/AppArmor)\n"
-               "  check: cat /proc/sys/kernel/"
-               "apparmor_restrict_unprivileged_userns\n"
-               "  workaround: sudo sysctl -w "
-               "kernel.apparmor_restrict_unprivileged_userns=0";
-    }
-    if (output.find("clone() failed: Operation not permitted")
-        != std::string::npos
-        || output.find("user namespaces are not enabled")
-        != std::string::npos)
-    {
-        return "kernel disables unprivileged_userns_clone\n"
-               "  check: cat /proc/sys/kernel/"
-               "unprivileged_userns_clone";
-    }
-    auto trimmed = output;
-    while (!trimmed.empty() &&
-           (trimmed.back() == '\n' || trimmed.back() == '\r'))
-        trimmed.pop_back();
-    return "bwrap probe failed; raw output:\n  " + trimmed;
-}
-
-// Build bwrap argv from unified bind list. Uses targeted --ro-bind
-// instead of `--ro-bind / /` to match proot's security profile
-// (same host paths exposed, same sandbox-private paths).
-// When `cmd` is non-empty, ends with `<shell> -c <cmd>` for non-
-// interactive single-command exec (M3); otherwise interactive shell.
-std::vector<std::string>
-build_bwrap_argv_(const fs::path& bwrap_bin,
-                  const fs::path& subos_dir,
-                  const fs::path& host_xlings_home,
-                  const std::string& user,
-                  const std::string& shell_path,
-                  bool interactive_shell,
-                  StorageMode storage = StorageMode::Shared,
-                  const fs::path& mountpoint = {},
-                  bool gpu = false,
-                  const std::string& cmd = "")
-{
-    auto user_home = "/home/" + user;
-    std::vector<std::string> argv = {
-        bwrap_bin.string(),
-        "--dev", "/dev",
-        "--proc", "/proc",
-    };
-
-    for (auto& b : sandbox_binds_(subos_dir, host_xlings_home, user,
-                                   storage, mountpoint)) {
-        if (b.readonly) {
-            argv.insert(argv.end(), {"--ro-bind", b.src, b.dst});
-        } else {
-            argv.insert(argv.end(), {"--bind", b.src, b.dst});
-        }
-    }
-
-    // GPU passthrough: must come after `--dev /dev` (which creates the
-    // empty tmpfs we'll mount nodes onto). Each --dev-bind is host-path
-    // → sandbox-path; missing nodes are silently skipped by gpu.cppm.
-    if (gpu) {
-        auto extra = xlings::subos::gpu::passthrough_args();
-        argv.insert(argv.end(), extra.begin(), extra.end());
-    }
-
-    // tmpfs mode: home and tmp are pure memory (exit = gone)
-    if (storage == StorageMode::Tmpfs) {
-        argv.insert(argv.end(), {"--tmpfs", user_home});
-        argv.insert(argv.end(), {"--tmpfs", "/tmp"});
-    }
-    // image mode: tmp uses tmpfs (home is bind-mounted from .mountpoint)
-    if (storage == StorageMode::Image) {
-        argv.insert(argv.end(), {"--tmpfs", "/tmp"});
-    }
-
-    argv.insert(argv.end(), {"--chdir", user_home, "--", shell_path});
-    if (!cmd.empty()) {
-        // Non-interactive single-command exec: shell -c <cmd>. The -i
-        // flag would print prompts/job-control warnings to captured
-        // stdout, so we omit it even if interactive_shell=true.
-        argv.push_back("-c");
-        argv.push_back(cmd);
-    } else if (interactive_shell) {
-        argv.push_back("-i");
-    }
-    return argv;
-}
-
 // ── Backend detection + auto-install ─────────────────────────────────
 
 enum class SandboxBackend { Bwrap, Proot };
@@ -726,102 +199,7 @@ struct BackendInfo {
     fs::path binary;
 };
 
-// Show bwrap hint — only on first sandbox use of a subos (detected by
-// whether <subos>/home/ exists; init_sandbox_dirs_ creates it, so if
-// it's missing, this is the first --sandbox entry for this subos).
-void maybe_show_bwrap_hint_(const fs::path& subos_dir) {
-    std::error_code ec;
-    if (fs::is_directory(subos_dir / "home", ec)) return;
-
-    log::info("bwrap not installed or namespace probe failed");
-    log::info("  to enable bwrap (recommended): xlings install bwrap");
-    log::info("  using proot fallback for now");
-}
-
-std::optional<BackendInfo>
-detect_backend_(const fs::path& home_dir,
-                const fs::path& subos_dir = {}) {
-    // 1. bwrap (xim pool) — preferred for native compat
-    if (auto bin = locate_bwrap_(home_dir)) {
-        if (probe_bwrap_(*bin).first)
-            return BackendInfo{ SandboxBackend::Bwrap, *bin };
-    }
-
-    // bwrap found but probe failed → show hint (first use only)
-    if (locate_bwrap_(home_dir) && !subos_dir.empty()) {
-        maybe_show_bwrap_hint_(subos_dir);
-    }
-
-    // 2. proot — zero-privilege fallback
-    if (auto bin = locate_proot_(home_dir))
-        return BackendInfo{ SandboxBackend::Proot, *bin };
-
-    return std::nullopt;
-}
-
-// Should we even try to fetch a sandbox backend for this host? Answered from
-// the on-disk index, with no network access.
-//
-// The evidence rule here is deliberately stricter than the one `xlings
-// install` uses, and the difference is who asked. A package-level `archs`
-// union is weak evidence -- it went unenforced for all of spec V1 and is
-// routinely under-declared -- so it must never veto an install the USER named:
-// being wrong there means refusing a package that works, and the user has no
-// way around it.
-//
-// This install is one nobody asked for. `--sandbox` triggers it implicitly,
-// and being wrong costs only a skipped auto-install that
-// `xlings install bwrap` still overrides. Being wrong the other way costs
-// every `--sandbox` invocation on the arch a download that 404s, ~45s of
-// waiting, and a diagnostic that blames the installer rather than naming the
-// target. So a weak signal is enough to decline here.
-//
-// What it is NOT is a compile-time `#if defined(__aarch64__)`, which is what
-// this replaced: that freezes a claim about the package index into the binary,
-// so the day an aarch64 backend is published every client in the field still
-// refuses. This is re-read from the index on every call.
-std::optional<std::string> backend_target_unavailable_() {
-    auto& catalog = xim::get_catalog(xim::CatalogAccess::LocalOnly);
-    if (!catalog.is_loaded()) return std::nullopt;
-
-    const auto hostArch = xim::host_architecture();
-    std::string target;
-    for (const auto* name : {"bwrap", "proot"}) {
-        auto match = catalog.resolve_target(name, "linux");
-        if (!match) return std::nullopt;          // cannot say -> let it try
-        auto pkg = catalog.load_package(*match);
-        if (!pkg) return std::nullopt;
-        const auto* entry = xim::find_entry(*pkg, "linux", match->version);
-        const auto compatibility = xim::check_target_compatibility(
-            *pkg, entry, "linux", hostArch);
-        target = compatibility.target;
-        // Supported AND not merely "we could not tell": an advisory means the
-        // recipe does not claim this arch, which is as much as an
-        // auto-install needs to hear.
-        if (compatibility.supported && compatibility.advisory.empty()) {
-            return std::nullopt;
-        }
-    }
-    return std::format(
-        "E_UNSUPPORTED_TARGET: no sandbox backend has a {} artifact", target);
-}
-
-int auto_install_backend_(const fs::path& home_dir, EventStream& stream) {
-    // Try bwrap first (build from source, config hook sets setuid)
-    log::info("installing sandbox backend...");
-    {
-        std::vector<std::string> t = {"xim:bwrap"};
-        xim::cmd_install(t, /*yes=*/true, /*noDeps=*/false, stream);
-        auto bin = locate_bwrap_(home_dir);
-        if (bin && probe_bwrap_(*bin).first) return 0;
-    }
-
-    // bwrap installed but namespace restricted → proot fallback
-    // (hint already shown by detect_backend_ on first use)
-
-    std::vector<std::string> t = {"xim:proot"};
-    return xim::cmd_install(t, /*yes=*/true, /*noDeps=*/false, stream);
-}
+int auto_install_backend_(const fs::path& home_dir, EventStream& stream);
 
 
 // V5 sandbox entry. Reached via `xlings subos use <name> --sandbox [backend]`.
@@ -833,389 +211,6 @@ int auto_install_backend_(const fs::path& home_dir, EventStream& stream) {
 export int enter(const std::string& name, EventStream& stream,
                       const std::string& preferred_backend = "",
                       bool gpu = false,
-                      const std::string& cmd = "") {
-
-    // Refuse nested sandbox entry.
-    if (utils::get_env_or_default("XLINGS_SUBOS_MODE") == "sandbox") {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = "cannot enter sandbox from inside another sandbox",
-            .recoverable = true,
-            .hint = "type 'exit' first to leave the current one",
-        });
-        return 1;
-    }
-
-    auto& p = Config::paths();
-    auto subos_dir = p.homeDir / "subos" / name;
-
-    // ── Storage mode (V6) ──
-    auto storage = read_storage_mode_(subos_dir);
-
-    // ── Resolve user ──
-#if defined(_WIN32)
-    auto user = utils::get_env_or_default("USERNAME");
-    if (user.empty()) user = "user";
-#else
-    auto user = utils::get_env_or_default("USER");
-    if (user.empty()) user = "user";
-#endif
-
-    auto sandbox_home = (subos_dir / "home" / user).string();
-    auto sandbox_tmp = (subos_dir / "tmp").string();
-
-    // Image mountpoint (populated in the Linux block below if image mode)
-    fs::path image_mountpoint;
-    if (storage == StorageMode::Image)
-        image_mountpoint = subos_dir / ".mountpoint";
-
-    // ── Lazy init sandbox dirs (shared mode only) ──
-    if (storage == StorageMode::Shared) {
-        fs::create_directories(subos_dir / "home" / user);
-        fs::create_directories(subos_dir / "tmp");
-    }
-
-#if defined(__linux__) || defined(__APPLE__)
-    // Seed shell rc files so profile is sourced (prompt pill + PATH).
-    // For image mode, rc files go into the mounted image (deferred until
-    // after mount in the Linux block below). For shared/tmpfs, seed now.
-    if (storage == StorageMode::Shared) {
-        auto user_home_dir = subos_dir / "home" / user;
-        fs::create_directories(user_home_dir);
-        write_sandbox_rc_(user_home_dir);
-    }
-#endif
-
-    // ── Common env (all platforms) ──
-    platform::set_env_variable("XLINGS_ACTIVE_SUBOS", name);
-    platform::set_env_variable("XLINGS_SUBOS_MODE", "sandbox");
-    // E2a, same declaration as the non-sandbox path. Declared here too and
-    // not only there: a contract that holds in one of the two ways users
-    // enter a subos is a contract consumers cannot rely on, and the sandbox
-    // is the mode the graphics acceptance tooling runs in.
-    platform::set_env_variable("XLINGS_SUBOS_LIB",
-                               (subos_dir / "lib").string());
-
-    nlohmann::json payload;
-    payload["name"] = name;
-    payload["mode"] = "sandbox";
-
-    std::cout.flush();
-    std::cerr.flush();
-
-#if defined(__linux__)
-    // ═══════════════════════════════════════════════════════════════
-    // Linux L3: FS view isolation via bwrap/proot
-    // ═══════════════════════════════════════════════════════════════
-
-    // image/tmpfs storage requires bwrap (mount namespace needed)
-    if (storage != StorageMode::Shared && !preferred_backend.empty()
-        && preferred_backend == "proot") {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = "image/tmpfs storage requires bwrap sandbox backend",
-            .recoverable = false,
-            .hint = "run: xlings install bwrap",
-        });
-        return 1;
-    }
-
-    // ── Image mode: mount image before sandbox entry ──
-    if (storage == StorageMode::Image) {
-        auto img = subos_dir / "home.img";
-        if (!fs::exists(img)) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::NotFound,
-                .message = "home.img not found — was this subos created with --storage image?",
-                .recoverable = false,
-            });
-            return 1;
-        }
-        auto rc = mount_image_(img, image_mountpoint, user);
-        if (rc != 0) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::Internal,
-                .message = "failed to mount home.img",
-                .recoverable = false,
-                .hint = "ensure you have sudo permission for mount",
-            });
-            return 1;
-        }
-    }
-
-    // /etc templates for Linux sandbox (NSS)
-    {
-        auto uid = ::getuid();
-        auto gid = ::getgid();
-        init_sandbox_dirs_(subos_dir, user, uid, gid);
-        // For image mode, init home and seed shell rc files inside the mount
-        if (storage == StorageMode::Image) {
-            auto mp_home = image_mountpoint / user;
-            fs::create_directories(mp_home);
-            write_sandbox_rc_(mp_home);
-        }
-    }
-
-    // Backend selection (the using-declarations that stood here named
-    // sandbox_detail_:: and are redundant now that this IS that namespace)
-    std::optional<BackendInfo> backend;
-
-    if (preferred_backend == "bwrap") {
-        auto bin = locate_bwrap_(p.homeDir);
-        if (!bin) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::NotFound,
-                .message = "bwrap not installed",
-                .recoverable = false,
-                .hint = "run: xlings install bwrap",
-            });
-            return 1;
-        }
-        if (auto probe = probe_bwrap_(*bin); !probe.first) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::NotFound,
-                .message = "bwrap probe failed",
-                .recoverable = false,
-                .hint = classify_bwrap_probe_error_(
-                            probe.second, *bin),
-            });
-            return 1;
-        }
-        backend = BackendInfo{ SandboxBackend::Bwrap, *bin };
-    } else if (preferred_backend == "proot") {
-        auto bin = locate_proot_(p.homeDir);
-        if (!bin) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::NotFound,
-                .message = std::move(bin).error(),
-                .recoverable = false,
-                .hint = "run: xlings install proot",
-            });
-            return 1;
-        }
-        backend = BackendInfo{ SandboxBackend::Proot, *bin };
-    } else {
-        backend = detect_backend_(p.homeDir, subos_dir);
-        if (!backend) {
-            // Ask the index whether it ships a backend for this target before
-            // touching the network, so an unsupported host gets one causal
-            // error and zero download requests.
-            //
-            // This used to be `#if defined(__aarch64__)`, which is a claim
-            // about the package index frozen into the binary at compile time:
-            // the day xim-pkgindex publishes an aarch64 bwrap, every client
-            // already in the field would still refuse. Reading the on-disk
-            // index costs nothing and is right both before and after that day.
-            if (auto unavailable = backend_target_unavailable_(); unavailable) {
-                stream.emit(ErrorEvent{
-                    .code = ErrorCode::InvalidInput,
-                    .message = *unavailable,
-                    .recoverable = false,
-                    .hint = "use shell isolation, install your distribution's "
-                            "bubblewrap package, or `xlings install bwrap` to "
-                            "try anyway",
-                });
-                return 1;
-            }
-            auto rc = auto_install_backend_(p.homeDir, stream);
-            if (rc != 0) {
-                stream.emit(ErrorEvent{
-                    .code = ErrorCode::NotFound,
-                    .message = "failed to install sandbox backend",
-                    .recoverable = false,
-                    .hint = "manually: xlings install bwrap (or: xlings install proot)",
-                });
-                return 1;
-            }
-            backend = detect_backend_(p.homeDir, subos_dir);
-            if (!backend) {
-                stream.emit(ErrorEvent{
-                    .code = ErrorCode::NotFound,
-                    .message = "no sandbox backend available after install attempt",
-                    .recoverable = false,
-                });
-                return 1;
-            }
-        }
-    }
-
-    // image/tmpfs requires bwrap — reject proot after auto-detect
-    if (storage != StorageMode::Shared
-        && backend->type != SandboxBackend::Bwrap) {
-        // If bwrap is actually installed but probe failed (the common
-        // case that triggers the proot fallback), surface the real
-        // probe error rather than the misleading "xlings install bwrap"
-        // suggestion that won't help.
-        std::string hint = "run: xlings install bwrap";
-        if (auto bin = locate_bwrap_(p.homeDir)) {
-            if (auto probe = probe_bwrap_(*bin);
-                !probe.first)
-            {
-                hint = classify_bwrap_probe_error_(
-                            probe.second, *bin);
-            }
-        }
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = storage_to_string_(storage)
-                       + " storage requires bwrap (proot does not support mount namespace)",
-            .recoverable = false,
-            .hint = std::move(hint),
-        });
-        if (storage == StorageMode::Image)
-            unmount_image_(image_mountpoint);
-        return 1;
-    }
-
-    auto backend_name = (backend->type == SandboxBackend::Bwrap) ? "bwrap" : "proot";
-    log::debug("sandbox backend: {} storage: {}", backend_name,
-               storage_to_string_(storage));
-
-    auto user_home = "/home/" + user;
-    auto shell = utils::get_env_or_default("SHELL");
-    if (shell.empty()) shell = "/bin/sh";
-
-    payload["backend"] = backend_name;
-    payload["shell"] = shell;
-    payload["storage"] = storage_to_string_(storage);
-    stream.emit(DataEvent{"subos_entering", payload.dump()});
-
-    platform::set_env_variable("HOME", user_home);
-    // Pin the home explicitly rather than relying on inheritance: it is
-    // reachable at its own absolute path in here (see sandbox_binds_), and
-    // every path baked at install time — xvm targets, RPATH, INTERP —
-    // assumes exactly that spelling.
-    platform::set_env_variable("XLINGS_HOME", p.homeDir.string());
-    // Same spelling as XLINGS_HOME above. A shim decides which home owns it
-    // by comparing the path it was invoked through against XLINGS_HOME as
-    // strings; spelling the home two ways here makes it warn about a
-    // conflict with itself.
-    platform::set_env_variable("PATH", std::format(
-        "{0}/subos/{1}/bin:{0}/bin:/usr/local/bin:/usr/bin:/bin",
-        p.homeDir.string(), name));
-    // bwrap `sh -i` prints prompts/job-control warnings into piped CI
-    // commands; keep `-i` only for real terminal sessions.
-    const bool interactive_shell = ::isatty(STDIN_FILENO) == 1;
-
-    std::vector<std::string> argv;
-    if (backend->type == SandboxBackend::Bwrap) {
-        argv = build_bwrap_argv_(
-            backend->binary, subos_dir, p.homeDir, user, shell,
-            interactive_shell, storage, image_mountpoint, gpu, cmd);
-    } else {
-        // proot already exposes the full host /dev and /sys via
-        // `--bind=/dev:/dev --bind=/sys:/sys`, so GPU devices are
-        // visible for free. --gpu is a no-op here.
-        argv = build_proot_argv_(
-            backend->binary, subos_dir, p.homeDir, user, shell, cmd);
-        platform::set_env_variable("PROOT_NO_SECCOMP", "1");
-    }
-
-    std::vector<char*> c_argv;
-    c_argv.reserve(argv.size() + 1);
-    for (auto& s : argv) c_argv.push_back(const_cast<char*>(s.c_str()));
-    c_argv.push_back(nullptr);
-
-    // Image mode: fork+exec+wait so we can unmount after sandbox exits.
-    // Shared/tmpfs: execvp replaces the process (no cleanup needed).
-    if (storage == StorageMode::Image) {
-        auto pid = ::fork();
-        if (pid < 0) {
-            log::error("fork failed: {}", std::strerror(errno));
-            unmount_image_(image_mountpoint);
-            return 1;
-        }
-        if (pid == 0) {
-            // Child: enter sandbox
-            ::execvp(c_argv[0], c_argv.data());
-            log::error("failed to exec {}: {}", backend_name, std::strerror(errno));
-            ::_exit(127);
-        }
-        // Parent: wait then unmount
-        int status = 0;
-        ::waitpid(pid, &status, 0);
-        unmount_image_(image_mountpoint);
-        return WIFEXITED(status) ? WEXITSTATUS(status) : 1;
-    }
-
-    ::execvp(c_argv[0], c_argv.data());
-    log::error("failed to exec {} '{}': {}", backend_name,
-               backend->binary.string(), std::strerror(errno));
-    return 127;
-
-#elif defined(__APPLE__)
-    // ═══════════════════════════════════════════════════════════════
-    // macOS L2: HOME redirect (dotfile isolation)
-    // ═══════════════════════════════════════════════════════════════
-
-    // Ask the same resolver the launch is about to use. Deriving the reported
-    // shell here independently is how `subos_entering` came to announce
-    // `/bin/zsh` while the process that started was `/bin/sh`: two fallbacks
-    // for the same question, in two places, that only agree when SHELL is set.
-    // Say it where the person is, not only in the README. A user who reaches
-    // for `--sandbox` to run something they do not trust is exactly the user
-    // who did not read the isolation matrix, and on these two platforms this
-    // is a dotfile redirect -- no filesystem, network or process boundary.
-    //
-    // Only on interactive entry: a `--cmd` run is a script, and a warning it
-    // emits on every invocation is noise nobody reads. `--quiet` silences it.
-    if (cmd.empty()) {
-        log::warn("sandbox on {} redirects the home directory only -- "
-                  "it does not contain the filesystem, network or processes. "
-                  "Use an OS sandbox or a VM for untrusted code.",
-                  "macOS");
-    }
-
-    payload["backend"] = "home-redirect";
-    payload["shell"] = platform::resolve_shell();
-    stream.emit(DataEvent{"subos_entering", payload.dump()});
-
-    platform::set_env_variable("HOME", sandbox_home);
-    platform::set_env_variable("TMPDIR", sandbox_tmp);
-    platform::set_env_variable("XDG_CONFIG_HOME", sandbox_home + "/.config");
-    platform::set_env_variable("XDG_DATA_HOME", sandbox_home + "/.local/share");
-    platform::set_env_variable("XDG_CACHE_HOME", sandbox_home + "/.cache");
-    platform::set_env_variable("XDG_STATE_HOME", sandbox_home + "/.local/state");
-
-    return platform::run_shell(cmd, cmd.empty());
-
-#elif defined(_WIN32)
-    // ═══════════════════════════════════════════════════════════════
-    // Windows L2: USERPROFILE redirect (dotfile isolation)
-    // ═══════════════════════════════════════════════════════════════
-
-    // Pre-create AppData structure
-    fs::create_directories(fs::path(sandbox_home) / "AppData" / "Roaming");
-    fs::create_directories(fs::path(sandbox_home) / "AppData" / "Local");
-
-    // Say it where the person is, not only in the README. A user who reaches
-    // for `--sandbox` to run something they do not trust is exactly the user
-    // who did not read the isolation matrix, and on these two platforms this
-    // is a dotfile redirect -- no filesystem, network or process boundary.
-    //
-    // Only on interactive entry: a `--cmd` run is a script, and a warning it
-    // emits on every invocation is noise nobody reads. `--quiet` silences it.
-    if (cmd.empty()) {
-        log::warn("sandbox on {} redirects the home directory only -- "
-                  "it does not contain the filesystem, network or processes. "
-                  "Use an OS sandbox or a VM for untrusted code.",
-                  "Windows");
-    }
-
-    payload["backend"] = "home-redirect";
-    stream.emit(DataEvent{"subos_entering", payload.dump()});
-
-    platform::set_env_variable("USERPROFILE", sandbox_home);
-    platform::set_env_variable("APPDATA", sandbox_home + "\\AppData\\Roaming");
-    platform::set_env_variable("LOCALAPPDATA", sandbox_home + "\\AppData\\Local");
-    platform::set_env_variable("TEMP", sandbox_tmp);
-    platform::set_env_variable("TMP", sandbox_tmp);
-    platform::set_env_variable("XDG_CONFIG_HOME", sandbox_home + "\\.config");
-    platform::set_env_variable("XDG_DATA_HOME", sandbox_home + "\\.local\\share");
-    platform::set_env_variable("XDG_CACHE_HOME", sandbox_home + "\\.cache");
-
-    return platform::run_shell(cmd, cmd.empty());
-#endif
-}
+                      const std::string& cmd = "");
 
 }  // namespace xlings::subos::sandbox
diff --git a/src/core/utf8.cpp b/src/core/utf8.cpp
new file mode 100644
index 00000000..5d6db996
--- /dev/null
+++ b/src/core/utf8.cpp
@@ -0,0 +1,24 @@
+module xlings.core.utf8;
+
+import std;
+import xlings.libs.json;
+
+namespace xlings::utf8 {
+
+auto safe_truncate(std::string_view s, std::size_t max_bytes, std::string_view suffix) -> std::string {
+    if (s.size() <= max_bytes) return std::string(s);
+    if (max_bytes < suffix.size()) return std::string(suffix.substr(0, max_bytes));
+
+    std::size_t cut = max_bytes - suffix.size();
+    // Back up past any UTF-8 continuation bytes (10xxxxxx)
+    while (cut > 0 && (static_cast<unsigned char>(s[cut]) & 0xC0) == 0x80) {
+        --cut;
+    }
+    return std::string(s.substr(0, cut)) + std::string(suffix);
+}
+
+auto safe_dump(const nlohmann::json& j, int indent) -> std::string {
+    return j.dump(indent, ' ', false, nlohmann::json::error_handler_t::replace);
+}
+
+}
diff --git a/src/core/utf8.cppm b/src/core/utf8.cppm
index 71edbb5a..0900970e 100644
--- a/src/core/utf8.cppm
+++ b/src/core/utf8.cppm
@@ -7,21 +7,9 @@ namespace xlings::utf8 {
 
 // UTF-8 safe truncation: truncates at character boundary, never cuts multi-byte characters
 export auto safe_truncate(std::string_view s, std::size_t max_bytes,
-                          std::string_view suffix = "...") -> std::string {
-    if (s.size() <= max_bytes) return std::string(s);
-    if (max_bytes < suffix.size()) return std::string(suffix.substr(0, max_bytes));
-
-    std::size_t cut = max_bytes - suffix.size();
-    // Back up past any UTF-8 continuation bytes (10xxxxxx)
-    while (cut > 0 && (static_cast<unsigned char>(s[cut]) & 0xC0) == 0x80) {
-        --cut;
-    }
-    return std::string(s.substr(0, cut)) + std::string(suffix);
-}
+                          std::string_view suffix = "...") -> std::string;
 
 // Safe JSON dump using error_handler_t::replace for invalid UTF-8
-export auto safe_dump(const nlohmann::json& j, int indent = -1) -> std::string {
-    return j.dump(indent, ' ', false, nlohmann::json::error_handler_t::replace);
-}
+export auto safe_dump(const nlohmann::json& j, int indent = -1) -> std::string;
 
 } // namespace xlings::utf8
diff --git a/src/core/utils.cpp b/src/core/utils.cpp
new file mode 100644
index 00000000..4f802b99
--- /dev/null
+++ b/src/core/utils.cpp
@@ -0,0 +1,85 @@
+module;
+#include <cstdlib>
+module xlings.core.utils;
+
+import std;
+
+namespace xlings::utils {
+
+[[nodiscard]] std::string get_env_or_default(std::string_view name, std::string_view defaultValue) {
+    if (const char* value = std::getenv(name.data()); value != nullptr) {
+        return value;
+    }
+    return std::string{defaultValue};
+}
+
+[[nodiscard]] bool env_is_set(const std::string& name) {
+    return std::getenv(name.c_str()) != nullptr;
+}
+
+[[nodiscard]] std::string strip_ansi(const std::string& str) {
+    std::string cleaned;
+    cleaned.reserve(str.size());
+
+    for (std::size_t i = 0; i < str.size(); ++i) {
+        if (str[i] == '\x1b' && i + 1 < str.size() && str[i + 1] == '[') {
+            i += 2;
+            while (i < str.size() && str[i] != 'm') {
+                ++i;
+            }
+        } else {
+            cleaned.push_back(str[i]);
+        }
+    }
+
+    return cleaned;
+}
+
+[[nodiscard]] std::string trim_string(const std::string& str) {
+    auto cleaned = strip_ansi(str);
+
+    auto start = std::ranges::find_if_not(cleaned,
+        [](unsigned char ch) { return std::isspace(ch); });
+    auto endIt = std::ranges::find_if_not(cleaned | std::views::reverse,
+        [](unsigned char ch) { return std::isspace(ch); }).base();
+
+    return std::string(start, endIt);
+}
+
+[[nodiscard]] std::vector<std::string> split_string(const std::string& str, char delimiter) {
+    std::vector<std::string> result;
+    auto view = str | std::views::split(delimiter);
+    for (const auto& part : view) {
+        result.push_back(std::string(part.begin(), part.end()));
+    }
+    return result;
+}
+
+bool ask_yes_no(const std::string& question, bool defaultYes) {
+    std::string prompt = defaultYes ? "[Y/n] " : "[y/N] ";
+    std::print("{}{}", question, prompt);
+    std::cout.flush();
+
+    std::string input;
+    if (!std::getline(std::cin, input)) return defaultYes;
+    if (input.empty()) return defaultYes;
+
+    return input[0] == 'y' || input[0] == 'Y';
+}
+
+std::string ask_input(const std::string& prompt, const std::string& defaultValue) {
+    std::string displayDefault = defaultValue.empty() ? "(empty)" : defaultValue;
+    std::print("{} [{}]: ", prompt, displayDefault);
+    std::cout.flush();
+
+    std::string input;
+    if (!std::getline(std::cin, input)) return defaultValue;
+
+    return input.empty() ? defaultValue : input;
+}
+
+void print_separator(const std::string& title) {
+    std::println("\n=== {} ===", title);
+}
+
+}
diff --git a/src/core/utils.cppm b/src/core/utils.cppm
index 8a785fbd..c6f966de 100644
--- a/src/core/utils.cppm
+++ b/src/core/utils.cppm
@@ -6,12 +6,7 @@ import std;
 
 export namespace xlings::utils {
 
-[[nodiscard]] std::string get_env_or_default(std::string_view name, std::string_view defaultValue = "") {
-    if (const char* value = std::getenv(name.data()); value != nullptr) {
-        return value;
-    }
-    return std::string{defaultValue};
-}
+[[nodiscard]] std::string get_env_or_default(std::string_view name, std::string_view defaultValue = "");
 
 // Whether the variable EXISTS in the environment -- empty or not.
 //
@@ -21,73 +16,18 @@ export namespace xlings::utils {
 // chose, so `set` must leave it alone; collapsing the two made the four
 // backends disagree, since `${VAR:=v}` and a `-not $env:VAR` test overwrite an
 // empty value while fish's `set -q` does not.
-[[nodiscard]] bool env_is_set(const std::string& name) {
-    return std::getenv(name.c_str()) != nullptr;
-}
+[[nodiscard]] bool env_is_set(const std::string& name);
 
-[[nodiscard]] std::string strip_ansi(const std::string& str) {
-    std::string cleaned;
-    cleaned.reserve(str.size());
+[[nodiscard]] std::string strip_ansi(const std::string& str);
 
-    for (std::size_t i = 0; i < str.size(); ++i) {
-        if (str[i] == '\x1b' && i + 1 < str.size() && str[i + 1] == '[') {
-            i += 2;
-            while (i < str.size() && str[i] != 'm') {
-                ++i;
-            }
-        } else {
-            cleaned.push_back(str[i]);
-        }
-    }
+[[nodiscard]] std::string trim_string(const std::string& str);
 
-    return cleaned;
-}
+[[nodiscard]] std::vector<std::string> split_string(const std::string& str, char delimiter);
 
-[[nodiscard]] std::string trim_string(const std::string& str) {
-    auto cleaned = strip_ansi(str);
+bool ask_yes_no(const std::string& question, bool defaultYes = false);
 
-    auto start = std::ranges::find_if_not(cleaned,
-        [](unsigned char ch) { return std::isspace(ch); });
-    auto endIt = std::ranges::find_if_not(cleaned | std::views::reverse,
-        [](unsigned char ch) { return std::isspace(ch); }).base();
+std::string ask_input(const std::string& prompt, const std::string& defaultValue = "");
 
-    return std::string(start, endIt);
-}
-
-[[nodiscard]] std::vector<std::string> split_string(const std::string& str, char delimiter) {
-    std::vector<std::string> result;
-    auto view = str | std::views::split(delimiter);
-    for (const auto& part : view) {
-        result.push_back(std::string(part.begin(), part.end()));
-    }
-    return result;
-}
-
-bool ask_yes_no(const std::string& question, bool defaultYes = false) {
-    std::string prompt = defaultYes ? "[Y/n] " : "[y/N] ";
-    std::print("{}{}", question, prompt);
-    std::cout.flush();
-
-    std::string input;
-    if (!std::getline(std::cin, input)) return defaultYes;
-    if (input.empty()) return defaultYes;
-
-    return input[0] == 'y' || input[0] == 'Y';
-}
-
-std::string ask_input(const std::string& prompt, const std::string& defaultValue = "") {
-    std::string displayDefault = defaultValue.empty() ? "(empty)" : defaultValue;
-    std::print("{} [{}]: ", prompt, displayDefault);
-    std::cout.flush();
-
-    std::string input;
-    if (!std::getline(std::cin, input)) return defaultValue;
-
-    return input.empty() ? defaultValue : input;
-}
-
-void print_separator(const std::string& title) {
-    std::println("\n=== {} ===", title);
-}
+void print_separator(const std::string& title);
 
 } // export namespace xlings::utils
diff --git a/src/core/version_order.cpp b/src/core/version_order.cpp
new file mode 100644
index 00000000..09fdc5a0
--- /dev/null
+++ b/src/core/version_order.cpp
@@ -0,0 +1,25 @@
+module xlings.core.version_order;
+
+import std;
+import xlings.core.semver;
+
+namespace xlings::version_order {
+
+std::strong_ordering compare(std::string_view lhs, std::string_view rhs) {
+    const int c = semver::compare(lhs, rhs);
+    if (c < 0) return std::strong_ordering::less;
+    if (c > 0) return std::strong_ordering::greater;
+    return std::strong_ordering::equal;
+}
+
+bool is_internal_key(std::string_view value) {
+    return value == "res_versioned";
+}
+
+void sort_desc(std::vector<std::string>& versions) {
+    std::ranges::stable_sort(versions, [](const auto& lhs, const auto& rhs) {
+        return compare(lhs, rhs) > 0;
+    });
+}
+
+}
diff --git a/src/core/version_order.cppm b/src/core/version_order.cppm
index 3cf37f00..c739cec9 100644
--- a/src/core/version_order.cppm
+++ b/src/core/version_order.cppm
@@ -18,21 +18,10 @@ import xlings.core.semver;
 // sorts stay deterministic.
 export namespace xlings::version_order {
 
-std::strong_ordering compare(std::string_view lhs, std::string_view rhs) {
-    const int c = semver::compare(lhs, rhs);
-    if (c < 0) return std::strong_ordering::less;
-    if (c > 0) return std::strong_ordering::greater;
-    return std::strong_ordering::equal;
-}
+std::strong_ordering compare(std::string_view lhs, std::string_view rhs);
 
-bool is_internal_key(std::string_view value) {
-    return value == "res_versioned";
-}
+bool is_internal_key(std::string_view value);
 
-void sort_desc(std::vector<std::string>& versions) {
-    std::ranges::stable_sort(versions, [](const auto& lhs, const auto& rhs) {
-        return compare(lhs, rhs) > 0;
-    });
-}
+void sort_desc(std::vector<std::string>& versions);
 
 }  // namespace xlings::version_order
diff --git a/src/core/xim/catalog.cpp b/src/core/xim/catalog.cpp
new file mode 100644
index 00000000..aa60bcb8
--- /dev/null
+++ b/src/core/xim/catalog.cpp
@@ -0,0 +1,700 @@
+module xlings.core.xim.catalog;
+
+import std;
+import mcpplibs.xpkg;
+import xlings.core.config;
+import xlings.core.log;
+import xlings.core.xim.payload;
+import xlings.core.xim.index;
+import xlings.core.xim.repo;
+import xlings.core.xim.libxpkg.types.type;
+import xlings.core.semver;
+import xlings.platform.target;
+
+namespace xlings::xim {
+
+std::string canonical_package_name(std::string_view namespaceName, std::string_view name) {
+    if (namespaceName.empty()) return std::string(name);
+    return std::string(namespaceName) + ":" + std::string(name);
+}
+
+std::string package_store_name(std::string_view namespaceName, std::string_view name) {
+    if (namespaceName.empty()) return std::string(name);
+    return std::string(namespaceName) + "-x-" + std::string(name);
+}
+
+std::string package_scope_label(PackageScope scope) {
+    return scope == PackageScope::Project ? "project" : "global";
+}
+
+std::string format_ambiguous_candidates(std::string_view target,
+                                        std::span<const PackageMatch> matches) {
+    std::string msg = std::format("package '{}' is ambiguous, candidates:\n", target);
+    for (std::size_t i = 0; i < matches.size(); ++i) {
+        auto& match = matches[i];
+        msg += std::format(
+            "{}. {}@{}   from {} repo '{}'\n",
+            i + 1,
+            match.canonicalName,
+            match.version,
+            package_scope_label(match.scope),
+            match.repoName);
+    }
+    msg += "\nuse one of:\n";
+    for (auto& match : matches) {
+        msg += std::format("  xlings install {}@{}\n", match.canonicalName, match.version);
+    }
+    return msg;
+}
+
+namespace detail_ {
+
+ParsedTarget_ parse_target_(std::string target) {
+    auto nsPos = target.find("::");
+    if (nsPos != std::string::npos) target.replace(nsPos, 2, ":");
+
+    ParsedTarget_ parsed;
+    parsed.raw = target;
+
+    auto at = target.find('@');
+    std::string head = at == std::string::npos ? target : target.substr(0, at);
+    parsed.version = at == std::string::npos ? std::string{} : target.substr(at + 1);
+
+    auto colon = head.find(':');
+    if (colon != std::string::npos) {
+        parsed.explicitNamespace = true;
+        parsed.namespaceName = head.substr(0, colon);
+        parsed.name = head.substr(colon + 1);
+    } else {
+        parsed.name = head;
+    }
+    return parsed;
+}
+
+}
+
+ParsedPackageTarget parse_package_target(std::string target) {
+    const auto parsed = detail_::parse_target_(std::move(target));
+    return {
+        .raw = parsed.raw,
+        .name = parsed.name,
+        .version = parsed.version,
+        .namespaceName = parsed.namespaceName,
+        .explicitNamespace = parsed.explicitNamespace,
+    };
+}
+
+namespace detail_ {
+
+std::string select_version_(const xpkg::Package& pkg,
+                            const std::string& platform,
+                            const std::string& versionHint) {
+    auto platformIt = pkg.xpm.entries.find(platform);
+    if (platformIt == pkg.xpm.entries.end()) return {};
+
+    auto& versions = platformIt->second;
+    if (!versionHint.empty()) {
+        // Direct exact match (handles "latest" ref resolution too)
+        auto directIt = versions.find(versionHint);
+        if (directIt != versions.end()) {
+            return directIt->second.ref.empty() ? versionHint : directIt->second.ref;
+        }
+        // Semver range/prefix matching against available versions
+        std::vector<std::string> available;
+        for (auto& [ver, _] : versions) {
+            if (ver != "latest") available.push_back(ver);
+        }
+        return semver::select_best(available, versionHint);
+    }
+
+    // No hint: resolve "latest" ref or pick highest
+    auto latestIt = versions.find("latest");
+    if (latestIt != versions.end() && !latestIt->second.ref.empty()) {
+        return latestIt->second.ref;
+    }
+
+    std::vector<std::string> available;
+    for (auto& [ver, _] : versions) {
+        if (ver != "latest") available.push_back(ver);
+    }
+    if (!available.empty()) {
+        semver::sort_desc(available);
+        return available[0];
+    }
+    // If no numbered version found but "latest" exists (no ref), use it directly
+    if (latestIt != versions.end()) {
+        return "latest";
+    }
+    return {};
+}
+
+std::string make_canonical_name_(const std::string& namespaceName,
+                                 const std::string& name) {
+    return canonical_package_name(namespaceName, name);
+}
+
+bool same_match_identity_(const PackageMatch& lhs, const PackageMatch& rhs) {
+    return lhs.namespaceName == rhs.namespaceName
+        && lhs.name == rhs.name
+        && lhs.version == rhs.version
+        && lhs.scope == rhs.scope
+        && lhs.repoName == rhs.repoName;
+}
+
+std::vector<PackageMatch> dedupe_matches_(
+    std::vector<PackageMatch> matches) {
+    std::ranges::sort(matches, {}, [](const PackageMatch& match) {
+        return std::tuple {
+            match.canonicalName,
+            match.version,
+            match.scope == PackageScope::Project ? 0 : 1,
+            match.repoName,
+            match.rawName,
+        };
+    });
+    std::vector<PackageMatch> unique;
+    for (auto& match : matches) {
+        const auto seen = std::ranges::any_of(
+            unique, [&](const PackageMatch& existing) {
+                return same_match_identity_(existing, match);
+            });
+        if (!seen) unique.push_back(std::move(match));
+    }
+    return unique;
+}
+
+int namespace_rank_(std::string_view namespaceName) {
+    return namespaceName == "local" ? 1 : 0;   // lower wins
+}
+
+NamespaceRankResult_ prefer_namespace_rank_(
+    const std::vector<PackageMatch>& matches) {
+    NamespaceRankResult_ out;
+    if (matches.empty()) return out;
+    int best = std::ranges::min(
+        matches | std::views::transform([](const PackageMatch& match) {
+            return namespace_rank_(match.namespaceName);
+        }));
+    for (const auto& match : matches) {
+        if (namespace_rank_(match.namespaceName) == best) {
+            out.kept.push_back(match);
+        } else {
+            // Same rule as announce_demotion_: no version, no `@`. This string
+            // is printed as a command the user can copy, and
+            // `xlings install local:binutils@` is not one.
+            out.demoted.push_back(
+                match.version.empty()
+                    ? match.canonicalName
+                    : std::format("{}@{}", match.canonicalName, match.version));
+        }
+    }
+    return out;
+}
+
+std::vector<PackageMatch> prefer_project_scope_(
+    std::vector<PackageMatch> matches) {
+    std::unordered_set<std::string> projectKeys;
+    for (const auto& match : matches) {
+        if (match.scope == PackageScope::Project) {
+            projectKeys.insert(
+                match.canonicalName + "@" + match.version);
+        }
+    }
+    if (projectKeys.empty()) return matches;
+    std::vector<PackageMatch> filtered;
+    for (auto& match : matches) {
+        const auto key = match.canonicalName + "@" + match.version;
+        if (match.scope == PackageScope::Global
+            && projectKeys.contains(key)) {
+            continue;
+        }
+        filtered.push_back(std::move(match));
+    }
+    return filtered;
+}
+
+}
+
+namespace catalog_detail {
+
+std::expected<PackageMatch, std::string>
+resolve_local_identity_from_repos(
+    std::span<const LocalIdentityRepoView> repos,
+    const std::string& target) {
+    const auto parsed = detail_::parse_target_(target);
+    if (parsed.name.empty() || !parsed.version.empty()) {
+        return std::unexpected(std::format(
+            "package identity '{}' is invalid", target));
+    }
+
+    std::vector<PackageMatch> primaryMatches;
+    std::vector<PackageMatch> subMatches;
+    std::optional<std::string_view> namespaceName;
+    if (parsed.explicitNamespace) namespaceName = parsed.namespaceName;
+    for (const auto& repo : repos) {
+        if (repo.index == nullptr) continue;
+        auto& destination = repo.subIndex
+            ? subMatches : primaryMatches;
+        for (const auto& candidate :
+             repo.index->find_candidates(parsed.name, namespaceName)) {
+            auto resolved = repo.index->resolve(candidate);
+            if (resolved.empty()) resolved = candidate;
+            auto matched = repo.index->find_entry(resolved) != nullptr
+                ? std::optional<std::string>{resolved}
+                : repo.index->match_version(resolved);
+            if (!matched) continue;
+            const auto* entry = repo.index->find_entry(*matched);
+            if (entry == nullptr) continue;
+            destination.push_back({
+                .query = parsed.raw,
+                .rawName = *matched,
+                .name = entry->identity.name,
+                .version = entry->version,
+                .namespaceName = entry->identity.namespaceName,
+                .canonicalName = entry->canonicalName,
+                .repoName = repo.repoName,
+                .pkgFile = entry->path,
+                .storeRoot = repo.storeRoot,
+                .scope = repo.scope,
+            });
+        }
+    }
+
+    if (parsed.explicitNamespace || primaryMatches.empty()) {
+        for (auto& match : subMatches) {
+            primaryMatches.push_back(std::move(match));
+        }
+    }
+    auto matches = std::move(primaryMatches);
+    matches = detail_::dedupe_matches_(std::move(matches));
+    if (matches.empty()) {
+        return std::unexpected(std::format(
+            "package '{}' not found", target));
+    }
+    if (matches.size() != 1) {
+        // Same namespace priority the full resolver applies, for the same
+        // reason: this path answers `info`/inventory, and an identity that
+        // resolves for `install` but not for `info` is two answers to one
+        // question -- the defect 2026.8.11.1 was spent removing.
+        if (!parsed.explicitNamespace) {
+            auto ranked = detail_::prefer_namespace_rank_(matches);
+            if (ranked.kept.size() == 1) {
+                auto chosen = std::move(ranked.kept.front());
+                chosen.demoted = std::move(ranked.demoted);
+                return chosen;
+            }
+        }
+        return std::unexpected(format_ambiguous_candidates(
+            target, matches));
+    }
+    return matches.front();
+}
+
+}
+
+std::optional<PackageMatch>
+resolve_local_coordinate(const PackageCatalog& catalog,
+                         std::string_view coordinate) {
+    if (!catalog.is_loaded() || coordinate.empty()) return std::nullopt;
+    auto resolved = catalog.resolve_target(
+        std::string(coordinate), std::string(platform::build_os()));
+    if (!resolved) return std::nullopt;
+    return std::move(*resolved);
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::xim {
+
+std::vector<RepoIndexSpec> PackageCatalog::repo_specs_() {
+    std::vector<RepoIndexSpec> specs;
+    for (auto& repo : Config::project_index_repos()) {
+        specs.push_back({
+            .name = repo.name,
+            .url = repo.url,
+            .dir = Config::repo_dir_for(repo, true),
+            .scope = PackageScope::Project,
+            .defaultNamespace = repo.name,
+        });
+    }
+    auto globalRepos = Config::global_index_repos();
+    for (std::size_t i = 0; i < globalRepos.size(); ++i) {
+        auto repoDir = Config::repo_dir_for(globalRepos[i], false);
+        specs.push_back({
+            .name = globalRepos[i].name,
+            .url = globalRepos[i].url,
+            .dir = repoDir,
+            .scope = PackageScope::Global,
+            .defaultNamespace = globalRepos[i].name,
+        });
+    }
+
+    // Include discovered sub-index repos (from xim-indexrepos.lua / xim-indexrepos.json)
+    for (auto& repo : discovered_global_sub_repos()) {
+        auto subDir = sub_repo_dir_for(repo, false);
+        if (std::filesystem::exists(subDir / "pkgs")) {
+            specs.push_back({
+                .name = repo.name,
+                .url = repo.url,
+                .dir = subDir,
+                .scope = PackageScope::Global,
+                .defaultNamespace = repo.name,
+                .subIndex = true,
+            });
+        }
+    }
+
+    // Include discovered project-local sub-index repos
+    for (auto& repo : discovered_project_sub_repos()) {
+        auto subDir = sub_repo_dir_for(repo, true);
+        if (std::filesystem::exists(subDir / "pkgs")) {
+            specs.push_back({
+                .name = repo.name,
+                .url = repo.url,
+                .dir = subDir,
+                .scope = PackageScope::Project,
+                .defaultNamespace = repo.name,
+                .subIndex = true,
+            });
+        }
+    }
+
+    // Local xpkg repo (from add-xpkg command)
+    auto localRepoDir = Config::global_data_dir() / "xim-pkgindex-local";
+    if (std::filesystem::exists(localRepoDir / "pkgs")) {
+        specs.push_back({
+            .name = "local",
+            .url = "",
+            .dir = localRepoDir,
+            .scope = PackageScope::Global,
+            .defaultNamespace = "local",
+        });
+    }
+
+    return specs;
+}
+
+PackageCatalog::RepoState PackageCatalog::make_state_(const RepoIndexSpec& spec) {
+    RepoState state;
+    state.spec = spec;
+    state.index.set_repo_dir(spec.dir);
+    state.index.set_default_namespace(spec.defaultNamespace);
+    return state;
+}
+
+std::vector<PackageMatch> PackageCatalog::build_matches_(const RepoState& state, const detail_::ParsedTarget_& parsed, const std::string& platform, bool forSearch) {
+    std::optional<std::string_view> namespaceName;
+    if (parsed.explicitNamespace) namespaceName = parsed.namespaceName;
+
+    std::vector<PackageMatch> matches;
+    for (auto& candidate :
+            state.index.find_candidates(parsed.name, namespaceName)) {
+        auto resolved = state.index.resolve(candidate);
+        if (resolved.empty()) resolved = candidate;
+
+        std::optional<std::string> matched;
+        if (state.index.find_entry(resolved)) {
+            matched = resolved;
+        } else {
+            matched = state.index.match_version(resolved);
+        }
+        if (!matched) continue;
+
+        auto* entry = state.index.find_entry(*matched);
+        if (!entry) continue;
+        auto pkg = state.index.load_package(*matched);
+        if (!pkg) continue;
+
+        auto version = detail_::select_version_(*pkg, platform, parsed.version);
+        if (version.empty() && !forSearch) continue;
+
+        PackageMatch match;
+        match.query = parsed.raw;
+        match.rawName = *matched;
+        match.name = entry->identity.name;
+        match.version = version;
+        match.namespaceName = entry->identity.namespaceName;
+        match.canonicalName = entry->canonicalName;
+        match.repoName = state.spec.name;
+        match.pkgFile = entry->path;
+        match.scope = state.spec.scope;
+        match.storeRoot = (state.spec.scope == PackageScope::Project
+            ? Config::project_data_dir()
+            : Config::global_data_dir()) / "xpkgs";
+        if (!version.empty()) {
+            auto installDir = match.storeRoot
+                / package_store_name(match.namespaceName, match.name)
+                / match.version;
+            std::error_code ec;
+            match.installed = std::filesystem::exists(installDir, ec)
+                && std::filesystem::is_directory(installDir, ec)
+                && payload_has_content(installDir);
+            // Whether the payload belongs to THIS platform. Recorded,
+            // not folded into `installed`: the install planner needs it
+            // (an empty plan downloads nothing, so a reinstall would have
+            // no artifact to install from -- and llvm.lua's
+            // os.tryrm(install_dir) then deletes the payload that WAS
+            // there), while remove and list must still see what is on
+            // disk. Only a PROVABLE mismatch counts -- Unknown keeps the
+            // fast path, so nothing that works today starts reinstalling.
+            if (match.installed) {
+                match.payloadForeign =
+                    classify_payload_platform(installDir)
+                        == PayloadPlatform::Foreign;
+            }
+        }
+        matches.push_back(std::move(match));
+    }
+    return matches;
+}
+
+std::vector<PackageMatch> PackageCatalog::collect_matches_(const std::string& target,
+                                               const std::string& platform) const {
+    auto parsed = detail_::parse_target_(target);
+    std::vector<PackageMatch> primaryMatches;
+    std::vector<PackageMatch> subMatches;
+
+    auto collect = [&](const std::vector<RepoState>& repos) {
+        for (const auto& repo : repos) {
+            auto matches = build_matches_(repo, parsed, platform);
+            if (repo.spec.subIndex) {
+                for (auto& match : matches) {
+                    subMatches.push_back(std::move(match));
+                }
+            } else {
+                for (auto& match : matches) {
+                    primaryMatches.push_back(std::move(match));
+                }
+            }
+        }
+    };
+    collect(projectRepos_);
+    collect(globalRepos_);
+
+    // For bare names (no explicit namespace): prefer primary repos.
+    // Only fall through to sub-repos when no primary match exists.
+    // Explicit namespace (e.g. d2x:d2mcpp) always uses all matches.
+    if (!parsed.explicitNamespace && !primaryMatches.empty()) {
+        return detail_::dedupe_matches_(std::move(primaryMatches));
+    }
+
+    // Merge: either explicit namespace or no primary match
+    for (auto& m : subMatches) {
+        primaryMatches.push_back(std::move(m));
+    }
+    return detail_::dedupe_matches_(std::move(primaryMatches));
+}
+
+std::expected<void, std::string> PackageCatalog::rebuild(bool forceRebuild) {
+    projectRepos_.clear();
+    globalRepos_.clear();
+    loadWarnings_.clear();
+    // The recipes behind the cached entries may have just been resynced.
+    packageCache_.clear();
+
+    auto specs = repo_specs_();
+    log::debug("catalog rebuild: {} repo(s), force={}", specs.size(), forceRebuild);
+
+    for (auto& spec : specs) {
+        log::debug("catalog: loading repo '{}' from {}", spec.name, spec.dir.string());
+        auto state = make_state_(spec);
+        auto hash = get_repo_head_hash(spec.dir);
+        auto result = state.index.load_or_rebuild(hash, forceRebuild);
+        if (!result) {
+            // #374: best-effort. A single degenerate/unsynced repo (no
+            // pkgs/, unreachable URL, empty default-namespace redirect
+            // target) must NOT collapse the whole catalog — that is the
+            // exact ">=2 index_repos -> silent exit 1" trigger. Record
+            // the skip and keep loading the rest; the command layer
+            // emits these as wire warnings so the skip is never silent.
+            // Mirrors the best-effort handling sub-index repos already
+            // get in sync_all_repos. loaded_ below still hard-fails only
+            // when NOTHING could be loaded.
+            loadWarnings_.push_back({spec.name, spec.scope, spec.dir, result.error()});
+            log::debug("catalog: skipping repo '{}': {}", spec.name, result.error());
+            continue;
+        }
+        if (spec.scope == PackageScope::Project) {
+            projectRepos_.push_back(std::move(state));
+        } else {
+            globalRepos_.push_back(std::move(state));
+        }
+    }
+
+    loaded_ = !projectRepos_.empty() || !globalRepos_.empty();
+    if (!loaded_) {
+        return std::unexpected(loadWarnings_.empty()
+            ? std::string("no index repositories configured")
+            : loadWarnings_.front().error);
+    }
+    return {};
+}
+
+bool PackageCatalog::is_loaded() const { return loaded_; }
+
+const std::vector<RepoLoadWarning>& PackageCatalog::load_warnings() const { return loadWarnings_; }
+
+std::vector<PackageMatch> PackageCatalog::prefer_project_scope_(std::vector<PackageMatch> matches) {
+    return detail_::prefer_project_scope_(std::move(matches));
+}
+
+void PackageCatalog::announce_demotion_(const std::string& target,
+                            const PackageMatch& chosen) const {
+    if (chosen.demoted.empty()) return;
+    std::string losers;
+    for (const auto& name : chosen.demoted) {
+        if (!losers.empty()) losers += ", ";
+        losers += name;
+    }
+    auto key = target + "\x1f" + chosen.canonicalName + "\x1f" + losers;
+    if (!demotionsAnnounced_.insert(key).second) return;
+    // `@version` only when there IS one. The identity-only path
+    // (resolve_local_identity, used by inventory) does not select a
+    // version, so unconditional formatting printed `local:binutils@` --
+    // measured on a real home right after the release. A trailing `@`
+    // reads as a version that failed to render, which is worse than not
+    // showing one: the whole purpose of this line is that the reader can
+    // trust what it says.
+    const auto withVersion = [](const std::string& name,
+                                const std::string& version) {
+        return version.empty() ? name : name + "@" + version;
+    };
+    log::warn("'{}' also provided by {}; selected {} by namespace "
+              "priority (local ranks last)",
+              target, losers,
+              withVersion(chosen.canonicalName, chosen.version));
+    log::warn("  to pick the other: use its full name, e.g. `{}`",
+              chosen.demoted.front());
+}
+
+std::expected<PackageMatch, std::string> PackageCatalog::resolve_target(const std::string& target,
+                   const std::string& platform) const {
+    auto matches = collect_matches_(target, platform);
+    if (matches.empty()) {
+        return std::unexpected(std::format("package '{}' not found", target));
+    }
+    if (matches.size() > 1) {
+        matches = prefer_project_scope_(std::move(matches));
+        if (matches.size() == 1) return matches.front();
+        if (!detail_::parse_target_(target).explicitNamespace) {
+            auto ranked = detail_::prefer_namespace_rank_(matches);
+            if (ranked.kept.size() == 1) {
+                auto chosen = std::move(ranked.kept.front());
+                chosen.demoted = std::move(ranked.demoted);
+                announce_demotion_(target, chosen);
+                return chosen;
+            }
+        }
+        // The candidate list stays COMPLETE here on purpose. Ranking
+        // failed to decide, so the user has to; hiding the demoted
+        // candidate would offer a menu that does not contain the answer
+        // they may want.
+        return std::unexpected(format_ambiguous_candidates(target, matches));
+    }
+    return matches.front();
+}
+
+std::expected<PackageMatch, std::string> PackageCatalog::resolve_local_identity(const std::string& target) const {
+    std::vector<catalog_detail::LocalIdentityRepoView> views;
+    views.reserve(projectRepos_.size() + globalRepos_.size());
+    const auto append = [&](const std::vector<RepoState>& repos) {
+        for (const auto& repo : repos) {
+            views.push_back({
+                .repoName = repo.spec.name,
+                .scope = repo.spec.scope,
+                .subIndex = repo.spec.subIndex,
+                .index = &repo.index,
+                .storeRoot = (repo.spec.scope == PackageScope::Project
+                    ? Config::project_data_dir()
+                    : Config::global_data_dir()) / "xpkgs",
+            });
+        }
+    };
+    append(projectRepos_);
+    append(globalRepos_);
+    auto match = catalog_detail::resolve_local_identity_from_repos(
+        views, target);
+    // Announce here too. Self-review caught the asymmetry: this path
+    // applied the namespace priority and said nothing, so a bare stamped
+    // identity resolved by inventory would have been a SILENT pick -- the
+    // one thing the rule must not become, and precisely the objection that
+    // justified refusing before it existed.
+    if (match) announce_demotion_(target, *match);
+    return match;
+}
+
+std::vector<PackageMatch> PackageCatalog::search(const std::string& query, const std::string& platform) {
+    std::vector<PackageMatch> results;
+    std::unordered_set<std::string> seen;
+
+    auto append = [&](std::vector<RepoState>& repos) {
+        for (auto& repo : repos) {
+            for (auto& raw : repo.index.search(query)) {
+                for (auto& match : build_matches_(
+                        repo, detail_::parse_target_(raw), platform, true)) {
+                    auto key = match.canonicalName + "@" + match.version
+                        + ":" + match.repoName;
+                    if (seen.insert(key).second) {
+                        results.push_back(std::move(match));
+                    }
+                }
+            }
+        }
+    };
+
+    append(projectRepos_);
+    append(globalRepos_);
+    return detail_::dedupe_matches_(std::move(results));
+}
+
+std::expected<xpkg::Package, std::string> PackageCatalog::load_package(const PackageMatch& match) {
+    // Loading a package means starting a Lua state and executing the
+    // recipe file. `search()` already does that once per candidate while
+    // it builds the matches, so every caller that then asks for the same
+    // package pays for a second evaluation of the same file.
+    //
+    // Keyed by what identifies the file, not by the query that found it.
+    // Lifetime is the process: an index that changed underneath a running
+    // command would invalidate the matches too, and `rebuild()` clears it.
+    const auto key = std::format("{}\x1f{}\x1f{}",
+        match.scope == PackageScope::Project ? "p" : "g",
+        match.repoName, match.rawName);
+    if (const auto cached = packageCache_.find(key);
+        cached != packageCache_.end()) {
+        return cached->second;
+    }
+
+    auto load = [&](std::vector<RepoState>& repos) -> std::expected<xpkg::Package, std::string> {
+        for (auto& repo : repos) {
+            if (repo.spec.name != match.repoName || repo.spec.scope != match.scope) continue;
+            return repo.index.load_package(match.rawName);
+        }
+        return std::unexpected(std::format("package '{}' not loaded", match.canonicalName));
+    };
+
+    auto result = match.scope == PackageScope::Project
+        ? load(projectRepos_) : load(globalRepos_);
+    if (result) packageCache_.emplace(key, *result);
+    return result;
+}
+
+void PackageCatalog::mark_installed(const PackageMatch& match, bool installed) {
+    auto update = [&](std::vector<RepoState>& repos) {
+        for (auto& repo : repos) {
+            if (repo.spec.name == match.repoName && repo.spec.scope == match.scope) {
+                repo.index.mark_installed(match.rawName, installed);
+                return;
+            }
+        }
+    };
+    if (match.scope == PackageScope::Project) {
+        update(projectRepos_);
+    } else {
+        update(globalRepos_);
+    }
+}
+
+} // namespace xlings::xim
diff --git a/src/core/xim/catalog.cppm b/src/core/xim/catalog.cppm
index dba03c71..2acd398c 100644
--- a/src/core/xim/catalog.cppm
+++ b/src/core/xim/catalog.cppm
@@ -67,19 +67,11 @@ struct RepoLoadWarning {
     std::string error;
 };
 
-std::string canonical_package_name(std::string_view namespaceName, std::string_view name) {
-    if (namespaceName.empty()) return std::string(name);
-    return std::string(namespaceName) + ":" + std::string(name);
-}
+std::string canonical_package_name(std::string_view namespaceName, std::string_view name);
 
-std::string package_store_name(std::string_view namespaceName, std::string_view name) {
-    if (namespaceName.empty()) return std::string(name);
-    return std::string(namespaceName) + "-x-" + std::string(name);
-}
+std::string package_store_name(std::string_view namespaceName, std::string_view name);
 
-std::string package_scope_label(PackageScope scope) {
-    return scope == PackageScope::Project ? "project" : "global";
-}
+std::string package_scope_label(PackageScope scope);
 
 // The parsed shape of a command-line coordinate: `[ns:]name[@version]`.
 //
@@ -98,24 +90,7 @@ struct ParsedPackageTarget {
 ParsedPackageTarget parse_package_target(std::string target);
 
 std::string format_ambiguous_candidates(std::string_view target,
-                                        std::span<const PackageMatch> matches) {
-    std::string msg = std::format("package '{}' is ambiguous, candidates:\n", target);
-    for (std::size_t i = 0; i < matches.size(); ++i) {
-        auto& match = matches[i];
-        msg += std::format(
-            "{}. {}@{}   from {} repo '{}'\n",
-            i + 1,
-            match.canonicalName,
-            match.version,
-            package_scope_label(match.scope),
-            match.repoName);
-    }
-    msg += "\nuse one of:\n";
-    for (auto& match : matches) {
-        msg += std::format("  xlings install {}@{}\n", match.canonicalName, match.version);
-    }
-    return msg;
-}
+                                        std::span<const PackageMatch> matches);
 
 namespace detail_ {
 
@@ -127,122 +102,28 @@ struct ParsedTarget_ {
     bool explicitNamespace { false };
 };
 
-ParsedTarget_ parse_target_(std::string target) {
-    auto nsPos = target.find("::");
-    if (nsPos != std::string::npos) target.replace(nsPos, 2, ":");
-
-    ParsedTarget_ parsed;
-    parsed.raw = target;
-
-    auto at = target.find('@');
-    std::string head = at == std::string::npos ? target : target.substr(0, at);
-    parsed.version = at == std::string::npos ? std::string{} : target.substr(at + 1);
-
-    auto colon = head.find(':');
-    if (colon != std::string::npos) {
-        parsed.explicitNamespace = true;
-        parsed.namespaceName = head.substr(0, colon);
-        parsed.name = head.substr(colon + 1);
-    } else {
-        parsed.name = head;
-    }
-    return parsed;
-}
+ParsedTarget_ parse_target_(std::string target);
 
 }  // namespace detail_
 
 // Definition sits here rather than beside the declaration: it delegates to
 // detail_::parse_target_, which is what every other resolution path uses, so
 // the exported form cannot drift from the internal one.
-ParsedPackageTarget parse_package_target(std::string target) {
-    const auto parsed = detail_::parse_target_(std::move(target));
-    return {
-        .raw = parsed.raw,
-        .name = parsed.name,
-        .version = parsed.version,
-        .namespaceName = parsed.namespaceName,
-        .explicitNamespace = parsed.explicitNamespace,
-    };
-}
+ParsedPackageTarget parse_package_target(std::string target);
 
 namespace detail_ {
 
 std::string select_version_(const xpkg::Package& pkg,
                             const std::string& platform,
-                            const std::string& versionHint) {
-    auto platformIt = pkg.xpm.entries.find(platform);
-    if (platformIt == pkg.xpm.entries.end()) return {};
-
-    auto& versions = platformIt->second;
-    if (!versionHint.empty()) {
-        // Direct exact match (handles "latest" ref resolution too)
-        auto directIt = versions.find(versionHint);
-        if (directIt != versions.end()) {
-            return directIt->second.ref.empty() ? versionHint : directIt->second.ref;
-        }
-        // Semver range/prefix matching against available versions
-        std::vector<std::string> available;
-        for (auto& [ver, _] : versions) {
-            if (ver != "latest") available.push_back(ver);
-        }
-        return semver::select_best(available, versionHint);
-    }
-
-    // No hint: resolve "latest" ref or pick highest
-    auto latestIt = versions.find("latest");
-    if (latestIt != versions.end() && !latestIt->second.ref.empty()) {
-        return latestIt->second.ref;
-    }
-
-    std::vector<std::string> available;
-    for (auto& [ver, _] : versions) {
-        if (ver != "latest") available.push_back(ver);
-    }
-    if (!available.empty()) {
-        semver::sort_desc(available);
-        return available[0];
-    }
-    // If no numbered version found but "latest" exists (no ref), use it directly
-    if (latestIt != versions.end()) {
-        return "latest";
-    }
-    return {};
-}
+                            const std::string& versionHint);
 
 std::string make_canonical_name_(const std::string& namespaceName,
-                                 const std::string& name) {
-    return canonical_package_name(namespaceName, name);
-}
-
-bool same_match_identity_(const PackageMatch& lhs, const PackageMatch& rhs) {
-    return lhs.namespaceName == rhs.namespaceName
-        && lhs.name == rhs.name
-        && lhs.version == rhs.version
-        && lhs.scope == rhs.scope
-        && lhs.repoName == rhs.repoName;
-}
+                                 const std::string& name);
+
+bool same_match_identity_(const PackageMatch& lhs, const PackageMatch& rhs);
 
 std::vector<PackageMatch> dedupe_matches_(
-    std::vector<PackageMatch> matches) {
-    std::ranges::sort(matches, {}, [](const PackageMatch& match) {
-        return std::tuple {
-            match.canonicalName,
-            match.version,
-            match.scope == PackageScope::Project ? 0 : 1,
-            match.repoName,
-            match.rawName,
-        };
-    });
-    std::vector<PackageMatch> unique;
-    for (auto& match : matches) {
-        const auto seen = std::ranges::any_of(
-            unique, [&](const PackageMatch& existing) {
-                return same_match_identity_(existing, match);
-            });
-        if (!seen) unique.push_back(std::move(match));
-    }
-    return unique;
-}
+    std::vector<PackageMatch> matches);
 
 // Namespace priority: `local` ranks below every other namespace.
 //
@@ -275,9 +156,7 @@ std::vector<PackageMatch> dedupe_matches_(
 //   * The loser is NAMED (PackageMatch::demoted -> one printed line). This
 //     turns "undetermined" into "determined, and here is what it beat", which
 //     is a different thing from determinism being dropped.
-int namespace_rank_(std::string_view namespaceName) {
-    return namespaceName == "local" ? 1 : 0;   // lower wins
-}
+int namespace_rank_(std::string_view namespaceName);
 
 struct NamespaceRankResult_ {
     std::vector<PackageMatch> kept;
@@ -293,50 +172,10 @@ struct NamespaceRankResult_ {
 // one edit to `&&` would silently produce an ambiguity message full of empty
 // strings. A vector of a handful of matches is not worth that.
 NamespaceRankResult_ prefer_namespace_rank_(
-    const std::vector<PackageMatch>& matches) {
-    NamespaceRankResult_ out;
-    if (matches.empty()) return out;
-    int best = std::ranges::min(
-        matches | std::views::transform([](const PackageMatch& match) {
-            return namespace_rank_(match.namespaceName);
-        }));
-    for (const auto& match : matches) {
-        if (namespace_rank_(match.namespaceName) == best) {
-            out.kept.push_back(match);
-        } else {
-            // Same rule as announce_demotion_: no version, no `@`. This string
-            // is printed as a command the user can copy, and
-            // `xlings install local:binutils@` is not one.
-            out.demoted.push_back(
-                match.version.empty()
-                    ? match.canonicalName
-                    : std::format("{}@{}", match.canonicalName, match.version));
-        }
-    }
-    return out;
-}
+    const std::vector<PackageMatch>& matches);
 
 std::vector<PackageMatch> prefer_project_scope_(
-    std::vector<PackageMatch> matches) {
-    std::unordered_set<std::string> projectKeys;
-    for (const auto& match : matches) {
-        if (match.scope == PackageScope::Project) {
-            projectKeys.insert(
-                match.canonicalName + "@" + match.version);
-        }
-    }
-    if (projectKeys.empty()) return matches;
-    std::vector<PackageMatch> filtered;
-    for (auto& match : matches) {
-        const auto key = match.canonicalName + "@" + match.version;
-        if (match.scope == PackageScope::Global
-            && projectKeys.contains(key)) {
-            continue;
-        }
-        filtered.push_back(std::move(match));
-    }
-    return filtered;
-}
+    std::vector<PackageMatch> matches);
 
 }  // namespace detail_
 
@@ -353,75 +192,7 @@ struct LocalIdentityRepoView {
 std::expected<PackageMatch, std::string>
 resolve_local_identity_from_repos(
     std::span<const LocalIdentityRepoView> repos,
-    const std::string& target) {
-    const auto parsed = detail_::parse_target_(target);
-    if (parsed.name.empty() || !parsed.version.empty()) {
-        return std::unexpected(std::format(
-            "package identity '{}' is invalid", target));
-    }
-
-    std::vector<PackageMatch> primaryMatches;
-    std::vector<PackageMatch> subMatches;
-    std::optional<std::string_view> namespaceName;
-    if (parsed.explicitNamespace) namespaceName = parsed.namespaceName;
-    for (const auto& repo : repos) {
-        if (repo.index == nullptr) continue;
-        auto& destination = repo.subIndex
-            ? subMatches : primaryMatches;
-        for (const auto& candidate :
-             repo.index->find_candidates(parsed.name, namespaceName)) {
-            auto resolved = repo.index->resolve(candidate);
-            if (resolved.empty()) resolved = candidate;
-            auto matched = repo.index->find_entry(resolved) != nullptr
-                ? std::optional<std::string>{resolved}
-                : repo.index->match_version(resolved);
-            if (!matched) continue;
-            const auto* entry = repo.index->find_entry(*matched);
-            if (entry == nullptr) continue;
-            destination.push_back({
-                .query = parsed.raw,
-                .rawName = *matched,
-                .name = entry->identity.name,
-                .version = entry->version,
-                .namespaceName = entry->identity.namespaceName,
-                .canonicalName = entry->canonicalName,
-                .repoName = repo.repoName,
-                .pkgFile = entry->path,
-                .storeRoot = repo.storeRoot,
-                .scope = repo.scope,
-            });
-        }
-    }
-
-    if (parsed.explicitNamespace || primaryMatches.empty()) {
-        for (auto& match : subMatches) {
-            primaryMatches.push_back(std::move(match));
-        }
-    }
-    auto matches = std::move(primaryMatches);
-    matches = detail_::dedupe_matches_(std::move(matches));
-    if (matches.empty()) {
-        return std::unexpected(std::format(
-            "package '{}' not found", target));
-    }
-    if (matches.size() != 1) {
-        // Same namespace priority the full resolver applies, for the same
-        // reason: this path answers `info`/inventory, and an identity that
-        // resolves for `install` but not for `info` is two answers to one
-        // question -- the defect 2026.8.11.1 was spent removing.
-        if (!parsed.explicitNamespace) {
-            auto ranked = detail_::prefer_namespace_rank_(matches);
-            if (ranked.kept.size() == 1) {
-                auto chosen = std::move(ranked.kept.front());
-                chosen.demoted = std::move(ranked.demoted);
-                return chosen;
-            }
-        }
-        return std::unexpected(format_ambiguous_candidates(
-            target, matches));
-    }
-    return matches.front();
-}
+    const std::string& target);
 
 }  // namespace catalog_detail
 
@@ -443,247 +214,32 @@ class PackageCatalog {
     mutable std::unordered_set<std::string> demotionsAnnounced_;
     bool loaded_ { false };
 
-    static std::vector<RepoIndexSpec> repo_specs_() {
-        std::vector<RepoIndexSpec> specs;
-        for (auto& repo : Config::project_index_repos()) {
-            specs.push_back({
-                .name = repo.name,
-                .url = repo.url,
-                .dir = Config::repo_dir_for(repo, true),
-                .scope = PackageScope::Project,
-                .defaultNamespace = repo.name,
-            });
-        }
-        auto globalRepos = Config::global_index_repos();
-        for (std::size_t i = 0; i < globalRepos.size(); ++i) {
-            auto repoDir = Config::repo_dir_for(globalRepos[i], false);
-            specs.push_back({
-                .name = globalRepos[i].name,
-                .url = globalRepos[i].url,
-                .dir = repoDir,
-                .scope = PackageScope::Global,
-                .defaultNamespace = globalRepos[i].name,
-            });
-        }
-
-        // Include discovered sub-index repos (from xim-indexrepos.lua / xim-indexrepos.json)
-        for (auto& repo : discovered_global_sub_repos()) {
-            auto subDir = sub_repo_dir_for(repo, false);
-            if (std::filesystem::exists(subDir / "pkgs")) {
-                specs.push_back({
-                    .name = repo.name,
-                    .url = repo.url,
-                    .dir = subDir,
-                    .scope = PackageScope::Global,
-                    .defaultNamespace = repo.name,
-                    .subIndex = true,
-                });
-            }
-        }
-
-        // Include discovered project-local sub-index repos
-        for (auto& repo : discovered_project_sub_repos()) {
-            auto subDir = sub_repo_dir_for(repo, true);
-            if (std::filesystem::exists(subDir / "pkgs")) {
-                specs.push_back({
-                    .name = repo.name,
-                    .url = repo.url,
-                    .dir = subDir,
-                    .scope = PackageScope::Project,
-                    .defaultNamespace = repo.name,
-                    .subIndex = true,
-                });
-            }
-        }
-
-        // Local xpkg repo (from add-xpkg command)
-        auto localRepoDir = Config::global_data_dir() / "xim-pkgindex-local";
-        if (std::filesystem::exists(localRepoDir / "pkgs")) {
-            specs.push_back({
-                .name = "local",
-                .url = "",
-                .dir = localRepoDir,
-                .scope = PackageScope::Global,
-                .defaultNamespace = "local",
-            });
-        }
-
-        return specs;
-    }
-
-    static RepoState make_state_(const RepoIndexSpec& spec) {
-        RepoState state;
-        state.spec = spec;
-        state.index.set_repo_dir(spec.dir);
-        state.index.set_default_namespace(spec.defaultNamespace);
-        return state;
-    }
+    static std::vector<RepoIndexSpec> repo_specs_();
+
+    static RepoState make_state_(const RepoIndexSpec& spec);
 
     static std::vector<PackageMatch>
     build_matches_(const RepoState& state,
                    const detail_::ParsedTarget_& parsed,
                    const std::string& platform,
-                   bool forSearch = false) {
-        std::optional<std::string_view> namespaceName;
-        if (parsed.explicitNamespace) namespaceName = parsed.namespaceName;
-
-        std::vector<PackageMatch> matches;
-        for (auto& candidate :
-                state.index.find_candidates(parsed.name, namespaceName)) {
-            auto resolved = state.index.resolve(candidate);
-            if (resolved.empty()) resolved = candidate;
-
-            std::optional<std::string> matched;
-            if (state.index.find_entry(resolved)) {
-                matched = resolved;
-            } else {
-                matched = state.index.match_version(resolved);
-            }
-            if (!matched) continue;
-
-            auto* entry = state.index.find_entry(*matched);
-            if (!entry) continue;
-            auto pkg = state.index.load_package(*matched);
-            if (!pkg) continue;
-
-            auto version = detail_::select_version_(*pkg, platform, parsed.version);
-            if (version.empty() && !forSearch) continue;
-
-            PackageMatch match;
-            match.query = parsed.raw;
-            match.rawName = *matched;
-            match.name = entry->identity.name;
-            match.version = version;
-            match.namespaceName = entry->identity.namespaceName;
-            match.canonicalName = entry->canonicalName;
-            match.repoName = state.spec.name;
-            match.pkgFile = entry->path;
-            match.scope = state.spec.scope;
-            match.storeRoot = (state.spec.scope == PackageScope::Project
-                ? Config::project_data_dir()
-                : Config::global_data_dir()) / "xpkgs";
-            if (!version.empty()) {
-                auto installDir = match.storeRoot
-                    / package_store_name(match.namespaceName, match.name)
-                    / match.version;
-                std::error_code ec;
-                match.installed = std::filesystem::exists(installDir, ec)
-                    && std::filesystem::is_directory(installDir, ec)
-                    && payload_has_content(installDir);
-                // Whether the payload belongs to THIS platform. Recorded,
-                // not folded into `installed`: the install planner needs it
-                // (an empty plan downloads nothing, so a reinstall would have
-                // no artifact to install from -- and llvm.lua's
-                // os.tryrm(install_dir) then deletes the payload that WAS
-                // there), while remove and list must still see what is on
-                // disk. Only a PROVABLE mismatch counts -- Unknown keeps the
-                // fast path, so nothing that works today starts reinstalling.
-                if (match.installed) {
-                    match.payloadForeign =
-                        classify_payload_platform(installDir)
-                            == PayloadPlatform::Foreign;
-                }
-            }
-            matches.push_back(std::move(match));
-        }
-        return matches;
-    }
+                   bool forSearch = false);
 
     std::vector<PackageMatch> collect_matches_(const std::string& target,
-                                               const std::string& platform) const {
-        auto parsed = detail_::parse_target_(target);
-        std::vector<PackageMatch> primaryMatches;
-        std::vector<PackageMatch> subMatches;
-
-        auto collect = [&](const std::vector<RepoState>& repos) {
-            for (const auto& repo : repos) {
-                auto matches = build_matches_(repo, parsed, platform);
-                if (repo.spec.subIndex) {
-                    for (auto& match : matches) {
-                        subMatches.push_back(std::move(match));
-                    }
-                } else {
-                    for (auto& match : matches) {
-                        primaryMatches.push_back(std::move(match));
-                    }
-                }
-            }
-        };
-        collect(projectRepos_);
-        collect(globalRepos_);
-
-        // For bare names (no explicit namespace): prefer primary repos.
-        // Only fall through to sub-repos when no primary match exists.
-        // Explicit namespace (e.g. d2x:d2mcpp) always uses all matches.
-        if (!parsed.explicitNamespace && !primaryMatches.empty()) {
-            return detail_::dedupe_matches_(std::move(primaryMatches));
-        }
-
-        // Merge: either explicit namespace or no primary match
-        for (auto& m : subMatches) {
-            primaryMatches.push_back(std::move(m));
-        }
-        return detail_::dedupe_matches_(std::move(primaryMatches));
-    }
+                                               const std::string& platform) const;
 
 public:
-    std::expected<void, std::string> rebuild(bool forceRebuild = false) {
-        projectRepos_.clear();
-        globalRepos_.clear();
-        loadWarnings_.clear();
-        // The recipes behind the cached entries may have just been resynced.
-        packageCache_.clear();
-
-        auto specs = repo_specs_();
-        log::debug("catalog rebuild: {} repo(s), force={}", specs.size(), forceRebuild);
-
-        for (auto& spec : specs) {
-            log::debug("catalog: loading repo '{}' from {}", spec.name, spec.dir.string());
-            auto state = make_state_(spec);
-            auto hash = get_repo_head_hash(spec.dir);
-            auto result = state.index.load_or_rebuild(hash, forceRebuild);
-            if (!result) {
-                // #374: best-effort. A single degenerate/unsynced repo (no
-                // pkgs/, unreachable URL, empty default-namespace redirect
-                // target) must NOT collapse the whole catalog — that is the
-                // exact ">=2 index_repos -> silent exit 1" trigger. Record
-                // the skip and keep loading the rest; the command layer
-                // emits these as wire warnings so the skip is never silent.
-                // Mirrors the best-effort handling sub-index repos already
-                // get in sync_all_repos. loaded_ below still hard-fails only
-                // when NOTHING could be loaded.
-                loadWarnings_.push_back({spec.name, spec.scope, spec.dir, result.error()});
-                log::debug("catalog: skipping repo '{}': {}", spec.name, result.error());
-                continue;
-            }
-            if (spec.scope == PackageScope::Project) {
-                projectRepos_.push_back(std::move(state));
-            } else {
-                globalRepos_.push_back(std::move(state));
-            }
-        }
-
-        loaded_ = !projectRepos_.empty() || !globalRepos_.empty();
-        if (!loaded_) {
-            return std::unexpected(loadWarnings_.empty()
-                ? std::string("no index repositories configured")
-                : loadWarnings_.front().error);
-        }
-        return {};
-    }
-
-    bool is_loaded() const { return loaded_; }
+    std::expected<void, std::string> rebuild(bool forceRebuild = false);
+
+    bool is_loaded() const;
 
     // #374: repos skipped during the last rebuild (best-effort). The
     // command layer emits these on the EventStream so a degraded
     // multi-repo config is visible to interface consumers (mcpp), not
     // silently swallowed.
-    const std::vector<RepoLoadWarning>& load_warnings() const { return loadWarnings_; }
+    const std::vector<RepoLoadWarning>& load_warnings() const;
 
     // When project and global have the same package, keep only project-scoped match
-    static std::vector<PackageMatch> prefer_project_scope_(std::vector<PackageMatch> matches) {
-        return detail_::prefer_project_scope_(std::move(matches));
-    }
+    static std::vector<PackageMatch> prefer_project_scope_(std::vector<PackageMatch> matches);
 
     // Say which candidate the namespace priority beat, exactly once.
     //
@@ -694,166 +250,24 @@ public:
     // then a silent pick, which is the whole thing this rule must not become.
     // One writer, deduplicated by what it actually said.
     void announce_demotion_(const std::string& target,
-                            const PackageMatch& chosen) const {
-        if (chosen.demoted.empty()) return;
-        std::string losers;
-        for (const auto& name : chosen.demoted) {
-            if (!losers.empty()) losers += ", ";
-            losers += name;
-        }
-        auto key = target + "\x1f" + chosen.canonicalName + "\x1f" + losers;
-        if (!demotionsAnnounced_.insert(key).second) return;
-        // `@version` only when there IS one. The identity-only path
-        // (resolve_local_identity, used by inventory) does not select a
-        // version, so unconditional formatting printed `local:binutils@` --
-        // measured on a real home right after the release. A trailing `@`
-        // reads as a version that failed to render, which is worse than not
-        // showing one: the whole purpose of this line is that the reader can
-        // trust what it says.
-        const auto withVersion = [](const std::string& name,
-                                    const std::string& version) {
-            return version.empty() ? name : name + "@" + version;
-        };
-        log::warn("'{}' also provided by {}; selected {} by namespace "
-                  "priority (local ranks last)",
-                  target, losers,
-                  withVersion(chosen.canonicalName, chosen.version));
-        log::warn("  to pick the other: use its full name, e.g. `{}`",
-                  chosen.demoted.front());
-    }
+                            const PackageMatch& chosen) const;
 
     std::expected<PackageMatch, std::string>
     resolve_target(const std::string& target,
-                   const std::string& platform) const {
-        auto matches = collect_matches_(target, platform);
-        if (matches.empty()) {
-            return std::unexpected(std::format("package '{}' not found", target));
-        }
-        if (matches.size() > 1) {
-            matches = prefer_project_scope_(std::move(matches));
-            if (matches.size() == 1) return matches.front();
-            if (!detail_::parse_target_(target).explicitNamespace) {
-                auto ranked = detail_::prefer_namespace_rank_(matches);
-                if (ranked.kept.size() == 1) {
-                    auto chosen = std::move(ranked.kept.front());
-                    chosen.demoted = std::move(ranked.demoted);
-                    announce_demotion_(target, chosen);
-                    return chosen;
-                }
-            }
-            // The candidate list stays COMPLETE here on purpose. Ranking
-            // failed to decide, so the user has to; hiding the demoted
-            // candidate would offer a menu that does not contain the answer
-            // they may want.
-            return std::unexpected(format_ambiguous_candidates(target, matches));
-        }
-        return matches.front();
-    }
+                   const std::string& platform) const;
 
     // Resolve an already-indexed package identity without evaluating its Lua
     // recipe, selecting a version, syncing a repository, or touching payload
     // contents. Inventory uses this as a leaf existence/uniqueness check so a
     // missing stamped identity cannot turn into an all-recipe scan.
     std::expected<PackageMatch, std::string>
-    resolve_local_identity(const std::string& target) const {
-        std::vector<catalog_detail::LocalIdentityRepoView> views;
-        views.reserve(projectRepos_.size() + globalRepos_.size());
-        const auto append = [&](const std::vector<RepoState>& repos) {
-            for (const auto& repo : repos) {
-                views.push_back({
-                    .repoName = repo.spec.name,
-                    .scope = repo.spec.scope,
-                    .subIndex = repo.spec.subIndex,
-                    .index = &repo.index,
-                    .storeRoot = (repo.spec.scope == PackageScope::Project
-                        ? Config::project_data_dir()
-                        : Config::global_data_dir()) / "xpkgs",
-                });
-            }
-        };
-        append(projectRepos_);
-        append(globalRepos_);
-        auto match = catalog_detail::resolve_local_identity_from_repos(
-            views, target);
-        // Announce here too. Self-review caught the asymmetry: this path
-        // applied the namespace priority and said nothing, so a bare stamped
-        // identity resolved by inventory would have been a SILENT pick -- the
-        // one thing the rule must not become, and precisely the objection that
-        // justified refusing before it existed.
-        if (match) announce_demotion_(target, *match);
-        return match;
-    }
-
-    std::vector<PackageMatch> search(const std::string& query, const std::string& platform) {
-        std::vector<PackageMatch> results;
-        std::unordered_set<std::string> seen;
-
-        auto append = [&](std::vector<RepoState>& repos) {
-            for (auto& repo : repos) {
-                for (auto& raw : repo.index.search(query)) {
-                    for (auto& match : build_matches_(
-                            repo, detail_::parse_target_(raw), platform, true)) {
-                        auto key = match.canonicalName + "@" + match.version
-                            + ":" + match.repoName;
-                        if (seen.insert(key).second) {
-                            results.push_back(std::move(match));
-                        }
-                    }
-                }
-            }
-        };
-
-        append(projectRepos_);
-        append(globalRepos_);
-        return detail_::dedupe_matches_(std::move(results));
-    }
-
-    std::expected<xpkg::Package, std::string> load_package(const PackageMatch& match) {
-        // Loading a package means starting a Lua state and executing the
-        // recipe file. `search()` already does that once per candidate while
-        // it builds the matches, so every caller that then asks for the same
-        // package pays for a second evaluation of the same file.
-        //
-        // Keyed by what identifies the file, not by the query that found it.
-        // Lifetime is the process: an index that changed underneath a running
-        // command would invalidate the matches too, and `rebuild()` clears it.
-        const auto key = std::format("{}\x1f{}\x1f{}",
-            match.scope == PackageScope::Project ? "p" : "g",
-            match.repoName, match.rawName);
-        if (const auto cached = packageCache_.find(key);
-            cached != packageCache_.end()) {
-            return cached->second;
-        }
-
-        auto load = [&](std::vector<RepoState>& repos) -> std::expected<xpkg::Package, std::string> {
-            for (auto& repo : repos) {
-                if (repo.spec.name != match.repoName || repo.spec.scope != match.scope) continue;
-                return repo.index.load_package(match.rawName);
-            }
-            return std::unexpected(std::format("package '{}' not loaded", match.canonicalName));
-        };
-
-        auto result = match.scope == PackageScope::Project
-            ? load(projectRepos_) : load(globalRepos_);
-        if (result) packageCache_.emplace(key, *result);
-        return result;
-    }
-
-    void mark_installed(const PackageMatch& match, bool installed) {
-        auto update = [&](std::vector<RepoState>& repos) {
-            for (auto& repo : repos) {
-                if (repo.spec.name == match.repoName && repo.spec.scope == match.scope) {
-                    repo.index.mark_installed(match.rawName, installed);
-                    return;
-                }
-            }
-        };
-        if (match.scope == PackageScope::Project) {
-            update(projectRepos_);
-        } else {
-            update(globalRepos_);
-        }
-    }
+    resolve_local_identity(const std::string& target) const;
+
+    std::vector<PackageMatch> search(const std::string& query, const std::string& platform);
+
+    std::expected<xpkg::Package, std::string> load_package(const PackageMatch& match);
+
+    void mark_installed(const PackageMatch& match, bool installed);
 };
 
 // Resolve one package coordinate against an already-loaded catalog. This is a
@@ -862,12 +276,6 @@ public:
 // ambiguity and project-preference rules as normal package resolution.
 std::optional<PackageMatch>
 resolve_local_coordinate(const PackageCatalog& catalog,
-                         std::string_view coordinate) {
-    if (!catalog.is_loaded() || coordinate.empty()) return std::nullopt;
-    auto resolved = catalog.resolve_target(
-        std::string(coordinate), std::string(platform::build_os()));
-    if (!resolved) return std::nullopt;
-    return std::move(*resolved);
-}
+                         std::string_view coordinate);
 
 }  // namespace xlings::xim
diff --git a/src/core/xim/commands.cpp b/src/core/xim/commands.cpp
new file mode 100644
index 00000000..98880abc
--- /dev/null
+++ b/src/core/xim/commands.cpp
@@ -0,0 +1,1722 @@
+module xlings.core.xim.commands;
+
+import std;
+import xlings.core.xim.libxpkg.types.type;
+import mcpplibs.xpkg;
+import mcpplibs.xpkg.executor;
+import mcpplibs.xpkg.loader;
+import xlings.core.xim.catalog;
+import xlings.core.xim.payload;
+import xlings.core.xim.inventory;
+import xlings.core.xim.repo;
+import xlings.core.xim.resolver;
+import xlings.core.xim.downloader;
+import xlings.core.xim.installer;
+import xlings.core.log;
+import xlings.core.config;
+import xlings.core.profile;
+import xlings.runtime;
+import xlings.libs.json;
+import xlings.core.i18n;
+import xlings.platform;
+import xlings.platform.target;
+import xlings.libs.tinyhttps;
+import xlings.core.xvm.db;
+import xlings.core.xvm.lock;
+import xlings.core.xvm.commands;
+import xlings.core.xvm.shim;
+import xlings.core.profile;
+import xlings.runtime.cancellation;
+import xlings.core.version_order;
+import xlings.core.xself.repair;
+
+namespace xlings::xim {
+
+PackageCatalog& get_catalog(CatalogAccess access) {
+    static PackageCatalog mgr;
+    static bool initialized = false;
+    static bool installReadyChecked = false;
+    // No rebuild yet on this call. A default-constructed expected<void,...> is
+    // a SUCCESS value, so leaving it as "the result" would make "never probed"
+    // and "probed and fine" the same thing -- and the self-heal below only ever
+    // fires on a failure it can see.
+    std::optional<std::expected<void, std::string>> result;
+    if (!initialized) {
+        result = mgr.rebuild();
+        initialized = true;
+    }
+
+    if (access == CatalogAccess::InstallReady && !installReadyChecked) {
+        // A LocalOnly caller may have initialized the singleton before an
+        // install reaches it. Rebuild once here so this access request has a
+        // current error to report before attempting the repair sync.
+        if (!result && !mgr.is_loaded()) result = mgr.rebuild();
+
+        // #366: on a fresh machine the main index rebuilds fine, but the
+        // default sub-indexes were never synced — their pkgs/ dirs don't
+        // exist, so repo_specs_() skips them and rebuild() still SUCCEEDS.
+        // The old code only synced in the failure branch, so scode/awesome/d2x
+        // stayed absent and `install scode:...` failed with "not found" until
+        // the user ran `xlings update`. Force a one-time sync when the
+        // sub-index marker JSON is missing (cheap: skipped on every later run).
+        bool subIndexesNeverSynced = !sub_indexes_initialized();
+        const bool buildFailed = result.has_value() && !result->has_value();
+        if (buildFailed || subIndexesNeverSynced) {
+            if (buildFailed) {
+                // Self-heal: a broken/absent index tree (interrupted fetch on
+                // an older xlings, wiped cache) is repairable — resync and
+                // rebuild once before surfacing an error the user would have
+                // to fix by running `xlings update` themselves.
+                log::warn("catalog build failed ({}); resyncing indexes...",
+                          result->error());
+            } else {
+                log::info("initializing package sub-indexes (first run)...");
+            }
+            if (sync_all_repos(true)) {
+                result = mgr.rebuild(true);
+            }
+            if (result.has_value() && !result->has_value()) {
+                log::error("failed to build catalog: {}", result->error());
+                log::info("try running: xlings update");
+            }
+        }
+        installReadyChecked = true;
+    }
+    return mgr;
+}
+
+std::string detect_platform() {
+    return std::string(xlings::platform::build_os());
+}
+
+bool index_refresh_cooldown_elapsed() {
+    using namespace std::chrono;
+    static steady_clock::time_point last{};
+    static bool primed = false;
+    auto now = steady_clock::now();
+    if (primed && now - last < seconds(60)) return false;
+    last = now;
+    primed = true;
+    return true;
+}
+
+int cmd_why(const std::string& target, const std::string& dep,
+            EventStream& stream) {
+    namespace fs = std::filesystem;
+    const auto store = Config::paths().dataDir / "xpkgs";
+    std::error_code ec;
+    if (!fs::is_directory(store, ec)) {
+        stream.emit(ErrorEvent{.code = ErrorCode::InvalidInput,
+                               .message = "no packages are installed",
+                               .recoverable = false});
+        return 1;
+    }
+
+    auto bare = target;
+    if (auto at = bare.find('@'); at != std::string::npos) bare.resize(at);
+    if (auto colon = bare.find(':'); colon != std::string::npos)
+        bare = bare.substr(colon + 1);
+
+    // Every installed version of the named package: a home can hold more
+    // than one, and "which one did you mean" is better answered by showing
+    // both than by picking.
+    std::vector<fs::path> records;
+    for (const auto& pkgDir : platform::dir_entries(store)) {
+        if (!pkgDir.is_directory()) continue;
+        const auto storeName = pkgDir.path().filename().string();
+        // `<ns>-x-<name>`; match the name half.
+        auto marker = storeName.find("-x-");
+        if (marker == std::string::npos) continue;
+        if (storeName.substr(marker + 3) != bare) continue;
+        for (const auto& verDir : platform::dir_entries(pkgDir.path())) {
+            auto rec = verDir.path() / ".xlings-resolution.json";
+            if (fs::is_regular_file(rec, ec)) records.push_back(rec);
+        }
+    }
+    if (records.empty()) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = std::format("no resolution record for '{}'", bare),
+            .recoverable = false,
+            .hint = "records are written at install time; reinstall the "
+                    "package to produce one"});
+        return 1;
+    }
+
+    for (const auto& recPath : records) {
+        auto content = platform::read_file_to_string(recPath.string());
+        auto json = nlohmann::json::parse(content, nullptr, false);
+        if (json.is_discarded()) continue;
+        std::println("{}", json.value("package", std::string{}));
+        for (const auto& d : json.value("deps", nlohmann::json::array())) {
+            const auto spec = d.value("spec", std::string{});
+            if (!dep.empty() && spec.find(dep) == std::string::npos) continue;
+            std::println("  {}", spec);
+            std::println("    resolved  {}   (source: {})",
+                         d.value("version", std::string{}),
+                         d.value("source", std::string{}));
+            std::println("    payload   {}",
+                         Config::display_path(d.value("install_dir", std::string{})));
+            for (const auto& l : d.value("libdirs", nlohmann::json::array())) {
+                std::println("    libdir    {}",
+                             Config::display_path(l.get<std::string>()));
+            }
+        }
+    }
+    return 0;
+}
+
+int cmd_install(std::span<const std::string> targets, bool yes, bool noDeps, EventStream& stream, bool forceGlobal, CancellationToken* cancel, bool dryRun, bool useAfterInstall) {
+    // Serialize against any other xlings mutating this home, then re-read
+    // state under the lock: Config loaded it at process start, outside the
+    // lock, so acting on that snapshot is how two commands lose each other's
+    // work. See xvm/lock.cppm.
+    auto stateLock = xvm::acquire_state_lock(Config::paths().homeDir);
+    if (!stateLock) {
+        log::error("{}", stateLock.error());
+        return 1;
+    }
+
+    // An emulated build installs emulated packages -- correctly, since they
+    // have to match this process's ABI, and slowly, since every one of them
+    // then runs under Rosetta / WOW64 / qemu. The user is the only one who can
+    // decide to switch, and cannot decide if nobody says it. Said at install
+    // time because that is when the cost is being incurred.
+    if (platform::is_emulated()) {
+        log::warn("this xlings is a {} build running on {} hardware; packages "
+                  "will match the build, not the machine. A native {} release "
+                  "avoids the emulation.",
+                  platform::build().arch, platform::host().arch,
+                  platform::host().str());
+    }
+    Config::reload_state();
+
+    auto& catalog = get_catalog(CatalogAccess::InstallReady);
+    if (!catalog.is_loaded()) {
+        log::info("package index not available, updating...");
+        sync_all_repos(true);
+        auto rebuildResult = catalog.rebuild();
+        if (!rebuildResult || !catalog.is_loaded()) {
+            // #374: emit a structured error on the EventStream instead of a
+            // bare log::error (which interface mode's tui_mode suppresses) so
+            // programmatic consumers see WHY the exit is non-zero rather than
+            // a silent {"exitCode":1,"kind":"result"} with an empty stream.
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::NotFound,
+                .message = std::string("package index not available")
+                    + (rebuildResult ? std::string{} : ": " + rebuildResult.error()),
+                .recoverable = true,
+                .hint = "run `xlings update`, or check index_repos in .xlings.json",
+            });
+            return 1;
+        }
+    }
+
+    // #374: surface any index repos skipped during the best-effort catalog
+    // build so a degraded multi-repo config is visible to interface consumers
+    // (mcpp) instead of silently ignored. Non-fatal — healthy repos still
+    // resolve; this only makes the skip observable on the wire.
+    for (auto& w : catalog.load_warnings()) {
+        stream.emit(LogEvent{LogLevel::warn,
+            "index repo '" + w.name + "' skipped ("
+            + (w.scope == PackageScope::Project ? "project" : "global")
+            + " scope): " + w.error});
+    }
+
+    auto platform = detect_platform();
+    std::vector<std::string> targetVec(targets.begin(), targets.end());
+    std::vector<PackageMatch> requestedMatches;
+    // C2 (#366 UX): allow at most one on-demand index refresh per install call.
+    bool refreshedForMissing = false;
+
+    // #374: for structured not-found errors, name the repos we searched so
+    // interface consumers can see the resolution scope (the issue asks to
+    // identify "which repositories were searched").
+    auto searched_repos_ = [&]() {
+        std::string s;
+        auto add = [&](const std::string& n) { if (!s.empty()) s += ", "; s += n; };
+        for (auto& r : Config::project_index_repos()) add(r.name);
+        for (auto& r : Config::global_index_repos()) add(r.name);
+        return s;
+    };
+
+    // Idempotency: `install` is NOT supposed to be a silent upgrader.
+    // If the package already has a version active in the current sub-OS
+    // that satisfies the user's request — bare name (no @ver) accepts
+    // anything, `name@<prefix>` accepts any active version starting with
+    // the prefix — pin the resolution to that exact version. The existing
+    // "all packages already installed" fast path takes it from there.
+    // For deliberate upgrades, users should run `xlings update <pkg>`.
+    // What is active in the workspace this install is about to write into.
+    // Top-level targets and expanded dependencies both resolve through it, so
+    // "already satisfied" means the same thing on both paths -- it used to be
+    // applied here only, with a `starts_with` test of its own, which made
+    // `@1.1` match an active `1.10` and left every dependency resolving to the
+    // index's newest version.
+    auto active_version_of_ = [](const std::string& name) {
+        return xvm::get_active_version(Config::effective_workspace(), name);
+    };
+    auto pin_to_active_if_satisfies_ = [&](const std::string& t) -> std::string {
+        return pin_target_to_active(t, active_version_of_);
+    };
+
+    for (auto& target : targetVec) {
+        auto pinned = pin_to_active_if_satisfies_(target);
+        auto match = catalog.resolve_target(pinned, platform);
+        if (!match && pinned != target) {
+            // Active version no longer in the catalog (xpm declaration changed
+            // since install) — fall back to the original target so the user
+            // still gets a useful resolve / error / fuzzy-match path.
+            match = catalog.resolve_target(target, platform);
+        }
+        // C2 (#366 UX): a target absent from the current catalog may simply be
+        // newer than the local index (package/version just published). Refresh
+        // the index once and retry before giving up, so `install <fresh-pkg>`
+        // — including explicit-namespace targets like `scode:linux-headers` —
+        // works without a manual `xlings update`. Debounced by a per-call guard
+        // + a process-wide cooldown; ambiguous errors are not "missing".
+        if (!match && !refreshedForMissing
+                && !match.error().contains("ambiguous")
+                && index_refresh_cooldown_elapsed()) {
+            refreshedForMissing = true;
+            log::info("'{}' not in current index; refreshing index...", target);
+            if (sync_all_repos(true)) {
+                catalog.rebuild(true);
+                match = catalog.resolve_target(pinned, platform);
+                if (!match && pinned != target) {
+                    match = catalog.resolve_target(target, platform);
+                }
+            }
+        }
+        if (!match) {
+            // Ambiguous matches: show error directly, don't fall through to fuzzy
+            if (match.error().contains("ambiguous")) {
+                // #374: structured error on the wire (was a swallowed log::error)
+                stream.emit(ErrorEvent{
+                    .code = ErrorCode::InvalidInput,
+                    .message = match.error(),
+                    .recoverable = true,
+                    .hint = "install a specific candidate with its full namespace:name@version",
+                });
+                return 1;
+            }
+            // Explicit namespace (e.g. scode:linux-headers) -- don't fuzzy-match
+            // across other namespaces, which can cause infinite recursion
+            if (target.find(':') != std::string::npos) {
+                // #374: structured error on the wire (was a swallowed log::error)
+                stream.emit(ErrorEvent{
+                    .code = ErrorCode::NotFound,
+                    .message = match.error(),
+                    .recoverable = true,
+                    .hint = "searched repos: [" + searched_repos_()
+                        + "]; run `xlings update` if the package was just published",
+                });
+                return 1;
+            }
+            // Try fuzzy search for suggestions
+            auto fuzzy = catalog.search(target, platform);
+            if (fuzzy.empty()) {
+                // #374: structured error on the wire (was a swallowed log::error)
+                stream.emit(ErrorEvent{
+                    .code = ErrorCode::NotFound,
+                    .message = match.error(),
+                    .recoverable = true,
+                    .hint = "searched repos: [" + searched_repos_()
+                        + "]; run `xlings update` if the package was just published",
+                });
+                return 1;
+            }
+            if (fuzzy.size() > 5) fuzzy.resize(5);
+
+            if (fuzzy.size() == 1) {
+                // Single fuzzy match -- use it directly
+                match = fuzzy.front();
+            } else if (yes) {
+                // -y mode: auto-select first match
+                match = fuzzy.front();
+            } else {
+                // Interactive selection via EventStream prompt
+                std::vector<std::string> options;
+                for (auto& f : fuzzy) {
+                    options.push_back(f.canonicalName + "@" + f.version);
+                }
+                PromptEvent req;
+                req.id = "select_package";
+                req.question = "Multiple matches found. Select a package:";
+                req.options = std::move(options);
+                auto chosen = stream.prompt(std::move(req));
+                if (chosen.empty()) {
+                    log::println("cancelled");
+                    return 0;
+                }
+                // Find matching fuzzy result
+                for (auto& f : fuzzy) {
+                    if ((f.canonicalName + "@" + f.version) == chosen) {
+                        match = f;
+                        break;
+                    }
+                }
+                if (!match) {
+                    log::println("cancelled");
+                    return 0;
+                }
+            }
+        }
+        // Update target to the canonical "<ns:name>@<version>" form so that
+        // the downstream dependency resolver (which calls resolve_target
+        // again on each item in targetVec) lands on this exact version.
+        // Without this, pin_to_active_if_satisfies_ above is silently undone
+        // when the resolver picks the catalog's highest-declared version for
+        // bare-name targets.
+        target = match->canonicalName;
+        if (!match->version.empty()) {
+            target += "@" + match->version;
+        }
+        requestedMatches.push_back(*match);
+    }
+
+    // Resolve dependencies
+    auto planResult = resolve(catalog, targetVec, platform, active_version_of_);
+    if (!planResult) {
+        // #374: structured error on the wire (was a swallowed log::error)
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = "dependency resolution failed: " + planResult.error(),
+            .recoverable = true,
+        });
+        return 1;
+    }
+
+    auto& plan = *planResult;
+    if (plan.has_errors()) {
+        // #374: structured errors on the wire (were swallowed log::error)
+        for (auto& err : plan.errors) {
+            stream.emit(ErrorEvent{
+                .code = ErrorCode::InvalidInput,
+                .message = err,
+                .recoverable = true,
+            });
+        }
+        return 1;
+    }
+
+    // -g: register versions/workspace in global scope so tools work outside project dir
+    if (forceGlobal) {
+        bool hasProjectOnly = false;
+        for (auto& node : plan.nodes) {
+            if (node.scope == PackageScope::Project) {
+                log::warn("-g ignored for '{}': only exists in project-local index", node.name);
+                hasProjectOnly = true;
+            }
+        }
+        if (hasProjectOnly) {
+            log::warn("-g disabled: cannot globally register project-only packages (uninstall would fail)");
+        } else {
+            Config::set_force_global_scope(true);
+        }
+    }
+
+    auto plan_key = [](const PackageMatch& match) {
+        return match.canonicalName + "@" + match.version;
+    };
+
+    std::unordered_map<std::string, bool> requestedAlreadyInstalled;
+    for (auto& match : requestedMatches) {
+        requestedAlreadyInstalled[plan_key(match)] =
+            match.installed && !match.payloadForeign;
+    }
+
+    auto activate_requested_targets = [&]() {
+        auto db = Config::versions();
+        for (auto& match : requestedMatches) {
+            auto active = xvm::get_active_version(Config::effective_workspace(), match.name);
+            // Only switch when nothing is active yet for this program OR the
+            // user passed --use to force activation. Otherwise preserve the
+            // existing active version. Pairs with the symmetric guard in
+            // installer.cppm process_xvm_operations_.
+            if ((active.empty() || useAfterInstall) &&
+                xvm::has_version(db, match.name, match.version)) {
+                auto useRet = xvm::cmd_use(match.name, match.version, stream);
+                if (useRet != 0) {
+                    log::warn("failed to activate {}@{} in current subos",
+                              match.name, match.version);
+                }
+            } else if (!active.empty() && active != match.version) {
+                // Declining to switch is a decision, and it used to be a
+                // silent one: `install llvm@20.1.7` printed nothing but
+                // success while `clang++` stayed on 22.1.8, so the version
+                // the user asked for was installed and unreachable.
+                log::println(
+                    "{}@{} installed, but '{}' still resolves to {} "
+                    "— `xlings use {} {}` to switch",
+                    match.canonicalName, match.version, match.name, active,
+                    match.name, match.version);
+            }
+            log::debug("version: {}", match.version);
+            if (requestedAlreadyInstalled[plan_key(match)]) {
+                log::debug("{}@{} already installed", match.canonicalName, match.version);
+            } else {
+                log::debug("{}@{} installed", match.canonicalName, match.version);
+            }
+        }
+    };
+
+    auto pending = plan.pending_count();
+    auto allAlreadyInstalled = (pending == 0);
+    if (allAlreadyInstalled) {
+        for (auto& m : requestedMatches) {
+            log::println("{}@{} is already installed", m.canonicalName, m.version);
+        }
+    }
+
+    // Show install plan with themed UI
+    if (!allAlreadyInstalled) {
+        nlohmann::json planPackages = nlohmann::json::array();
+        for (auto& node : plan.nodes) {
+            if (!node.alreadyInstalled) {
+                std::string nameVer = node.canonicalName;
+                if (!node.version.empty()) nameVer += "@" + node.version;
+                planPackages.push_back({nameVer, ""});
+            }
+        }
+        nlohmann::json planPayload;
+        planPayload["packages"] = std::move(planPackages);
+        stream.emit(DataEvent{"install_plan", planPayload.dump()});
+    }
+
+    // dry-run stops here — clients (plan_install) only want the plan.
+    if (dryRun) {
+        return 0;
+    }
+
+    // Confirm via EventStream prompt
+    if (!allAlreadyInstalled && !yes) {
+        PromptEvent confirmReq;
+        confirmReq.id = "confirm_install";
+        confirmReq.question = "Proceed with installation?";
+        confirmReq.options = {"y", "n"};
+        confirmReq.defaultValue = "y";
+        auto answer = stream.prompt(std::move(confirmReq));
+        if (answer != "y") {
+            log::println("cancelled");
+            return 0;
+        }
+    }
+
+    // Execute install
+    Installer installer(catalog);
+    DownloaderConfig dlConfig;
+    auto mirror = Config::mirror();
+    if (!mirror.empty()) dlConfig.preferredMirror = mirror;
+
+    // Download progress renderer: emit via EventStream so consumers can render.
+    // CLI consumer renders ftxui progress bars; agent TUI shows summary text.
+    DownloadProgressRenderer dlRenderer = [&stream](std::span<const TaskProgress> state,
+                  std::size_t nameWidth, double elapsedSec, bool sizesReady,
+                  int prevLines) -> int {
+        nlohmann::json files = nlohmann::json::array();
+        for (auto& p : state) {
+            files.push_back({
+                {"name", p.name},
+                {"totalBytes", p.totalBytes},
+                {"downloadedBytes", p.downloadedBytes},
+                {"started", p.started},
+                {"finished", p.finished},
+                {"success", p.success}
+            });
+        }
+        nlohmann::json payload;
+        payload["files"] = std::move(files);
+        payload["nameWidth"] = nameWidth;
+        payload["elapsedSec"] = elapsedSec;
+        payload["sizesReady"] = sizesReady;
+        payload["prevLines"] = prevLines;
+        stream.emit(DataEvent{"download_progress", payload.dump()});
+        return static_cast<int>(state.size()) + 2;
+    };
+
+    int successCount = 0;
+    int failedCount = 0;
+
+    auto result = installer.execute(plan, dlConfig,
+        [&, cancel](const InstallStatus& status) {
+            switch (status.phase) {
+                case InstallPhase::Downloading:
+                    break;  // TUI progress bar handles this
+                case InstallPhase::Installing:
+                    log::debug("[{}] installing...", status.name);
+                    break;
+                case InstallPhase::Configuring:
+                    log::debug("[{}] configuring...", status.name);
+                    break;
+                case InstallPhase::Done:
+                    log::debug("[{}] done", status.name);
+                    ++successCount;
+                    break;
+                case InstallPhase::Failed:
+                    // #374: structured per-package failure on the wire so
+                    // interface consumers see WHICH package failed (was a
+                    // swallowed log::error). failedCount still drives exitCode.
+                    stream.emit(ErrorEvent{
+                        .code = ErrorCode::Internal,
+                        .message = "[" + status.name + "] failed: " + status.message,
+                        .recoverable = true,
+                    });
+                    ++failedCount;
+                    break;
+                default:
+                    break;
+            }
+        },
+        // Process deferred pkgmanager.install()/remove() requests synchronously
+        // between install and config hooks so config can access sub-dependencies
+        [forceGlobal, useAfterInstall, &stream](const std::vector<mcpplibs::xpkg::InstallRequest>& reqs) {
+            for (auto& req : reqs) {
+                if (req.op == "install") {
+                    log::debug("installing sub-dependency: {}", req.target);
+                    std::vector<std::string> subTargets = { req.target };
+                    cmd_install(subTargets, /*yes=*/true, /*noDeps=*/false, stream,
+                                forceGlobal, /*cancel=*/nullptr, /*dryRun=*/false,
+                                useAfterInstall);
+                } else if (req.op == "remove") {
+                    log::debug("removing sub-dependency: {}", req.target);
+                    // force: an xpkg hook asking for a removal has already
+                    // reasoned about what it is replacing. Letting the
+                    // reverse-dep guard veto it would break recipes that
+                    // legitimately swap one provider for another mid-install.
+                    cmd_remove(req.target, /*yes=*/true, stream, /*force=*/true);
+                }
+            }
+        },
+        dlRenderer, cancel, useAfterInstall);
+
+    if (!result) {
+        // #374: structured error on the wire (was a swallowed log::error)
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::Internal,
+            .message = "install failed: " + result.error(),
+            .recoverable = false,
+        });
+        return 1;
+    }
+
+    activate_requested_targets();
+    if (!allAlreadyInstalled) {
+        nlohmann::json summaryPayload;
+        summaryPayload["success"] = successCount;
+        summaryPayload["failed"] = failedCount;
+        stream.emit(DataEvent{"install_summary", summaryPayload.dump()});
+
+        // If this install ran via `sudo`, the downloaded payloads, version DB
+        // and shims were written root-owned into the user's home. Hand the
+        // home back to the invoking user so a later non-sudo `xlings install`
+        // isn't locked out by EACCES. No-op for pure root / non-root installs
+        // (lchown is metadata-only, so even large payload trees are cheap).
+        platform::chown_to_invoker(Config::paths().homeDir);
+    }
+    // Per-package failures (download / extract / hook) are surfaced via
+    // InstallPhase::Failed callbacks and accumulate in `failedCount`;
+    // installer.execute itself only returns unexpected on cancel or
+    // plan-level errors. Without checking failedCount here, `xlings
+    // install` and `interface install_packages` would report exitCode=0
+    // even when individual packages failed to install — see
+    // .agents/docs/2026-05-22-cmd-install-silent-failure-analysis.md
+    xself::print_migration_hint_once(Config::recorded_client_version(),
+                                     Info::VERSION);
+    return failedCount > 0 ? 1 : 0;
+}
+
+std::expected<bool, std::string>
+selected_payloadless_config_has_uninstall_(
+        PackageCatalog& catalog,
+        const PackageMatch& match,
+        std::string_view platform) {
+    auto package = catalog.load_package(match);
+    if (!package) return std::unexpected(package.error());
+    if (package->type != xpkg::PackageType::Config) return false;
+
+    const auto hasDeps = [&](const auto& deps) {
+        auto it = deps.find(std::string(platform));
+        return it != deps.end() && !it->second.empty();
+    };
+    if (hasDeps(package->xpm.deps)
+        || hasDeps(package->xpm.runtime_deps)
+        || hasDeps(package->xpm.build_deps)) {
+        return false;
+    }
+
+    const auto storeRoot = match.storeRoot.empty()
+        ? Config::paths().dataDir / "xpkgs"
+        : match.storeRoot;
+    const auto installDir = storeRoot
+        / package_store_name(match.namespaceName, match.name)
+        / match.version;
+    const auto snapshot = installDir / ".xpkg.lua";
+    std::error_code ec;
+    const auto recipe = std::filesystem::is_regular_file(snapshot, ec)
+        ? snapshot
+        : match.pkgFile;
+    ec.clear();
+    if (!std::filesystem::is_regular_file(recipe, ec)) {
+        return std::unexpected(std::format(
+            "uninstall recipe is not a local file: {}", recipe.string()));
+    }
+
+    auto executor = xpkg::create_executor(recipe);
+    if (!executor) return std::unexpected(executor.error());
+    return executor->has_hook(xpkg::HookType::Uninstall);
+}
+
+int cmd_remove(const std::string& target, bool yes, EventStream& stream,
+               bool force) {
+    // Serialize against any other xlings mutating this home, then re-read
+    // state under the lock: Config loaded it at process start, outside the
+    // lock, so acting on that snapshot is how two commands lose each other's
+    // work. See xvm/lock.cppm.
+    auto stateLock = xvm::acquire_state_lock(Config::paths().homeDir);
+    if (!stateLock) {
+        log::error("{}", stateLock.error());
+        return 1;
+    }
+
+    // An emulated build installs emulated packages -- correctly, since they
+    // have to match this process's ABI, and slowly, since every one of them
+    // then runs under Rosetta / WOW64 / qemu. The user is the only one who can
+    // decide to switch, and cannot decide if nobody says it. Said at install
+    // time because that is when the cost is being incurred.
+    if (platform::is_emulated()) {
+        log::warn("this xlings is a {} build running on {} hardware; packages "
+                  "will match the build, not the machine. A native {} release "
+                  "avoids the emulation.",
+                  platform::build().arch, platform::host().arch,
+                  platform::host().str());
+    }
+    Config::reload_state();
+
+    auto& catalog = get_catalog();
+    if (!catalog.is_loaded()) {
+        log::error("package index not available");
+        return 1;
+    }
+
+    // Resolve up-front so the prompt and summary can show the canonical
+    // name + version + active subos. When the user did not pin a version,
+    // prefer the active one — catalog.resolve_target's default is the
+    // highest *declared* version, which may not be installed.
+    std::string displayName = target;
+    std::string displayVersion;
+    std::string subos = Config::paths().activeSubos;
+    bool payloadlessUninstallProven = false;
+
+    // 0.4.19+: subos-membership guard.
+    //
+    // Pre-fix: in a fresh (or pruned) subos, `xlings remove gcc` would
+    // reach the catalog, resolve to whatever version the recipe declared
+    // as "default", attempt detach (no-op since gcc is not in this
+    // subos's workspace), then succeed via the cross-subos refcount
+    // path because gcc IS installed in some OTHER subos. Net effect:
+    // confusing "✓ removed (subos: tmp)" output for a version the user
+    // never had. Refuse early and tell them where the package actually
+    // lives.
+    {
+        auto stripVer = [](const std::string& s) {
+            auto at = s.find('@');
+            return (at == std::string::npos) ? s : s.substr(0, at);
+        };
+        auto bareWithoutVer = stripVer(target);
+        auto bareName = bareWithoutVer.substr(bareWithoutVer.rfind(':') + 1);
+
+        const auto& ws  = Config::workspace();
+        const auto& wsi = Config::workspace_installed();
+        bool in_active    = ws.contains(bareName) && !ws.at(bareName).empty();
+        bool in_installed = wsi.contains(bareName) && !wsi.at(bareName).empty();
+
+        if (!in_active && !in_installed) {
+            // Which subos(es) DO have this package? Computed first, because it
+            // is what separates the two cases below.
+            auto referencing = xlings::profile::find_subos_referencing(
+                Config::paths().homeDir, bareName);
+            std::erase(referencing, subos);
+
+            if (!referencing.empty()) {
+                // The case this guard was written for (0.4.19+): the package
+                // lives in ANOTHER subos. Removing it here detaches rather
+                // than removes, and the cross-subos refcount path would then
+                // report "✓ removed (subos: tmp)" for a version the user never
+                // had. Refuse, and say where it actually lives.
+                log::warn("xlings: '{}' is not installed in current subos '{}'",
+                          bareName, subos);
+                std::string list;
+                for (auto& n : referencing) {
+                    if (!list.empty()) list += ", ";
+                    list += n;
+                }
+                log::warn("  installed in subos: {}", list);
+                log::warn("  hint: `xlings subos use {}` then `xlings remove {}`",
+                          referencing.front(), bareName);
+                return 0;
+            }
+
+            // No subos claims it. Ask the disk before concluding it is absent
+            // -- the two workspace tables are bookkeeping, and a payload can
+            // outlive them (openxlings/xlings#511).
+            //
+            // Answering "not installed" here while a payload sits in xpkgs/ is
+            // not a harmless no-op: `install` treats a present payload
+            // directory as already installed and skips the install AND its
+            // config() hook. So `install -> remove (success) -> install` leaves
+            // a package whose config() never runs again. That is the same
+            // cascade that produced the aarch64 failure in #509, where an
+            // unconfigured gcc payload emitted binaries carrying the packaging
+            // machine's PT_INTERP and the error named the wrong file entirely.
+            bool payloadOnDisk = false;
+            {
+                namespace fs = std::filesystem;
+                const auto store = Config::paths().dataDir / "xpkgs";
+                std::error_code pec;
+                if (fs::is_directory(store, pec)) {
+                    for (const auto& pkgDir : platform::dir_entries(store)) {
+                        if (!pkgDir.is_directory()) continue;
+                        const auto storeName = pkgDir.path().filename().string();
+                        auto marker = storeName.find("-x-");
+                        if (marker == std::string::npos) continue;
+                        if (storeName.substr(marker + 3) != bareName) continue;
+                        for (const auto& verDir :
+                             platform::dir_entries(pkgDir.path())) {
+                            if (!verDir.is_directory()) continue;
+                            if (payload_has_content(verDir.path())) {
+                                payloadOnDisk = true;
+                                break;
+                            }
+                        }
+                        if (payloadOnDisk) break;
+                    }
+                }
+            }
+
+            if (!payloadOnDisk) {
+                // Nothing here is installed. The only question left is whether
+                // this coordinate is a payloadless config whose uninstall hook
+                // still has work to do -- and being unable to answer it is not
+                // the same as answering "yes".
+                //
+                // What an unanswerable question MEANS depends on how the user
+                // asked it, and these are two different questions:
+                //
+                //   `remove pkg`        -- "make sure pkg is gone". Scripts
+                //       re-run this defensively, and a package whose recipe has
+                //       left the index is as gone as it gets. Warn, exit 0.
+                //       That is the convention the block below states.
+                //   `remove pkg@9.9.9`  -- "remove THIS version". Nothing here
+                //       has it and the index has never heard of it, so the
+                //       coordinate itself is wrong. Say so and fail; reporting
+                //       success would confirm a removal of something that
+                //       cannot exist.
+                const bool explicitVersion = target.contains('@');
+                auto selected = catalog.resolve_target(
+                    target, detect_platform());
+                std::expected<bool, std::string> executable = false;
+                if (selected) {
+                    executable = selected_payloadless_config_has_uninstall_(
+                        catalog, *selected, detect_platform());
+                }
+                if (!selected || !executable) {
+                    const auto reason = selected ? executable.error()
+                                                 : selected.error();
+                    if (explicitVersion) {
+                        stream.emit(ErrorEvent{
+                            .code = reason.contains("ambiguous")
+                                ? ErrorCode::InvalidInput
+                                : ErrorCode::NotFound,
+                            .message = reason,
+                            .recoverable = true,
+                            .hint = "verify the package coordinate, or drop "
+                                    "the version to remove whatever is installed",
+                        });
+                        return 1;
+                    }
+                    log::warn("xlings: cannot inspect an uninstall recipe for "
+                              "'{}' ({}); treating it as absent",
+                              target, reason);
+                }
+                if (executable && *executable) {
+                    payloadlessUninstallProven = true;
+                    log::info("{}@{} has an executable payloadless config "
+                              "uninstall; running it",
+                              selected->canonicalName, selected->version);
+                } else {
+                    // Genuinely absent. Here the "remove what isn't there is
+                    // success" convention is right (S4 of
+                    // remove_multi_version_test.sh asserts exit 0 and no
+                    // `removed.*subos` summary), so keep it -- with a visible
+                    // diagnostic, and without breaking scripts that re-run
+                    // `remove` defensively.
+                    log::warn(
+                        "xlings: '{}' is not installed in current subos '{}'",
+                        bareName, subos);
+                    return 0;
+                }
+            }
+
+            if (payloadOnDisk) {
+                log::warn("xlings: '{}' is not registered in subos '{}', but a "
+                          "payload is on disk; removing it for real",
+                          bareName, subos);
+            }
+        }
+    }
+
+    std::string resolveTarget = target;
+    if (target.find('@') == std::string::npos) {
+        auto bareName = target.substr(target.rfind(':') + 1);
+
+        // `remove <name>` with several versions installed here: SAY SO.
+        //
+        // This started as a refusal -- list the candidates, exit 2, on the
+        // reasoning that in every error `remove` raises about multi-version
+        // state the active binding is not the version being complained about.
+        // E2E-13 killed it, and was right to: `remove <pkg>` taking the active
+        // version and re-pointing the binding at the highest survivor is a
+        // documented, tested contract (docs/bugfixes/2026-04-25-...), and
+        // "run it three times to clear three versions" is a loop people write.
+        // The evidence behind the refusal came from the ERROR paths of #541 ②;
+        // generalising it to the ordinary path was not supported by it.
+        //
+        // What survives is the half that was actually missing: the user cannot
+        // see that this package has other versions here, or how to name them.
+        // Same move as the entry binary in this release -- ANNOUNCE the
+        // divergence, do not refuse it -- and consistency with that is most of
+        // the argument.
+        //
+        // `--force` is exempt: the xpkg hook path (pkgmanager.remove) passes it
+        // precisely because a recipe swapping a provider mid-install has
+        // already reasoned about what it replaces, and an extra paragraph in
+        // the middle of an install helps nobody.
+        if (!force) {
+            const auto& wsi = Config::workspace_installed();
+            if (auto it = wsi.find(bareName);
+                it != wsi.end() && it->second.size() > 1) {
+                auto versions = it->second;
+                version_order::sort_desc(versions);
+                log::warn("'{}' has {} versions installed in subos '{}'; this "
+                          "removes the ACTIVE one only",
+                          bareName, versions.size(), subos);
+                for (const auto& v : versions) {
+                    log::warn("  xlings remove {}@{}", target, v);
+                }
+            }
+        }
+
+        auto active = xvm::get_active_version(
+            Config::effective_workspace(), bareName);
+        // Fall back to "any installed version" when the active binding
+        // has been cleared. The catalog's default version pick is the
+        // recipe's highest *declared* version, which may not match what's
+        // on disk. Before this fallback, a sequence like
+        //
+        //     xlings remove d2x        # detaches active binding
+        //     xlings use d2x           # error: 'd2x' not in version DB
+        //     xlings remove d2x        # ← still picks declared 0.1.4!
+        //
+        // would loop forever: each subsequent remove re-resolved to the
+        // recipe's latest, hit `installer.uninstall` as a no-op (xvm DB
+        // already empty, payload dir already gone), and printed
+        // "✓ removed" anyway. Picking from the xvm DB instead anchors
+        // the resolution to reality.
+        if (active.empty()) {
+            // The database has to outlive the pointer into it.
+            // Config::versions() returns by VALUE, so passing the call
+            // directly to get_vinfo() handed back a pointer into a temporary
+            // that died at the end of that full expression -- and the next
+            // line read it. Use-after-free: `xlings remove glibc` on a home
+            // where glibc is registered but not active SIGSEGV'd on the
+            // released musl-static build and threw bad_alloc on a glibc one,
+            // from pick_highest_version walking a map that was gone.
+            //
+            // Reported 2026-07-28; reproduces identically on 2026.7.27.2,
+            // .3 and .4, so it is as old as this fallback.
+            const auto db = Config::versions();
+            const auto* vinfo = xvm::get_vinfo(db, bareName);
+            if (vinfo && !vinfo->versions.empty()) {
+                active = xvm::pick_highest_version(vinfo->versions);
+            }
+        }
+        if (!active.empty()) {
+            resolveTarget = target + "@" + active;
+        }
+    }
+
+    auto match = catalog.resolve_target(resolveTarget, detect_platform());
+    if (match) {
+        displayName = match->canonicalName;
+        displayVersion = match->version;
+        // Refuse to "remove" a version whose payload isn't on disk. The
+        // earlier version of this check only fired when the user pinned
+        // a version — under the theory that installer.uninstall would
+        // resolve the mismatch when the catalog had picked a non-installed
+        // version on its own. It does not. uninstall runs through the
+        // motions (xvm ops over an already-empty DB, fs::remove_all over
+        // a non-existent dir) and reports success, which loops the user.
+        // The xvm-DB fallback above already anchors resolution to a real
+        // installed version when one exists, so reaching here with
+        // `!installed` means nothing is installed for this target unless the
+        // payloadless-config proof above deliberately admitted its recipe.
+        if (!match->installed && !payloadlessUninstallProven) {
+            log::warn("{}@{} is not installed", displayName, displayVersion);
+            return 0;
+        }
+
+        // Guard against `xlings remove xim:xlings` when xlings has only
+        // one version installed.
+        //
+        // The remove path's "no surviving versions" branch tries to delete
+        // the program's PATH shim — and that shim IS the running xlings.exe.
+        // On Windows this fails with ERROR_SHARING_VIOLATION; on POSIX it
+        // succeeds via unlink(2)'s allow-unlink-of-running-executable
+        // semantics, but leaves a workspace pointer to a version that no
+        // longer exists. Both outcomes are wrong for the same reason: this
+        // command is the wrong tool for the job.
+        //
+        // Multi-version remove (auto-switch to highest remaining) keeps
+        // working unchanged — the no-survivors branch never fires there.
+        // Full uninstall has its own command (`xlings self uninstall`)
+        // which uses the atomic_replace_executable + scheduled-delete
+        // machinery designed precisely for "uninstall the running binary".
+        if (xvm::is_xlings_binary(match->name)) {
+            auto db = Config::versions();
+            const auto* vinfo = xvm::get_vinfo(db, match->name);
+            bool only_version = vinfo
+                && vinfo->versions.size() == 1
+                && vinfo->versions.contains(match->version);
+            if (only_version) {
+                log::error(
+                    "xlings only has one version installed ({}@{}); "
+                    "cannot remove the running binary itself.",
+                    match->canonicalName, match->version);
+                log::println(
+                    "  use `xlings self uninstall` to fully uninstall xlings, or");
+                log::println(
+                    "  install another version first: `xlings install {}@<other>`",
+                    match->canonicalName);
+                return 2;
+            }
+        }
+    }
+
+    // Reverse-dependency guard.
+    //
+    // `xlings remove libxml2` succeeds while llvm depends on it, and the next
+    // `ld.lld` does not start. The error names a soname, so it reads as a
+    // broken llvm install rather than as the consequence of the removal two
+    // commands earlier — and reinstalling llvm does not fix it, because llvm
+    // was never the thing that changed.
+    //
+    // Refuse and name the dependents. `--force` is the escape hatch, because
+    // there are legitimate reasons to break a link deliberately (replacing a
+    // package with another provider, pruning a home you are about to rebuild).
+    //
+    // Only DIRECT dependents are consulted, and that is not a shortcut: a
+    // dependency's libdirs enter a payload's RPATH closure only when it is
+    // named as a direct dep (elfpatch's closure_lib_paths reads the direct
+    // list). A package two hops away does not have this payload on any search
+    // path, so removing it cannot break that package through the loader.
+    // Deliberately NOT conditioned on `match`. The catalog fails to resolve a
+    // target whenever two repos provide the name -- `local:glibc` alongside
+    // `xim:glibc` is an ordinary state in a home that has ever registered a
+    // recipe locally -- and removal proceeds anyway, by bare name, further
+    // down. Gating the guard on a successful resolve made it skip in exactly
+    // the homes most likely to need it, and skip silently: same output as a
+    // clean pass. Take the bare name the way the subos-membership check above
+    // already does, and check regardless.
+    if (!force) {
+        struct Dependent { std::string name; std::string version; };
+        std::vector<Dependent> dependents;
+
+        const auto platform = detect_platform();
+        const auto bare_of = [](const std::string& s) {
+            auto noVer = s.substr(0, s.find('@'));
+            return noVer.substr(noVer.rfind(':') + 1);
+        };
+        const auto targetBare =
+            match ? bare_of(match->canonicalName) : bare_of(target);
+
+        // Current subos only. A package installed in another subos resolves
+        // through that subos's own payloads; removing it here detaches rather
+        // than deletes, which is exactly the case that must NOT be blocked.
+        for (const auto& rec : collect_inventory(catalog, /*allSubos=*/false)) {
+            // By bare name: the same package can be installed under two
+            // namespaces, and neither of them is "not the target".
+            if (bare_of(rec.canonicalName) == targetBare) continue;
+
+            auto depMatch = catalog.resolve_target(
+                rec.canonicalName + "@" + rec.version, platform);
+            if (!depMatch) continue;
+            auto depPkg = catalog.load_package(*depMatch);
+            if (!depPkg) continue;
+
+            // runtime first, falling back to the legacy union `deps` — the
+            // same precedence `info` uses. Build deps are irrelevant here:
+            // they are not on the consumer's runtime search path.
+            const std::vector<std::string>* list = nullptr;
+            if (auto it = depPkg->xpm.runtime_deps.find(platform);
+                it != depPkg->xpm.runtime_deps.end() && !it->second.empty()) {
+                list = &it->second;
+            } else if (auto it2 = depPkg->xpm.deps.find(platform);
+                       it2 != depPkg->xpm.deps.end() && !it2->second.empty()) {
+                list = &it2->second;
+            }
+            if (!list) continue;
+
+            for (const auto& dep : *list) {
+                // "xim:zlib@1.3.1" -> "zlib". Compare bare names: the
+                // namespace a consumer writes is not always the one the
+                // target resolved under, and a version range must not make
+                // a real dependency invisible to this check.
+                if (bare_of(dep) == targetBare) {
+                    dependents.push_back({rec.canonicalName, rec.version});
+                    break;
+                }
+            }
+        }
+
+        if (!dependents.empty()) {
+            log::error("{}@{} is required by {} installed package(s) in subos '{}':",
+                       displayName, displayVersion, dependents.size(), subos);
+            for (const auto& d : dependents) {
+                log::println("    {}@{}", d.name, d.version);
+            }
+            log::println("  remove those first, or re-run with --force to break the link "
+                         "anyway.");
+
+            nlohmann::json blockedPayload;
+            blockedPayload["subos"] = subos;
+            blockedPayload["name"] = displayName;
+            blockedPayload["version"] = displayVersion;
+            auto& arr = blockedPayload["required_by"] = nlohmann::json::array();
+            for (const auto& d : dependents) {
+                arr.push_back({{"name", d.name}, {"version", d.version}});
+            }
+            stream.emit(DataEvent{"remove_blocked", blockedPayload.dump()});
+            return 2;
+        }
+    }
+
+    nlohmann::json planPayload;
+    planPayload["subos"] = subos;
+    planPayload["name"] = displayName;
+    planPayload["version"] = displayVersion;
+    stream.emit(DataEvent{"remove_plan", planPayload.dump()});
+
+    if (!yes) {
+        std::string suffix = displayVersion.empty()
+            ? std::string{}
+            : "@" + displayVersion;
+        PromptEvent confirmReq;
+        confirmReq.id = "confirm_remove";
+        confirmReq.question = std::format(
+            "Remove {}{} from subos '{}' ?", displayName, suffix, subos);
+        confirmReq.options = {"y", "n"};
+        confirmReq.defaultValue = "n";
+        auto answer = stream.prompt(std::move(confirmReq));
+        if (answer != "y") {
+            log::println("cancelled");
+            return 0;
+        }
+    }
+
+    Installer installer(catalog);
+    auto result = installer.uninstall(target);
+    if (!result) {
+        log::error("uninstall failed: {}", result.error());
+        return 1;
+    }
+
+    // Say which of the two things actually happened.
+    //
+    // When another subos still pins this exact version, `remove` detaches the
+    // current subos and deliberately keeps the registration and the payload —
+    // deleting them would break every other subos that is using them. That is
+    // right. Printing "✓ removed" for it was not: the user is told the package
+    // is gone while ~/.xlings/.xlings.json and data/xpkgs/ still hold it in
+    // full, and the reinstall they try next tells them to uninstall first
+    // (#443, and the closed loop in #422).
+    //
+    // The subos are named rather than merely counted because that is the whole
+    // remedy: removing it from each of them in turn lets the last one delete
+    // the payload for real.
+    std::vector<std::string> pinnedBy;
+    if (result->detachedOnly) {
+        pinnedBy = xlings::profile::find_subos_pinning_version(
+            Config::paths().homeDir,
+            result->target.empty() ? displayName : result->target,
+            result->version.empty() ? displayVersion : result->version);
+        std::erase(pinnedBy, subos);
+    }
+
+    nlohmann::json summaryPayload;
+    summaryPayload["subos"] = subos;
+    summaryPayload["name"] = displayName;
+    summaryPayload["version"] = displayVersion;
+    summaryPayload["detached"] = result->detachedOnly;
+    summaryPayload["pinned_by"] = pinnedBy;
+    stream.emit(DataEvent{"remove_summary", summaryPayload.dump()});
+    return 0;
+}
+
+int cmd_search(const std::string& keyword, EventStream& stream) {
+    auto& catalog = get_catalog();
+    if (!catalog.is_loaded()) {
+        log::error("package index not available");
+        return 1;
+    }
+
+    auto results = catalog.search(keyword, detect_platform());
+    if (results.empty()) {
+        log::println("no packages found matching '{}'", keyword);
+        return 0;
+    }
+
+    nlohmann::json itemsJson = nlohmann::json::array();
+    for (auto& match : results) {
+        auto pkg = catalog.load_package(match);
+        std::string desc = pkg ? pkg->description : "";
+        itemsJson.push_back({match.canonicalName, desc});
+    }
+    nlohmann::json searchPayload;
+    searchPayload["title"] = "Search results:";
+    searchPayload["items"] = std::move(itemsJson);
+    searchPayload["numbered"] = true;
+    stream.emit(DataEvent{"styled_list", searchPayload.dump()});
+    return 0;
+}
+
+int cmd_list(const std::string& filter, EventStream& stream, bool all) {
+    auto& catalog = get_catalog();
+    if (!catalog.is_loaded()) {
+        log::error("package index not available");
+        return 1;
+    }
+
+    const auto inventoryFilter = filter.empty()
+        ? std::optional<std::string_view>{}
+        : std::optional<std::string_view>{filter};
+    auto installed = collect_inventory(catalog, all, inventoryFilter);
+
+    if (installed.empty()) {
+        if (all) {
+            log::println("no installed packages found");
+        } else {
+            log::println("no packages installed in current subos");
+            log::println("  hint: `xlings list --all` to see globally-installed packages");
+        }
+        // The empty list is where the nudge matters MOST, not least: a home
+        // whose packages are still registered in the old client's format can
+        // report nothing installed while the payloads sit on disk and the
+        // shims work. Returning early without it would stay silent exactly
+        // when the user has the strongest reason to wonder.
+        xself::print_migration_hint_once(Config::recorded_client_version(),
+                                         Info::VERSION);
+        return 0;
+    }
+
+    // Installed is not the same question as usable.
+    //
+    // `installed[]` and the active selection are two different tables, and a
+    // package can sit in the first without appearing in the second — a group
+    // whose activation was withheld at install time, or a `remove` that took
+    // out the active version and found no coherent replacement. Such a package
+    // has no shim, so its commands are not on PATH, and until now this list
+    // rendered it identically to a working one. The user then meets the
+    // failure through whatever tried to run it, in an error message that names
+    // the missing command and never names xlings.
+    const auto& ws = Config::effective_workspace();
+    const auto& db = Config::versions();
+
+    // Does this ROW's version serve the name, or does some other version?
+    //
+    // A row is a (package, version) pair, so "is the name active" is the wrong
+    // question whenever more than one version is installed: llvm 20.1.7 and
+    // 22.1.8 both register `llvm`, and asking only whether `llvm` is active
+    // leaves the 22.1.8 row looking exactly like the 20.1.7 one that is
+    // actually serving. Compare against the release the active version belongs
+    // to, not against the member version, because a member of a release
+    // carries its own version string (node's `npm` is at `node-24.15.0`).
+    const auto served_by_this_row = [&](std::string_view program,
+                                        const std::string& rowVersion) {
+        const auto it = ws.find(std::string(program));
+        if (it == ws.end() || it->second.empty()) return false;
+        std::string release = it->second;
+        if (const auto* vd = xvm::get_vdata(db, std::string(program), release);
+            vd && vd->bindingGroup) {
+            release = vd->bindingGroup->rootVersion;
+        }
+        return release == rowVersion
+            || xvm::strip_namespace(release) == rowVersion;
+    };
+
+    nlohmann::json listItems = nlohmann::json::array();
+    for (auto& match : installed) {
+        std::string desc = match.description;
+        // Asked of the programs the recipe declares, not of the package name:
+        // the package is `mcpp-short-cmd`, the xvm targets are `madd`,
+        // `mbuild`, … and the package name is never one of them. A package
+        // that declares nothing runnable (a library, a release anchor) has no
+        // active version to lack, so it is never flagged — the same
+        // `package.programs` promise installer.cppm:1847 verifies.
+        //
+        // LIMIT: a recipe that declares no `programs` is never marked, because
+        // nothing records which xvm targets a package version registered —
+        // that mapping exists only in the recipe. Measured: `binutils` and
+        // `gcc` declare theirs and are marked; `llvm` declares none and is
+        // not, though `self doctor` reports it by release. This is a floor,
+        // not full coverage, and the fix is in the recipe.
+        std::string status;
+        if (!match.degradedReason.empty()) {
+            status = "degraded: " + match.degradedReason;
+        } else if (!match.active && !match.programs.empty()
+            && std::ranges::none_of(match.programs,
+                [&](std::string_view program) {
+                    return served_by_this_row(program, match.version);
+                })) {
+            status = "inactive";
+        }
+        // Which subos a row belongs to is the whole reason `--all` exists, and
+        // the inventory has always carried it. Without it the wider listing is
+        // a flat set of names with no way to tell where any of them lives.
+        if (all && !match.suboses.empty()) {
+            std::string where;
+            for (const auto& subos : match.suboses) {
+                if (!where.empty()) where += ", ";
+                where += subos;
+            }
+            status += status.empty() ? "" : " \u00b7 ";
+            status += "in " + where;
+        }
+        listItems.push_back({match.canonicalName + "@" + match.version,
+                             desc, status});
+    }
+    nlohmann::json listPayload;
+    listPayload["title"] = all ? "Installed packages (all subos):"
+                               : "Installed packages (current subos):";
+    listPayload["items"] = std::move(listItems);
+    listPayload["numbered"] = true;
+    stream.emit(DataEvent{"styled_list", listPayload.dump()});
+    log::println("total: {} installed", installed.size());
+    xself::print_migration_hint_once(Config::recorded_client_version(),
+                                     Info::VERSION);
+    return 0;
+}
+
+int cmd_info(const std::string& target, EventStream& stream, bool allVersions) {
+    auto& catalog = get_catalog();
+    if (!catalog.is_loaded()) {
+        log::error("package index not available");
+        return 1;
+    }
+
+    auto match = catalog.resolve_target(target, detect_platform());
+    if (!match) {
+        log::error("{}", match.error());
+        return 1;
+    }
+
+    auto pkg = catalog.load_package(*match);
+    if (!pkg) {
+        log::error("failed to load package: {}", pkg.error());
+        return 1;
+    }
+
+    // Build info fields as JSON
+    auto addField = [](nlohmann::json& arr, const std::string& label,
+                       const std::string& value, bool hl = false) {
+        arr.push_back({{"label", label}, {"value", value}, {"highlight", hl}});
+    };
+
+    nlohmann::json fieldsJson = nlohmann::json::array();
+    addField(fieldsJson, "description", std::string(pkg->description));
+    if (!pkg->homepage.empty())
+        addField(fieldsJson, "homepage", std::string(pkg->homepage));
+    if (!pkg->repo.empty())
+        addField(fieldsJson, "repo", std::string(pkg->repo));
+    if (!pkg->licenses.empty()) {
+        std::string licStr;
+        for (auto& l : pkg->licenses) {
+            if (!licStr.empty()) licStr += " ";
+            licStr += l;
+        }
+        addField(fieldsJson, "licenses", licStr);
+    }
+    if (!pkg->categories.empty()) {
+        std::string catStr;
+        for (auto& c : pkg->categories) {
+            if (!catStr.empty()) catStr += " ";
+            catStr += c;
+        }
+        addField(fieldsJson, "categories", catStr);
+    }
+
+    auto platform = detect_platform();
+    auto platformIt = pkg->xpm.entries.find(platform);
+    if (platformIt != pkg->xpm.entries.end()) {
+        // Concrete versions and aliases used to share one comma-joined
+        // `versions` row, so `latest` and the version it points at appeared
+        // side by side — `latest -> 16.1.0, 16.1.0` reads as the list
+        // repeating itself. They are two different facts; they get two rows.
+        std::vector<std::string> versions;
+        std::vector<std::string> aliases;
+        for (auto& [ver, res] : platformIt->second) {
+            if (version_order::is_internal_key(ver)) continue;
+            if (!res.ref.empty()) {
+                aliases.push_back(ver + " -> " + res.ref);
+                continue;
+            }
+            versions.push_back(ver);
+        }
+        version_order::sort_desc(versions);
+        std::ranges::sort(aliases);
+        auto join_wrapped = [](const std::vector<std::string>& values,
+                               std::size_t limit) {
+            std::string result;
+            const auto count = std::min(values.size(), limit);
+            for (std::size_t i = 0; i < count; ++i) {
+                if (!result.empty()) result += (i % 4 == 0 ? "\n" : ", ");
+                result += values[i];
+            }
+            if (values.size() > count) {
+                result += std::format("\n… {} more (--all-versions)",
+                                      values.size() - count);
+            }
+            return result;
+        };
+        auto verStr = join_wrapped(versions,
+            allVersions ? versions.size() : std::size_t{8});
+        auto aliasStr = join_wrapped(aliases, aliases.size());
+        // `available` rather than `versions`: the panel's second half also
+        // had a row called `versions`, meaning the locally installed ones.
+        if (!verStr.empty())   addField(fieldsJson, "available", verStr);
+        if (!aliasStr.empty()) addField(fieldsJson, "aliases", aliasStr);
+    }
+
+    auto join_deps = [](const std::vector<std::string>& v) {
+        std::string s;
+        for (auto& d : v) {
+            if (!s.empty()) s += " ";
+            s += d;
+        }
+        return s;
+    };
+    auto rtIt = pkg->xpm.runtime_deps.find(platform);
+    auto bdIt = pkg->xpm.build_deps.find(platform);
+    bool hasRuntime = (rtIt != pkg->xpm.runtime_deps.end() && !rtIt->second.empty());
+    bool hasBuild   = (bdIt != pkg->xpm.build_deps.end()   && !bdIt->second.empty());
+    if (hasRuntime || hasBuild) {
+        // Show split form when either is non-empty. The legacy `deps`
+        // field was always the union, so omit it to avoid duplication
+        // when a package only declares the array form (loader fans
+        // legacy → both kinds, so listing all three would triple-print).
+        if (hasRuntime) addField(fieldsJson, "runtime deps", join_deps(rtIt->second));
+        if (hasBuild)   addField(fieldsJson, "build deps",   join_deps(bdIt->second));
+    } else {
+        auto depsIt = pkg->xpm.deps.find(platform);
+        if (depsIt != pkg->xpm.deps.end() && !depsIt->second.empty()) {
+            addField(fieldsJson, "deps", join_deps(depsIt->second));
+        }
+    }
+
+    const auto storeName = package_store_name(match->namespaceName, match->name);
+    const auto storePath = match->storeRoot / storeName;
+    // This package's rows only. Building the whole inventory to answer two
+    // booleans about one package made `info` proportional to the index.
+    const auto rows = collect_package_inventory(
+        catalog, match->canonicalName, /*allSubos=*/true);
+    const auto packageInstalled = !rows.empty();
+    const auto selectedInstalled = std::ranges::any_of(rows,
+        [&](const auto& record) {
+            return record.version == xvm::strip_namespace(match->version);
+        });
+    // Two labels, not three, and neither of them is a bare `installed`: the
+    // detail section below already has a row by that name listing the
+    // versions on disk. `package installed yes` / `selected installed no` /
+    // `installed 0.0.1 (active)` is three labels for overlapping facts, and
+    // the middle one is the only question the summary can answer that the
+    // list below cannot.
+    // An incomplete selected version must not render as `yes`. The payload is
+    // there and the records are not, so every command that reads one source
+    // says installed and every command that reads the other says it is not --
+    // which is how a graphics stack wired to nothing reported success on a
+    // real home. Named here so the panel answers the question that brings
+    // people to it.
+    const auto selectedIncomplete = std::ranges::any_of(rows,
+        [&](const auto& record) {
+            return record.version == xvm::strip_namespace(match->version)
+                && record.incomplete;
+        });
+    addField(fieldsJson, "selected version", match->version);
+    addField(fieldsJson, "selected installed",
+             !packageInstalled ? "no (package not installed)"
+             : selectedIncomplete ? "incomplete (payload present, not registered)"
+             : selectedInstalled ? "yes"
+             : "no (other versions are)");
+    if (selectedIncomplete) {
+        addField(fieldsJson, "repair",
+                 std::format("xlings install {}@{}",
+                             match->canonicalName, match->version));
+    }
+
+    nlohmann::json extraJson = nlohmann::json::array();
+    if (packageInstalled) {
+        auto db = Config::versions();
+        auto ws = Config::effective_workspace();
+        auto target = match->name;
+
+        auto activeVer = xvm::get_active_version(ws, target);
+        if (!activeVer.empty()) {
+            addField(extraJson, "active", activeVer, true);
+        }
+
+        auto allVers = xvm::get_all_versions(db, target);
+        if (!allVers.empty()) {
+            std::string verList;
+            for (auto& v : allVers) {
+                if (!verList.empty()) verList += ", ";
+                verList += v;
+                // Spelled out rather than a bare `*`, which needed a legend
+                // the panel never printed.
+                if (v == activeVer) verList += " (active)";
+            }
+            addField(extraJson, "installed", verList);
+        }
+
+        addField(extraJson, "xpkg path", Config::display_path(storePath));
+
+        auto binDir = Config::global_subos_bin_dir();
+        auto shimPath = binDir / target;
+        if (std::filesystem::exists(shimPath)) {
+            addField(extraJson, "shim", Config::display_path(shimPath));
+        }
+
+        auto* vinfo = xvm::get_vinfo(db, target);
+        if (vinfo && !vinfo->bindings.empty()) {
+            std::string bindStr;
+            for (auto& [bindName, verMap] : vinfo->bindings) {
+                if (!bindStr.empty()) bindStr += ", ";
+                bindStr += bindName;
+                if (!activeVer.empty()) {
+                    auto vit = verMap.find(activeVer);
+                    if (vit != verMap.end()) {
+                        bindStr += " -> " + vit->second;
+                    }
+                }
+            }
+            addField(extraJson, "bindings", bindStr);
+        }
+
+        auto subosRefs = profile::find_subos_referencing(
+            Config::paths().homeDir, target);
+        if (!subosRefs.empty()) {
+            std::string refStr;
+            for (auto& s : subosRefs) {
+                if (!refStr.empty()) refStr += ", ";
+                refStr += s;
+            }
+            addField(extraJson, "subos", refStr);
+        }
+    }
+
+    nlohmann::json infoPayload;
+    infoPayload["title"] = match->canonicalName;
+    infoPayload["fields"] = std::move(fieldsJson);
+    infoPayload["extra_fields"] = std::move(extraJson);
+    stream.emit(DataEvent{"info_panel", infoPayload.dump()});
+    return 0;
+}
+
+int cmd_add_xpkg(const std::string& fileOrUrl, EventStream& stream) {
+    namespace fs = std::filesystem;
+    auto localRepoDir = Config::global_data_dir() / "xim-pkgindex-local";
+    auto pkgsDir = localRepoDir / "pkgs";
+    fs::path luaFile;
+
+    if (fileOrUrl.starts_with("http://") || fileOrUrl.starts_with("https://")) {
+        auto filename = fileOrUrl.substr(fileOrUrl.rfind('/') + 1);
+        if (auto q = filename.find('?'); q != std::string::npos)
+            filename = filename.substr(0, q);
+        // Download to temp location first, then move to letter subdir
+        auto tmpFile = pkgsDir / filename;
+        fs::create_directories(pkgsDir);
+        if (fs::exists(tmpFile)) fs::remove(tmpFile);
+        if (!tinyhttps::fetch_to_file(fileOrUrl, tmpFile)) {
+            log::error("download failed: {}", fileOrUrl);
+            return 1;
+        }
+        luaFile = tmpFile;
+    } else {
+        fs::path src(fileOrUrl);
+        if (!src.is_absolute()) src = fs::current_path() / src;
+        if (!fs::exists(src)) {
+            log::error("file not found: {}", Config::display_path(src));
+            return 1;
+        }
+        luaFile = pkgsDir / src.filename();
+        fs::create_directories(pkgsDir);
+        fs::copy_file(src, luaFile, fs::copy_options::overwrite_existing);
+    }
+
+    // Validate xpkg file
+    auto pkg = xpkg::load_package(luaFile);
+    if (!pkg) {
+        log::error("invalid xpkg: {}", pkg.error());
+        fs::remove(luaFile);
+        return 1;
+    }
+
+    // Move to letter subdirectory (build_index expects pkgs/<letter>/<name>.lua)
+    auto name = pkg->name;
+    if (name.empty()) name = luaFile.stem().string();
+    std::string letter(1, std::tolower(static_cast<unsigned char>(name[0])));
+    auto letterDir = pkgsDir / letter;
+    fs::create_directories(letterDir);
+    auto destFile = letterDir / luaFile.filename();
+    if (destFile != luaFile) {
+        fs::rename(luaFile, destFile);
+        luaFile = destFile;
+    }
+
+    // Give the local index the shared `libs/` too.
+    //
+    // Without this, `--add-xpkg` produces an index holding ONLY `pkgs/`, and a
+    // recipe's top-level `import("xim.pkgindex.sysroot")` resolves against
+    // `<index>/libs/<name>.lua` -- which does not exist -- so libxpkg hands back a
+    // permissive stub whose every call evaporates. Measured 2026-08-08 installing
+    // libXtst this way: `xvm.add` registered the anchor while
+    // `sysroot.declare_libs` produced no lib nodes at all, against a real-index
+    // install of the sibling libXi which produces libXi.so / .so.6 / .so.6.1.0.
+    //
+    // So a local install could not exercise the part of a recipe most likely to be
+    // wrong -- sysroot assets, driver directories, EGL/Vulkan manifests -- and it
+    // reported success. That cost a bug report against `xlings use` (#507) for a
+    // defect that did not exist.
+    //
+    // A symlink rather than a copy: the local index is an OVERLAY on the same
+    // ecosystem, so it should track the primary index's modules rather than
+    // snapshot them -- a stale copy would be its own silent-divergence bug. Falls
+    // back to a directory copy where symlinks need privileges (Windows).
+    {
+        auto primaryLibs = Config::global_data_dir() / "xim-pkgindex" / "libs";
+        auto localLibs = localRepoDir / "libs";
+        std::error_code lec;
+        if (fs::is_directory(primaryLibs, lec) && !fs::exists(localLibs, lec)) {
+            fs::create_directory_symlink(primaryLibs, localLibs, lec);
+            if (lec) {
+                lec.clear();
+                fs::copy(primaryLibs, localLibs,
+                         fs::copy_options::recursive
+                             | fs::copy_options::overwrite_existing, lec);
+            }
+            if (lec) {
+                log::warn("could not provide libs/ to the local index: {} -- "
+                          "`xim.pkgindex.*` calls in this recipe will be silent "
+                          "no-ops", lec.message());
+            }
+        } else if (!fs::is_directory(primaryLibs, lec)) {
+            log::warn("no primary index libs/ at {} -- `xim.pkgindex.*` calls in "
+                      "this recipe will be silent no-ops (run `xlings update`)",
+                      Config::display_path(primaryLibs));
+        }
+    }
+
+    log::println("add xpkg - {}", luaFile.string());
+    // Rebuild index so the new package is immediately available
+    auto& catalog = get_catalog();
+    // get_catalog() already triggers a rebuild on first call,
+    // but the local repo was just modified so we need a fresh rebuild
+    catalog.rebuild();
+    return 0;
+}
+
+int cmd_update(const std::string& target, bool yes, EventStream& stream) {
+    // Sync repos
+    if (!sync_all_repos(true)) {
+        log::error("failed to sync repositories");
+        return 1;
+    }
+
+    // Force rebuild index (writes fresh cache)
+    auto& catalog = get_catalog();
+    auto rebuildResult = catalog.rebuild(true);
+    if (!rebuildResult) {
+        log::error("failed to rebuild catalog: {}", rebuildResult.error());
+        return 1;
+    }
+
+    log::println("index updated");
+
+    if (target.empty()) return 0;
+
+    auto match = catalog.resolve_target(target, detect_platform());
+    if (!match) {
+        log::error("{}", match.error());
+        return 1;
+    }
+
+    auto bareName = match->name;
+    auto latest = match->version;
+    auto currentActive = xvm::get_active_version(
+        Config::effective_workspace(), bareName);
+
+    nlohmann::json planPayload;
+    planPayload["name"]    = match->canonicalName;
+    planPayload["current"] = currentActive;
+    planPayload["latest"]  = latest;
+    stream.emit(DataEvent{"update_plan", planPayload.dump()});
+
+    if (currentActive.empty()) {
+        log::warn("{} is not installed — run: xlings install {}",
+                  match->canonicalName, bareName);
+        return 0;
+    }
+
+    if (currentActive == latest) {
+        log::println("{}@{} is already the latest", match->canonicalName, currentActive);
+        return 0;
+    }
+
+    if (!yes) {
+        PromptEvent confirmReq;
+        confirmReq.id = "confirm_update";
+        confirmReq.question = std::format(
+            "Upgrade {} from {} to {} ?",
+            match->canonicalName, currentActive, latest);
+        confirmReq.options = {"y", "n"};
+        confirmReq.defaultValue = "y";
+        auto answer = stream.prompt(std::move(confirmReq));
+        if (answer != "y") {
+            log::println("cancelled");
+            return 0;
+        }
+    }
+
+    // Install the new version. cmd_install handles dependency resolution,
+    // download, and hooks. We pass yes=true because the user already
+    // confirmed the upgrade above (and hook-driven sub-installs should
+    // never re-prompt regardless). useAfterInstall=true because update by
+    // definition moves the active pointer forward to the new version.
+    std::vector<std::string> installTargets = { bareName + "@" + latest };
+    auto rc = cmd_install(installTargets, /*yes=*/true, /*noDeps=*/false, stream,
+                          /*forceGlobal=*/false, /*cancel=*/nullptr,
+                          /*dryRun=*/false, /*useAfterInstall=*/true);
+    if (rc != 0) return rc;
+
+    nlohmann::json summaryPayload;
+    summaryPayload["name"] = match->canonicalName;
+    summaryPayload["from"] = currentActive;
+    summaryPayload["to"]   = latest;
+    stream.emit(DataEvent{"update_summary", summaryPayload.dump()});
+
+    log::println("upgraded {}: {} -> {}", match->canonicalName, currentActive, latest);
+    log::println("  old version retained — remove with: xlings remove {}@{}",
+                 bareName, currentActive);
+    return 0;
+}
+
+}
diff --git a/src/core/xim/commands.cppm b/src/core/xim/commands.cppm
index 91b60a59..f29bb881 100644
--- a/src/core/xim/commands.cppm
+++ b/src/core/xim/commands.cppm
@@ -12,22 +12,13 @@ import xlings.core.xim.repo;
 import xlings.core.xim.resolver;
 import xlings.core.xim.downloader;
 import xlings.core.xim.installer;
-import xlings.core.log;
 import xlings.core.config;
-import xlings.core.profile;
 import xlings.runtime;
-import xlings.libs.json;
-import xlings.core.i18n;
 import xlings.platform;
 import xlings.platform.target;
 import xlings.libs.tinyhttps;
 import xlings.core.xvm.db;
-import xlings.core.xvm.lock;
-import xlings.core.xvm.commands;
-import xlings.core.xvm.shim;
-import xlings.core.profile;
 import xlings.runtime.cancellation;
-import xlings.core.version_order;
 // Leaf module (std + log + platform only), so importing it here does not
 // recreate the xim.commands <-> xself cycle that keeps `self update` shelling
 // out to a subprocess.
@@ -40,62 +31,9 @@ export namespace xlings::xim {
 enum class CatalogAccess { LocalOnly, InstallReady };
 
 // Shared IndexManager instance (lazy-initialized)
-PackageCatalog& get_catalog(CatalogAccess access = CatalogAccess::LocalOnly) {
-    static PackageCatalog mgr;
-    static bool initialized = false;
-    static bool installReadyChecked = false;
-    // No rebuild yet on this call. A default-constructed expected<void,...> is
-    // a SUCCESS value, so leaving it as "the result" would make "never probed"
-    // and "probed and fine" the same thing -- and the self-heal below only ever
-    // fires on a failure it can see.
-    std::optional<std::expected<void, std::string>> result;
-    if (!initialized) {
-        result = mgr.rebuild();
-        initialized = true;
-    }
+PackageCatalog& get_catalog(CatalogAccess access = CatalogAccess::LocalOnly);
 
-    if (access == CatalogAccess::InstallReady && !installReadyChecked) {
-        // A LocalOnly caller may have initialized the singleton before an
-        // install reaches it. Rebuild once here so this access request has a
-        // current error to report before attempting the repair sync.
-        if (!result && !mgr.is_loaded()) result = mgr.rebuild();
-
-        // #366: on a fresh machine the main index rebuilds fine, but the
-        // default sub-indexes were never synced — their pkgs/ dirs don't
-        // exist, so repo_specs_() skips them and rebuild() still SUCCEEDS.
-        // The old code only synced in the failure branch, so scode/awesome/d2x
-        // stayed absent and `install scode:...` failed with "not found" until
-        // the user ran `xlings update`. Force a one-time sync when the
-        // sub-index marker JSON is missing (cheap: skipped on every later run).
-        bool subIndexesNeverSynced = !sub_indexes_initialized();
-        const bool buildFailed = result.has_value() && !result->has_value();
-        if (buildFailed || subIndexesNeverSynced) {
-            if (buildFailed) {
-                // Self-heal: a broken/absent index tree (interrupted fetch on
-                // an older xlings, wiped cache) is repairable — resync and
-                // rebuild once before surfacing an error the user would have
-                // to fix by running `xlings update` themselves.
-                log::warn("catalog build failed ({}); resyncing indexes...",
-                          result->error());
-            } else {
-                log::info("initializing package sub-indexes (first run)...");
-            }
-            if (sync_all_repos(true)) {
-                result = mgr.rebuild(true);
-            }
-            if (result.has_value() && !result->has_value()) {
-                log::error("failed to build catalog: {}", result->error());
-                log::info("try running: xlings update");
-            }
-        }
-        installReadyChecked = true;
-    }
-    return mgr;
-}
-
-std::string detect_platform() {
-    return std::string(xlings::platform::build_os());
-}
+std::string detect_platform();
 
 // Forward declaration for deferred install request processing
 int cmd_remove(const std::string& target, bool yes, EventStream& stream,
@@ -105,16 +43,7 @@ int cmd_remove(const std::string& target, bool yes, EventStream& stream,
 // UX): returns true at most once per cooldown window so a tight loop of
 // `install <genuinely-absent-pkg>` can't spin repeated full resyncs. Combined
 // with a per-invocation guard, a single `install` refreshes at most once.
-bool index_refresh_cooldown_elapsed() {
-    using namespace std::chrono;
-    static steady_clock::time_point last{};
-    static bool primed = false;
-    auto now = steady_clock::now();
-    if (primed && now - last < seconds(60)) return false;
-    last = now;
-    primed = true;
-    return true;
-}
+bool index_refresh_cooldown_elapsed();
 
 // === install command ===
 //
@@ -135,533 +64,12 @@ bool index_refresh_cooldown_elapsed() {
 // against what was intended -- those two have differed, and the difference
 // is what this whole area exists to prevent.
 int cmd_why(const std::string& target, const std::string& dep,
-            EventStream& stream) {
-    namespace fs = std::filesystem;
-    const auto store = Config::paths().dataDir / "xpkgs";
-    std::error_code ec;
-    if (!fs::is_directory(store, ec)) {
-        stream.emit(ErrorEvent{.code = ErrorCode::InvalidInput,
-                               .message = "no packages are installed",
-                               .recoverable = false});
-        return 1;
-    }
-
-    auto bare = target;
-    if (auto at = bare.find('@'); at != std::string::npos) bare.resize(at);
-    if (auto colon = bare.find(':'); colon != std::string::npos)
-        bare = bare.substr(colon + 1);
-
-    // Every installed version of the named package: a home can hold more
-    // than one, and "which one did you mean" is better answered by showing
-    // both than by picking.
-    std::vector<fs::path> records;
-    for (const auto& pkgDir : platform::dir_entries(store)) {
-        if (!pkgDir.is_directory()) continue;
-        const auto storeName = pkgDir.path().filename().string();
-        // `<ns>-x-<name>`; match the name half.
-        auto marker = storeName.find("-x-");
-        if (marker == std::string::npos) continue;
-        if (storeName.substr(marker + 3) != bare) continue;
-        for (const auto& verDir : platform::dir_entries(pkgDir.path())) {
-            auto rec = verDir.path() / ".xlings-resolution.json";
-            if (fs::is_regular_file(rec, ec)) records.push_back(rec);
-        }
-    }
-    if (records.empty()) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = std::format("no resolution record for '{}'", bare),
-            .recoverable = false,
-            .hint = "records are written at install time; reinstall the "
-                    "package to produce one"});
-        return 1;
-    }
-
-    for (const auto& recPath : records) {
-        auto content = platform::read_file_to_string(recPath.string());
-        auto json = nlohmann::json::parse(content, nullptr, false);
-        if (json.is_discarded()) continue;
-        std::println("{}", json.value("package", std::string{}));
-        for (const auto& d : json.value("deps", nlohmann::json::array())) {
-            const auto spec = d.value("spec", std::string{});
-            if (!dep.empty() && spec.find(dep) == std::string::npos) continue;
-            std::println("  {}", spec);
-            std::println("    resolved  {}   (source: {})",
-                         d.value("version", std::string{}),
-                         d.value("source", std::string{}));
-            std::println("    payload   {}",
-                         Config::display_path(d.value("install_dir", std::string{})));
-            for (const auto& l : d.value("libdirs", nlohmann::json::array())) {
-                std::println("    libdir    {}",
-                             Config::display_path(l.get<std::string>()));
-            }
-        }
-    }
-    return 0;
-}
+            EventStream& stream);
 
 int cmd_install(std::span<const std::string> targets, bool yes, bool noDeps,
                 EventStream& stream, bool forceGlobal = false,
                 CancellationToken* cancel = nullptr, bool dryRun = false,
-                bool useAfterInstall = false) {
-    // Serialize against any other xlings mutating this home, then re-read
-    // state under the lock: Config loaded it at process start, outside the
-    // lock, so acting on that snapshot is how two commands lose each other's
-    // work. See xvm/lock.cppm.
-    auto stateLock = xvm::acquire_state_lock(Config::paths().homeDir);
-    if (!stateLock) {
-        log::error("{}", stateLock.error());
-        return 1;
-    }
-
-    // An emulated build installs emulated packages -- correctly, since they
-    // have to match this process's ABI, and slowly, since every one of them
-    // then runs under Rosetta / WOW64 / qemu. The user is the only one who can
-    // decide to switch, and cannot decide if nobody says it. Said at install
-    // time because that is when the cost is being incurred.
-    if (platform::is_emulated()) {
-        log::warn("this xlings is a {} build running on {} hardware; packages "
-                  "will match the build, not the machine. A native {} release "
-                  "avoids the emulation.",
-                  platform::build().arch, platform::host().arch,
-                  platform::host().str());
-    }
-    Config::reload_state();
-
-    auto& catalog = get_catalog(CatalogAccess::InstallReady);
-    if (!catalog.is_loaded()) {
-        log::info("package index not available, updating...");
-        sync_all_repos(true);
-        auto rebuildResult = catalog.rebuild();
-        if (!rebuildResult || !catalog.is_loaded()) {
-            // #374: emit a structured error on the EventStream instead of a
-            // bare log::error (which interface mode's tui_mode suppresses) so
-            // programmatic consumers see WHY the exit is non-zero rather than
-            // a silent {"exitCode":1,"kind":"result"} with an empty stream.
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::NotFound,
-                .message = std::string("package index not available")
-                    + (rebuildResult ? std::string{} : ": " + rebuildResult.error()),
-                .recoverable = true,
-                .hint = "run `xlings update`, or check index_repos in .xlings.json",
-            });
-            return 1;
-        }
-    }
-
-    // #374: surface any index repos skipped during the best-effort catalog
-    // build so a degraded multi-repo config is visible to interface consumers
-    // (mcpp) instead of silently ignored. Non-fatal — healthy repos still
-    // resolve; this only makes the skip observable on the wire.
-    for (auto& w : catalog.load_warnings()) {
-        stream.emit(LogEvent{LogLevel::warn,
-            "index repo '" + w.name + "' skipped ("
-            + (w.scope == PackageScope::Project ? "project" : "global")
-            + " scope): " + w.error});
-    }
-
-    auto platform = detect_platform();
-    std::vector<std::string> targetVec(targets.begin(), targets.end());
-    std::vector<PackageMatch> requestedMatches;
-    // C2 (#366 UX): allow at most one on-demand index refresh per install call.
-    bool refreshedForMissing = false;
-
-    // #374: for structured not-found errors, name the repos we searched so
-    // interface consumers can see the resolution scope (the issue asks to
-    // identify "which repositories were searched").
-    auto searched_repos_ = [&]() {
-        std::string s;
-        auto add = [&](const std::string& n) { if (!s.empty()) s += ", "; s += n; };
-        for (auto& r : Config::project_index_repos()) add(r.name);
-        for (auto& r : Config::global_index_repos()) add(r.name);
-        return s;
-    };
-
-    // Idempotency: `install` is NOT supposed to be a silent upgrader.
-    // If the package already has a version active in the current sub-OS
-    // that satisfies the user's request — bare name (no @ver) accepts
-    // anything, `name@<prefix>` accepts any active version starting with
-    // the prefix — pin the resolution to that exact version. The existing
-    // "all packages already installed" fast path takes it from there.
-    // For deliberate upgrades, users should run `xlings update <pkg>`.
-    // What is active in the workspace this install is about to write into.
-    // Top-level targets and expanded dependencies both resolve through it, so
-    // "already satisfied" means the same thing on both paths -- it used to be
-    // applied here only, with a `starts_with` test of its own, which made
-    // `@1.1` match an active `1.10` and left every dependency resolving to the
-    // index's newest version.
-    auto active_version_of_ = [](const std::string& name) {
-        return xvm::get_active_version(Config::effective_workspace(), name);
-    };
-    auto pin_to_active_if_satisfies_ = [&](const std::string& t) -> std::string {
-        return pin_target_to_active(t, active_version_of_);
-    };
-
-    for (auto& target : targetVec) {
-        auto pinned = pin_to_active_if_satisfies_(target);
-        auto match = catalog.resolve_target(pinned, platform);
-        if (!match && pinned != target) {
-            // Active version no longer in the catalog (xpm declaration changed
-            // since install) — fall back to the original target so the user
-            // still gets a useful resolve / error / fuzzy-match path.
-            match = catalog.resolve_target(target, platform);
-        }
-        // C2 (#366 UX): a target absent from the current catalog may simply be
-        // newer than the local index (package/version just published). Refresh
-        // the index once and retry before giving up, so `install <fresh-pkg>`
-        // — including explicit-namespace targets like `scode:linux-headers` —
-        // works without a manual `xlings update`. Debounced by a per-call guard
-        // + a process-wide cooldown; ambiguous errors are not "missing".
-        if (!match && !refreshedForMissing
-                && !match.error().contains("ambiguous")
-                && index_refresh_cooldown_elapsed()) {
-            refreshedForMissing = true;
-            log::info("'{}' not in current index; refreshing index...", target);
-            if (sync_all_repos(true)) {
-                catalog.rebuild(true);
-                match = catalog.resolve_target(pinned, platform);
-                if (!match && pinned != target) {
-                    match = catalog.resolve_target(target, platform);
-                }
-            }
-        }
-        if (!match) {
-            // Ambiguous matches: show error directly, don't fall through to fuzzy
-            if (match.error().contains("ambiguous")) {
-                // #374: structured error on the wire (was a swallowed log::error)
-                stream.emit(ErrorEvent{
-                    .code = ErrorCode::InvalidInput,
-                    .message = match.error(),
-                    .recoverable = true,
-                    .hint = "install a specific candidate with its full namespace:name@version",
-                });
-                return 1;
-            }
-            // Explicit namespace (e.g. scode:linux-headers) -- don't fuzzy-match
-            // across other namespaces, which can cause infinite recursion
-            if (target.find(':') != std::string::npos) {
-                // #374: structured error on the wire (was a swallowed log::error)
-                stream.emit(ErrorEvent{
-                    .code = ErrorCode::NotFound,
-                    .message = match.error(),
-                    .recoverable = true,
-                    .hint = "searched repos: [" + searched_repos_()
-                        + "]; run `xlings update` if the package was just published",
-                });
-                return 1;
-            }
-            // Try fuzzy search for suggestions
-            auto fuzzy = catalog.search(target, platform);
-            if (fuzzy.empty()) {
-                // #374: structured error on the wire (was a swallowed log::error)
-                stream.emit(ErrorEvent{
-                    .code = ErrorCode::NotFound,
-                    .message = match.error(),
-                    .recoverable = true,
-                    .hint = "searched repos: [" + searched_repos_()
-                        + "]; run `xlings update` if the package was just published",
-                });
-                return 1;
-            }
-            if (fuzzy.size() > 5) fuzzy.resize(5);
-
-            if (fuzzy.size() == 1) {
-                // Single fuzzy match -- use it directly
-                match = fuzzy.front();
-            } else if (yes) {
-                // -y mode: auto-select first match
-                match = fuzzy.front();
-            } else {
-                // Interactive selection via EventStream prompt
-                std::vector<std::string> options;
-                for (auto& f : fuzzy) {
-                    options.push_back(f.canonicalName + "@" + f.version);
-                }
-                PromptEvent req;
-                req.id = "select_package";
-                req.question = "Multiple matches found. Select a package:";
-                req.options = std::move(options);
-                auto chosen = stream.prompt(std::move(req));
-                if (chosen.empty()) {
-                    log::println("cancelled");
-                    return 0;
-                }
-                // Find matching fuzzy result
-                for (auto& f : fuzzy) {
-                    if ((f.canonicalName + "@" + f.version) == chosen) {
-                        match = f;
-                        break;
-                    }
-                }
-                if (!match) {
-                    log::println("cancelled");
-                    return 0;
-                }
-            }
-        }
-        // Update target to the canonical "<ns:name>@<version>" form so that
-        // the downstream dependency resolver (which calls resolve_target
-        // again on each item in targetVec) lands on this exact version.
-        // Without this, pin_to_active_if_satisfies_ above is silently undone
-        // when the resolver picks the catalog's highest-declared version for
-        // bare-name targets.
-        target = match->canonicalName;
-        if (!match->version.empty()) {
-            target += "@" + match->version;
-        }
-        requestedMatches.push_back(*match);
-    }
-
-    // Resolve dependencies
-    auto planResult = resolve(catalog, targetVec, platform, active_version_of_);
-    if (!planResult) {
-        // #374: structured error on the wire (was a swallowed log::error)
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = "dependency resolution failed: " + planResult.error(),
-            .recoverable = true,
-        });
-        return 1;
-    }
-
-    auto& plan = *planResult;
-    if (plan.has_errors()) {
-        // #374: structured errors on the wire (were swallowed log::error)
-        for (auto& err : plan.errors) {
-            stream.emit(ErrorEvent{
-                .code = ErrorCode::InvalidInput,
-                .message = err,
-                .recoverable = true,
-            });
-        }
-        return 1;
-    }
-
-    // -g: register versions/workspace in global scope so tools work outside project dir
-    if (forceGlobal) {
-        bool hasProjectOnly = false;
-        for (auto& node : plan.nodes) {
-            if (node.scope == PackageScope::Project) {
-                log::warn("-g ignored for '{}': only exists in project-local index", node.name);
-                hasProjectOnly = true;
-            }
-        }
-        if (hasProjectOnly) {
-            log::warn("-g disabled: cannot globally register project-only packages (uninstall would fail)");
-        } else {
-            Config::set_force_global_scope(true);
-        }
-    }
-
-    auto plan_key = [](const PackageMatch& match) {
-        return match.canonicalName + "@" + match.version;
-    };
-
-    std::unordered_map<std::string, bool> requestedAlreadyInstalled;
-    for (auto& match : requestedMatches) {
-        requestedAlreadyInstalled[plan_key(match)] =
-            match.installed && !match.payloadForeign;
-    }
-
-    auto activate_requested_targets = [&]() {
-        auto db = Config::versions();
-        for (auto& match : requestedMatches) {
-            auto active = xvm::get_active_version(Config::effective_workspace(), match.name);
-            // Only switch when nothing is active yet for this program OR the
-            // user passed --use to force activation. Otherwise preserve the
-            // existing active version. Pairs with the symmetric guard in
-            // installer.cppm process_xvm_operations_.
-            if ((active.empty() || useAfterInstall) &&
-                xvm::has_version(db, match.name, match.version)) {
-                auto useRet = xvm::cmd_use(match.name, match.version, stream);
-                if (useRet != 0) {
-                    log::warn("failed to activate {}@{} in current subos",
-                              match.name, match.version);
-                }
-            } else if (!active.empty() && active != match.version) {
-                // Declining to switch is a decision, and it used to be a
-                // silent one: `install llvm@20.1.7` printed nothing but
-                // success while `clang++` stayed on 22.1.8, so the version
-                // the user asked for was installed and unreachable.
-                log::println(
-                    "{}@{} installed, but '{}' still resolves to {} "
-                    "— `xlings use {} {}` to switch",
-                    match.canonicalName, match.version, match.name, active,
-                    match.name, match.version);
-            }
-            log::debug("version: {}", match.version);
-            if (requestedAlreadyInstalled[plan_key(match)]) {
-                log::debug("{}@{} already installed", match.canonicalName, match.version);
-            } else {
-                log::debug("{}@{} installed", match.canonicalName, match.version);
-            }
-        }
-    };
-
-    auto pending = plan.pending_count();
-    auto allAlreadyInstalled = (pending == 0);
-    if (allAlreadyInstalled) {
-        for (auto& m : requestedMatches) {
-            log::println("{}@{} is already installed", m.canonicalName, m.version);
-        }
-    }
-
-    // Show install plan with themed UI
-    if (!allAlreadyInstalled) {
-        nlohmann::json planPackages = nlohmann::json::array();
-        for (auto& node : plan.nodes) {
-            if (!node.alreadyInstalled) {
-                std::string nameVer = node.canonicalName;
-                if (!node.version.empty()) nameVer += "@" + node.version;
-                planPackages.push_back({nameVer, ""});
-            }
-        }
-        nlohmann::json planPayload;
-        planPayload["packages"] = std::move(planPackages);
-        stream.emit(DataEvent{"install_plan", planPayload.dump()});
-    }
-
-    // dry-run stops here — clients (plan_install) only want the plan.
-    if (dryRun) {
-        return 0;
-    }
-
-    // Confirm via EventStream prompt
-    if (!allAlreadyInstalled && !yes) {
-        PromptEvent confirmReq;
-        confirmReq.id = "confirm_install";
-        confirmReq.question = "Proceed with installation?";
-        confirmReq.options = {"y", "n"};
-        confirmReq.defaultValue = "y";
-        auto answer = stream.prompt(std::move(confirmReq));
-        if (answer != "y") {
-            log::println("cancelled");
-            return 0;
-        }
-    }
-
-    // Execute install
-    Installer installer(catalog);
-    DownloaderConfig dlConfig;
-    auto mirror = Config::mirror();
-    if (!mirror.empty()) dlConfig.preferredMirror = mirror;
-
-    // Download progress renderer: emit via EventStream so consumers can render.
-    // CLI consumer renders ftxui progress bars; agent TUI shows summary text.
-    DownloadProgressRenderer dlRenderer = [&stream](std::span<const TaskProgress> state,
-                  std::size_t nameWidth, double elapsedSec, bool sizesReady,
-                  int prevLines) -> int {
-        nlohmann::json files = nlohmann::json::array();
-        for (auto& p : state) {
-            files.push_back({
-                {"name", p.name},
-                {"totalBytes", p.totalBytes},
-                {"downloadedBytes", p.downloadedBytes},
-                {"started", p.started},
-                {"finished", p.finished},
-                {"success", p.success}
-            });
-        }
-        nlohmann::json payload;
-        payload["files"] = std::move(files);
-        payload["nameWidth"] = nameWidth;
-        payload["elapsedSec"] = elapsedSec;
-        payload["sizesReady"] = sizesReady;
-        payload["prevLines"] = prevLines;
-        stream.emit(DataEvent{"download_progress", payload.dump()});
-        return static_cast<int>(state.size()) + 2;
-    };
-
-    int successCount = 0;
-    int failedCount = 0;
-
-    auto result = installer.execute(plan, dlConfig,
-        [&, cancel](const InstallStatus& status) {
-            switch (status.phase) {
-                case InstallPhase::Downloading:
-                    break;  // TUI progress bar handles this
-                case InstallPhase::Installing:
-                    log::debug("[{}] installing...", status.name);
-                    break;
-                case InstallPhase::Configuring:
-                    log::debug("[{}] configuring...", status.name);
-                    break;
-                case InstallPhase::Done:
-                    log::debug("[{}] done", status.name);
-                    ++successCount;
-                    break;
-                case InstallPhase::Failed:
-                    // #374: structured per-package failure on the wire so
-                    // interface consumers see WHICH package failed (was a
-                    // swallowed log::error). failedCount still drives exitCode.
-                    stream.emit(ErrorEvent{
-                        .code = ErrorCode::Internal,
-                        .message = "[" + status.name + "] failed: " + status.message,
-                        .recoverable = true,
-                    });
-                    ++failedCount;
-                    break;
-                default:
-                    break;
-            }
-        },
-        // Process deferred pkgmanager.install()/remove() requests synchronously
-        // between install and config hooks so config can access sub-dependencies
-        [forceGlobal, useAfterInstall, &stream](const std::vector<mcpplibs::xpkg::InstallRequest>& reqs) {
-            for (auto& req : reqs) {
-                if (req.op == "install") {
-                    log::debug("installing sub-dependency: {}", req.target);
-                    std::vector<std::string> subTargets = { req.target };
-                    cmd_install(subTargets, /*yes=*/true, /*noDeps=*/false, stream,
-                                forceGlobal, /*cancel=*/nullptr, /*dryRun=*/false,
-                                useAfterInstall);
-                } else if (req.op == "remove") {
-                    log::debug("removing sub-dependency: {}", req.target);
-                    // force: an xpkg hook asking for a removal has already
-                    // reasoned about what it is replacing. Letting the
-                    // reverse-dep guard veto it would break recipes that
-                    // legitimately swap one provider for another mid-install.
-                    cmd_remove(req.target, /*yes=*/true, stream, /*force=*/true);
-                }
-            }
-        },
-        dlRenderer, cancel, useAfterInstall);
-
-    if (!result) {
-        // #374: structured error on the wire (was a swallowed log::error)
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::Internal,
-            .message = "install failed: " + result.error(),
-            .recoverable = false,
-        });
-        return 1;
-    }
-
-    activate_requested_targets();
-    if (!allAlreadyInstalled) {
-        nlohmann::json summaryPayload;
-        summaryPayload["success"] = successCount;
-        summaryPayload["failed"] = failedCount;
-        stream.emit(DataEvent{"install_summary", summaryPayload.dump()});
-
-        // If this install ran via `sudo`, the downloaded payloads, version DB
-        // and shims were written root-owned into the user's home. Hand the
-        // home back to the invoking user so a later non-sudo `xlings install`
-        // isn't locked out by EACCES. No-op for pure root / non-root installs
-        // (lchown is metadata-only, so even large payload trees are cheap).
-        platform::chown_to_invoker(Config::paths().homeDir);
-    }
-    // Per-package failures (download / extract / hook) are surfaced via
-    // InstallPhase::Failed callbacks and accumulate in `failedCount`;
-    // installer.execute itself only returns unexpected on cancel or
-    // plan-level errors. Without checking failedCount here, `xlings
-    // install` and `interface install_packages` would report exitCode=0
-    // even when individual packages failed to install — see
-    // .agents/docs/2026-05-22-cmd-install-silent-failure-analysis.md
-    xself::print_migration_hint_once(Config::recorded_client_version(),
-                                     Info::VERSION);
-    return failedCount > 0 ? 1 : 0;
-}
+                bool useAfterInstall = false);
 
 // === remove command ===
 //
@@ -673,566 +81,13 @@ std::expected<bool, std::string>
 selected_payloadless_config_has_uninstall_(
         PackageCatalog& catalog,
         const PackageMatch& match,
-        std::string_view platform) {
-    auto package = catalog.load_package(match);
-    if (!package) return std::unexpected(package.error());
-    if (package->type != xpkg::PackageType::Config) return false;
-
-    const auto hasDeps = [&](const auto& deps) {
-        auto it = deps.find(std::string(platform));
-        return it != deps.end() && !it->second.empty();
-    };
-    if (hasDeps(package->xpm.deps)
-        || hasDeps(package->xpm.runtime_deps)
-        || hasDeps(package->xpm.build_deps)) {
-        return false;
-    }
-
-    const auto storeRoot = match.storeRoot.empty()
-        ? Config::paths().dataDir / "xpkgs"
-        : match.storeRoot;
-    const auto installDir = storeRoot
-        / package_store_name(match.namespaceName, match.name)
-        / match.version;
-    const auto snapshot = installDir / ".xpkg.lua";
-    std::error_code ec;
-    const auto recipe = std::filesystem::is_regular_file(snapshot, ec)
-        ? snapshot
-        : match.pkgFile;
-    ec.clear();
-    if (!std::filesystem::is_regular_file(recipe, ec)) {
-        return std::unexpected(std::format(
-            "uninstall recipe is not a local file: {}", recipe.string()));
-    }
-
-    auto executor = xpkg::create_executor(recipe);
-    if (!executor) return std::unexpected(executor.error());
-    return executor->has_hook(xpkg::HookType::Uninstall);
-}
+        std::string_view platform);
 
 int cmd_remove(const std::string& target, bool yes, EventStream& stream,
-               bool force) {
-    // Serialize against any other xlings mutating this home, then re-read
-    // state under the lock: Config loaded it at process start, outside the
-    // lock, so acting on that snapshot is how two commands lose each other's
-    // work. See xvm/lock.cppm.
-    auto stateLock = xvm::acquire_state_lock(Config::paths().homeDir);
-    if (!stateLock) {
-        log::error("{}", stateLock.error());
-        return 1;
-    }
-
-    // An emulated build installs emulated packages -- correctly, since they
-    // have to match this process's ABI, and slowly, since every one of them
-    // then runs under Rosetta / WOW64 / qemu. The user is the only one who can
-    // decide to switch, and cannot decide if nobody says it. Said at install
-    // time because that is when the cost is being incurred.
-    if (platform::is_emulated()) {
-        log::warn("this xlings is a {} build running on {} hardware; packages "
-                  "will match the build, not the machine. A native {} release "
-                  "avoids the emulation.",
-                  platform::build().arch, platform::host().arch,
-                  platform::host().str());
-    }
-    Config::reload_state();
-
-    auto& catalog = get_catalog();
-    if (!catalog.is_loaded()) {
-        log::error("package index not available");
-        return 1;
-    }
-
-    // Resolve up-front so the prompt and summary can show the canonical
-    // name + version + active subos. When the user did not pin a version,
-    // prefer the active one — catalog.resolve_target's default is the
-    // highest *declared* version, which may not be installed.
-    std::string displayName = target;
-    std::string displayVersion;
-    std::string subos = Config::paths().activeSubos;
-    bool payloadlessUninstallProven = false;
-
-    // 0.4.19+: subos-membership guard.
-    //
-    // Pre-fix: in a fresh (or pruned) subos, `xlings remove gcc` would
-    // reach the catalog, resolve to whatever version the recipe declared
-    // as "default", attempt detach (no-op since gcc is not in this
-    // subos's workspace), then succeed via the cross-subos refcount
-    // path because gcc IS installed in some OTHER subos. Net effect:
-    // confusing "✓ removed (subos: tmp)" output for a version the user
-    // never had. Refuse early and tell them where the package actually
-    // lives.
-    {
-        auto stripVer = [](const std::string& s) {
-            auto at = s.find('@');
-            return (at == std::string::npos) ? s : s.substr(0, at);
-        };
-        auto bareWithoutVer = stripVer(target);
-        auto bareName = bareWithoutVer.substr(bareWithoutVer.rfind(':') + 1);
-
-        const auto& ws  = Config::workspace();
-        const auto& wsi = Config::workspace_installed();
-        bool in_active    = ws.contains(bareName) && !ws.at(bareName).empty();
-        bool in_installed = wsi.contains(bareName) && !wsi.at(bareName).empty();
-
-        if (!in_active && !in_installed) {
-            // Which subos(es) DO have this package? Computed first, because it
-            // is what separates the two cases below.
-            auto referencing = xlings::profile::find_subos_referencing(
-                Config::paths().homeDir, bareName);
-            std::erase(referencing, subos);
-
-            if (!referencing.empty()) {
-                // The case this guard was written for (0.4.19+): the package
-                // lives in ANOTHER subos. Removing it here detaches rather
-                // than removes, and the cross-subos refcount path would then
-                // report "✓ removed (subos: tmp)" for a version the user never
-                // had. Refuse, and say where it actually lives.
-                log::warn("xlings: '{}' is not installed in current subos '{}'",
-                          bareName, subos);
-                std::string list;
-                for (auto& n : referencing) {
-                    if (!list.empty()) list += ", ";
-                    list += n;
-                }
-                log::warn("  installed in subos: {}", list);
-                log::warn("  hint: `xlings subos use {}` then `xlings remove {}`",
-                          referencing.front(), bareName);
-                return 0;
-            }
-
-            // No subos claims it. Ask the disk before concluding it is absent
-            // -- the two workspace tables are bookkeeping, and a payload can
-            // outlive them (openxlings/xlings#511).
-            //
-            // Answering "not installed" here while a payload sits in xpkgs/ is
-            // not a harmless no-op: `install` treats a present payload
-            // directory as already installed and skips the install AND its
-            // config() hook. So `install -> remove (success) -> install` leaves
-            // a package whose config() never runs again. That is the same
-            // cascade that produced the aarch64 failure in #509, where an
-            // unconfigured gcc payload emitted binaries carrying the packaging
-            // machine's PT_INTERP and the error named the wrong file entirely.
-            bool payloadOnDisk = false;
-            {
-                namespace fs = std::filesystem;
-                const auto store = Config::paths().dataDir / "xpkgs";
-                std::error_code pec;
-                if (fs::is_directory(store, pec)) {
-                    for (const auto& pkgDir : platform::dir_entries(store)) {
-                        if (!pkgDir.is_directory()) continue;
-                        const auto storeName = pkgDir.path().filename().string();
-                        auto marker = storeName.find("-x-");
-                        if (marker == std::string::npos) continue;
-                        if (storeName.substr(marker + 3) != bareName) continue;
-                        for (const auto& verDir :
-                             platform::dir_entries(pkgDir.path())) {
-                            if (!verDir.is_directory()) continue;
-                            if (payload_has_content(verDir.path())) {
-                                payloadOnDisk = true;
-                                break;
-                            }
-                        }
-                        if (payloadOnDisk) break;
-                    }
-                }
-            }
-
-            if (!payloadOnDisk) {
-                // Nothing here is installed. The only question left is whether
-                // this coordinate is a payloadless config whose uninstall hook
-                // still has work to do -- and being unable to answer it is not
-                // the same as answering "yes".
-                //
-                // What an unanswerable question MEANS depends on how the user
-                // asked it, and these are two different questions:
-                //
-                //   `remove pkg`        -- "make sure pkg is gone". Scripts
-                //       re-run this defensively, and a package whose recipe has
-                //       left the index is as gone as it gets. Warn, exit 0.
-                //       That is the convention the block below states.
-                //   `remove pkg@9.9.9`  -- "remove THIS version". Nothing here
-                //       has it and the index has never heard of it, so the
-                //       coordinate itself is wrong. Say so and fail; reporting
-                //       success would confirm a removal of something that
-                //       cannot exist.
-                const bool explicitVersion = target.contains('@');
-                auto selected = catalog.resolve_target(
-                    target, detect_platform());
-                std::expected<bool, std::string> executable = false;
-                if (selected) {
-                    executable = selected_payloadless_config_has_uninstall_(
-                        catalog, *selected, detect_platform());
-                }
-                if (!selected || !executable) {
-                    const auto reason = selected ? executable.error()
-                                                 : selected.error();
-                    if (explicitVersion) {
-                        stream.emit(ErrorEvent{
-                            .code = reason.contains("ambiguous")
-                                ? ErrorCode::InvalidInput
-                                : ErrorCode::NotFound,
-                            .message = reason,
-                            .recoverable = true,
-                            .hint = "verify the package coordinate, or drop "
-                                    "the version to remove whatever is installed",
-                        });
-                        return 1;
-                    }
-                    log::warn("xlings: cannot inspect an uninstall recipe for "
-                              "'{}' ({}); treating it as absent",
-                              target, reason);
-                }
-                if (executable && *executable) {
-                    payloadlessUninstallProven = true;
-                    log::info("{}@{} has an executable payloadless config "
-                              "uninstall; running it",
-                              selected->canonicalName, selected->version);
-                } else {
-                    // Genuinely absent. Here the "remove what isn't there is
-                    // success" convention is right (S4 of
-                    // remove_multi_version_test.sh asserts exit 0 and no
-                    // `removed.*subos` summary), so keep it -- with a visible
-                    // diagnostic, and without breaking scripts that re-run
-                    // `remove` defensively.
-                    log::warn(
-                        "xlings: '{}' is not installed in current subos '{}'",
-                        bareName, subos);
-                    return 0;
-                }
-            }
-
-            if (payloadOnDisk) {
-                log::warn("xlings: '{}' is not registered in subos '{}', but a "
-                          "payload is on disk; removing it for real",
-                          bareName, subos);
-            }
-        }
-    }
-
-    std::string resolveTarget = target;
-    if (target.find('@') == std::string::npos) {
-        auto bareName = target.substr(target.rfind(':') + 1);
-
-        // `remove <name>` with several versions installed here: SAY SO.
-        //
-        // This started as a refusal -- list the candidates, exit 2, on the
-        // reasoning that in every error `remove` raises about multi-version
-        // state the active binding is not the version being complained about.
-        // E2E-13 killed it, and was right to: `remove <pkg>` taking the active
-        // version and re-pointing the binding at the highest survivor is a
-        // documented, tested contract (docs/bugfixes/2026-04-25-...), and
-        // "run it three times to clear three versions" is a loop people write.
-        // The evidence behind the refusal came from the ERROR paths of #541 ②;
-        // generalising it to the ordinary path was not supported by it.
-        //
-        // What survives is the half that was actually missing: the user cannot
-        // see that this package has other versions here, or how to name them.
-        // Same move as the entry binary in this release -- ANNOUNCE the
-        // divergence, do not refuse it -- and consistency with that is most of
-        // the argument.
-        //
-        // `--force` is exempt: the xpkg hook path (pkgmanager.remove) passes it
-        // precisely because a recipe swapping a provider mid-install has
-        // already reasoned about what it replaces, and an extra paragraph in
-        // the middle of an install helps nobody.
-        if (!force) {
-            const auto& wsi = Config::workspace_installed();
-            if (auto it = wsi.find(bareName);
-                it != wsi.end() && it->second.size() > 1) {
-                auto versions = it->second;
-                version_order::sort_desc(versions);
-                log::warn("'{}' has {} versions installed in subos '{}'; this "
-                          "removes the ACTIVE one only",
-                          bareName, versions.size(), subos);
-                for (const auto& v : versions) {
-                    log::warn("  xlings remove {}@{}", target, v);
-                }
-            }
-        }
-
-        auto active = xvm::get_active_version(
-            Config::effective_workspace(), bareName);
-        // Fall back to "any installed version" when the active binding
-        // has been cleared. The catalog's default version pick is the
-        // recipe's highest *declared* version, which may not match what's
-        // on disk. Before this fallback, a sequence like
-        //
-        //     xlings remove d2x        # detaches active binding
-        //     xlings use d2x           # error: 'd2x' not in version DB
-        //     xlings remove d2x        # ← still picks declared 0.1.4!
-        //
-        // would loop forever: each subsequent remove re-resolved to the
-        // recipe's latest, hit `installer.uninstall` as a no-op (xvm DB
-        // already empty, payload dir already gone), and printed
-        // "✓ removed" anyway. Picking from the xvm DB instead anchors
-        // the resolution to reality.
-        if (active.empty()) {
-            // The database has to outlive the pointer into it.
-            // Config::versions() returns by VALUE, so passing the call
-            // directly to get_vinfo() handed back a pointer into a temporary
-            // that died at the end of that full expression -- and the next
-            // line read it. Use-after-free: `xlings remove glibc` on a home
-            // where glibc is registered but not active SIGSEGV'd on the
-            // released musl-static build and threw bad_alloc on a glibc one,
-            // from pick_highest_version walking a map that was gone.
-            //
-            // Reported 2026-07-28; reproduces identically on 2026.7.27.2,
-            // .3 and .4, so it is as old as this fallback.
-            const auto db = Config::versions();
-            const auto* vinfo = xvm::get_vinfo(db, bareName);
-            if (vinfo && !vinfo->versions.empty()) {
-                active = xvm::pick_highest_version(vinfo->versions);
-            }
-        }
-        if (!active.empty()) {
-            resolveTarget = target + "@" + active;
-        }
-    }
-
-    auto match = catalog.resolve_target(resolveTarget, detect_platform());
-    if (match) {
-        displayName = match->canonicalName;
-        displayVersion = match->version;
-        // Refuse to "remove" a version whose payload isn't on disk. The
-        // earlier version of this check only fired when the user pinned
-        // a version — under the theory that installer.uninstall would
-        // resolve the mismatch when the catalog had picked a non-installed
-        // version on its own. It does not. uninstall runs through the
-        // motions (xvm ops over an already-empty DB, fs::remove_all over
-        // a non-existent dir) and reports success, which loops the user.
-        // The xvm-DB fallback above already anchors resolution to a real
-        // installed version when one exists, so reaching here with
-        // `!installed` means nothing is installed for this target unless the
-        // payloadless-config proof above deliberately admitted its recipe.
-        if (!match->installed && !payloadlessUninstallProven) {
-            log::warn("{}@{} is not installed", displayName, displayVersion);
-            return 0;
-        }
-
-        // Guard against `xlings remove xim:xlings` when xlings has only
-        // one version installed.
-        //
-        // The remove path's "no surviving versions" branch tries to delete
-        // the program's PATH shim — and that shim IS the running xlings.exe.
-        // On Windows this fails with ERROR_SHARING_VIOLATION; on POSIX it
-        // succeeds via unlink(2)'s allow-unlink-of-running-executable
-        // semantics, but leaves a workspace pointer to a version that no
-        // longer exists. Both outcomes are wrong for the same reason: this
-        // command is the wrong tool for the job.
-        //
-        // Multi-version remove (auto-switch to highest remaining) keeps
-        // working unchanged — the no-survivors branch never fires there.
-        // Full uninstall has its own command (`xlings self uninstall`)
-        // which uses the atomic_replace_executable + scheduled-delete
-        // machinery designed precisely for "uninstall the running binary".
-        if (xvm::is_xlings_binary(match->name)) {
-            auto db = Config::versions();
-            const auto* vinfo = xvm::get_vinfo(db, match->name);
-            bool only_version = vinfo
-                && vinfo->versions.size() == 1
-                && vinfo->versions.contains(match->version);
-            if (only_version) {
-                log::error(
-                    "xlings only has one version installed ({}@{}); "
-                    "cannot remove the running binary itself.",
-                    match->canonicalName, match->version);
-                log::println(
-                    "  use `xlings self uninstall` to fully uninstall xlings, or");
-                log::println(
-                    "  install another version first: `xlings install {}@<other>`",
-                    match->canonicalName);
-                return 2;
-            }
-        }
-    }
-
-    // Reverse-dependency guard.
-    //
-    // `xlings remove libxml2` succeeds while llvm depends on it, and the next
-    // `ld.lld` does not start. The error names a soname, so it reads as a
-    // broken llvm install rather than as the consequence of the removal two
-    // commands earlier — and reinstalling llvm does not fix it, because llvm
-    // was never the thing that changed.
-    //
-    // Refuse and name the dependents. `--force` is the escape hatch, because
-    // there are legitimate reasons to break a link deliberately (replacing a
-    // package with another provider, pruning a home you are about to rebuild).
-    //
-    // Only DIRECT dependents are consulted, and that is not a shortcut: a
-    // dependency's libdirs enter a payload's RPATH closure only when it is
-    // named as a direct dep (elfpatch's closure_lib_paths reads the direct
-    // list). A package two hops away does not have this payload on any search
-    // path, so removing it cannot break that package through the loader.
-    // Deliberately NOT conditioned on `match`. The catalog fails to resolve a
-    // target whenever two repos provide the name -- `local:glibc` alongside
-    // `xim:glibc` is an ordinary state in a home that has ever registered a
-    // recipe locally -- and removal proceeds anyway, by bare name, further
-    // down. Gating the guard on a successful resolve made it skip in exactly
-    // the homes most likely to need it, and skip silently: same output as a
-    // clean pass. Take the bare name the way the subos-membership check above
-    // already does, and check regardless.
-    if (!force) {
-        struct Dependent { std::string name; std::string version; };
-        std::vector<Dependent> dependents;
-
-        const auto platform = detect_platform();
-        const auto bare_of = [](const std::string& s) {
-            auto noVer = s.substr(0, s.find('@'));
-            return noVer.substr(noVer.rfind(':') + 1);
-        };
-        const auto targetBare =
-            match ? bare_of(match->canonicalName) : bare_of(target);
-
-        // Current subos only. A package installed in another subos resolves
-        // through that subos's own payloads; removing it here detaches rather
-        // than deletes, which is exactly the case that must NOT be blocked.
-        for (const auto& rec : collect_inventory(catalog, /*allSubos=*/false)) {
-            // By bare name: the same package can be installed under two
-            // namespaces, and neither of them is "not the target".
-            if (bare_of(rec.canonicalName) == targetBare) continue;
-
-            auto depMatch = catalog.resolve_target(
-                rec.canonicalName + "@" + rec.version, platform);
-            if (!depMatch) continue;
-            auto depPkg = catalog.load_package(*depMatch);
-            if (!depPkg) continue;
-
-            // runtime first, falling back to the legacy union `deps` — the
-            // same precedence `info` uses. Build deps are irrelevant here:
-            // they are not on the consumer's runtime search path.
-            const std::vector<std::string>* list = nullptr;
-            if (auto it = depPkg->xpm.runtime_deps.find(platform);
-                it != depPkg->xpm.runtime_deps.end() && !it->second.empty()) {
-                list = &it->second;
-            } else if (auto it2 = depPkg->xpm.deps.find(platform);
-                       it2 != depPkg->xpm.deps.end() && !it2->second.empty()) {
-                list = &it2->second;
-            }
-            if (!list) continue;
-
-            for (const auto& dep : *list) {
-                // "xim:zlib@1.3.1" -> "zlib". Compare bare names: the
-                // namespace a consumer writes is not always the one the
-                // target resolved under, and a version range must not make
-                // a real dependency invisible to this check.
-                if (bare_of(dep) == targetBare) {
-                    dependents.push_back({rec.canonicalName, rec.version});
-                    break;
-                }
-            }
-        }
-
-        if (!dependents.empty()) {
-            log::error("{}@{} is required by {} installed package(s) in subos '{}':",
-                       displayName, displayVersion, dependents.size(), subos);
-            for (const auto& d : dependents) {
-                log::println("    {}@{}", d.name, d.version);
-            }
-            log::println("  remove those first, or re-run with --force to break the link "
-                         "anyway.");
-
-            nlohmann::json blockedPayload;
-            blockedPayload["subos"] = subos;
-            blockedPayload["name"] = displayName;
-            blockedPayload["version"] = displayVersion;
-            auto& arr = blockedPayload["required_by"] = nlohmann::json::array();
-            for (const auto& d : dependents) {
-                arr.push_back({{"name", d.name}, {"version", d.version}});
-            }
-            stream.emit(DataEvent{"remove_blocked", blockedPayload.dump()});
-            return 2;
-        }
-    }
-
-    nlohmann::json planPayload;
-    planPayload["subos"] = subos;
-    planPayload["name"] = displayName;
-    planPayload["version"] = displayVersion;
-    stream.emit(DataEvent{"remove_plan", planPayload.dump()});
-
-    if (!yes) {
-        std::string suffix = displayVersion.empty()
-            ? std::string{}
-            : "@" + displayVersion;
-        PromptEvent confirmReq;
-        confirmReq.id = "confirm_remove";
-        confirmReq.question = std::format(
-            "Remove {}{} from subos '{}' ?", displayName, suffix, subos);
-        confirmReq.options = {"y", "n"};
-        confirmReq.defaultValue = "n";
-        auto answer = stream.prompt(std::move(confirmReq));
-        if (answer != "y") {
-            log::println("cancelled");
-            return 0;
-        }
-    }
-
-    Installer installer(catalog);
-    auto result = installer.uninstall(target);
-    if (!result) {
-        log::error("uninstall failed: {}", result.error());
-        return 1;
-    }
-
-    // Say which of the two things actually happened.
-    //
-    // When another subos still pins this exact version, `remove` detaches the
-    // current subos and deliberately keeps the registration and the payload —
-    // deleting them would break every other subos that is using them. That is
-    // right. Printing "✓ removed" for it was not: the user is told the package
-    // is gone while ~/.xlings/.xlings.json and data/xpkgs/ still hold it in
-    // full, and the reinstall they try next tells them to uninstall first
-    // (#443, and the closed loop in #422).
-    //
-    // The subos are named rather than merely counted because that is the whole
-    // remedy: removing it from each of them in turn lets the last one delete
-    // the payload for real.
-    std::vector<std::string> pinnedBy;
-    if (result->detachedOnly) {
-        pinnedBy = xlings::profile::find_subos_pinning_version(
-            Config::paths().homeDir,
-            result->target.empty() ? displayName : result->target,
-            result->version.empty() ? displayVersion : result->version);
-        std::erase(pinnedBy, subos);
-    }
-
-    nlohmann::json summaryPayload;
-    summaryPayload["subos"] = subos;
-    summaryPayload["name"] = displayName;
-    summaryPayload["version"] = displayVersion;
-    summaryPayload["detached"] = result->detachedOnly;
-    summaryPayload["pinned_by"] = pinnedBy;
-    stream.emit(DataEvent{"remove_summary", summaryPayload.dump()});
-    return 0;
-}
+               bool force);
 
 // === search command ===
-int cmd_search(const std::string& keyword, EventStream& stream) {
-    auto& catalog = get_catalog();
-    if (!catalog.is_loaded()) {
-        log::error("package index not available");
-        return 1;
-    }
-
-    auto results = catalog.search(keyword, detect_platform());
-    if (results.empty()) {
-        log::println("no packages found matching '{}'", keyword);
-        return 0;
-    }
-
-    nlohmann::json itemsJson = nlohmann::json::array();
-    for (auto& match : results) {
-        auto pkg = catalog.load_package(match);
-        std::string desc = pkg ? pkg->description : "";
-        itemsJson.push_back({match.canonicalName, desc});
-    }
-    nlohmann::json searchPayload;
-    searchPayload["title"] = "Search results:";
-    searchPayload["items"] = std::move(itemsJson);
-    searchPayload["numbered"] = true;
-    stream.emit(DataEvent{"styled_list", searchPayload.dump()});
-    return 0;
-}
+int cmd_search(const std::string& keyword, EventStream& stream);
 
 // === list command ===
 //
@@ -1245,452 +100,14 @@ int cmd_search(const std::string& keyword, EventStream& stream) {
 // disk in xpkgs/" — that's *globally* installed and shared across
 // subos. The new C2 schema stores per-subos opt-in via
 // `workspace_installed`, so the subos-scoped list intersects the two.
-int cmd_list(const std::string& filter, EventStream& stream, bool all = false) {
-    auto& catalog = get_catalog();
-    if (!catalog.is_loaded()) {
-        log::error("package index not available");
-        return 1;
-    }
-
-    const auto inventoryFilter = filter.empty()
-        ? std::optional<std::string_view>{}
-        : std::optional<std::string_view>{filter};
-    auto installed = collect_inventory(catalog, all, inventoryFilter);
-
-    if (installed.empty()) {
-        if (all) {
-            log::println("no installed packages found");
-        } else {
-            log::println("no packages installed in current subos");
-            log::println("  hint: `xlings list --all` to see globally-installed packages");
-        }
-        // The empty list is where the nudge matters MOST, not least: a home
-        // whose packages are still registered in the old client's format can
-        // report nothing installed while the payloads sit on disk and the
-        // shims work. Returning early without it would stay silent exactly
-        // when the user has the strongest reason to wonder.
-        xself::print_migration_hint_once(Config::recorded_client_version(),
-                                         Info::VERSION);
-        return 0;
-    }
-
-    // Installed is not the same question as usable.
-    //
-    // `installed[]` and the active selection are two different tables, and a
-    // package can sit in the first without appearing in the second — a group
-    // whose activation was withheld at install time, or a `remove` that took
-    // out the active version and found no coherent replacement. Such a package
-    // has no shim, so its commands are not on PATH, and until now this list
-    // rendered it identically to a working one. The user then meets the
-    // failure through whatever tried to run it, in an error message that names
-    // the missing command and never names xlings.
-    const auto& ws = Config::effective_workspace();
-    const auto& db = Config::versions();
-
-    // Does this ROW's version serve the name, or does some other version?
-    //
-    // A row is a (package, version) pair, so "is the name active" is the wrong
-    // question whenever more than one version is installed: llvm 20.1.7 and
-    // 22.1.8 both register `llvm`, and asking only whether `llvm` is active
-    // leaves the 22.1.8 row looking exactly like the 20.1.7 one that is
-    // actually serving. Compare against the release the active version belongs
-    // to, not against the member version, because a member of a release
-    // carries its own version string (node's `npm` is at `node-24.15.0`).
-    const auto served_by_this_row = [&](std::string_view program,
-                                        const std::string& rowVersion) {
-        const auto it = ws.find(std::string(program));
-        if (it == ws.end() || it->second.empty()) return false;
-        std::string release = it->second;
-        if (const auto* vd = xvm::get_vdata(db, std::string(program), release);
-            vd && vd->bindingGroup) {
-            release = vd->bindingGroup->rootVersion;
-        }
-        return release == rowVersion
-            || xvm::strip_namespace(release) == rowVersion;
-    };
-
-    nlohmann::json listItems = nlohmann::json::array();
-    for (auto& match : installed) {
-        std::string desc = match.description;
-        // Asked of the programs the recipe declares, not of the package name:
-        // the package is `mcpp-short-cmd`, the xvm targets are `madd`,
-        // `mbuild`, … and the package name is never one of them. A package
-        // that declares nothing runnable (a library, a release anchor) has no
-        // active version to lack, so it is never flagged — the same
-        // `package.programs` promise installer.cppm:1847 verifies.
-        //
-        // LIMIT: a recipe that declares no `programs` is never marked, because
-        // nothing records which xvm targets a package version registered —
-        // that mapping exists only in the recipe. Measured: `binutils` and
-        // `gcc` declare theirs and are marked; `llvm` declares none and is
-        // not, though `self doctor` reports it by release. This is a floor,
-        // not full coverage, and the fix is in the recipe.
-        std::string status;
-        if (!match.degradedReason.empty()) {
-            status = "degraded: " + match.degradedReason;
-        } else if (!match.active && !match.programs.empty()
-            && std::ranges::none_of(match.programs,
-                [&](std::string_view program) {
-                    return served_by_this_row(program, match.version);
-                })) {
-            status = "inactive";
-        }
-        // Which subos a row belongs to is the whole reason `--all` exists, and
-        // the inventory has always carried it. Without it the wider listing is
-        // a flat set of names with no way to tell where any of them lives.
-        if (all && !match.suboses.empty()) {
-            std::string where;
-            for (const auto& subos : match.suboses) {
-                if (!where.empty()) where += ", ";
-                where += subos;
-            }
-            status += status.empty() ? "" : " \u00b7 ";
-            status += "in " + where;
-        }
-        listItems.push_back({match.canonicalName + "@" + match.version,
-                             desc, status});
-    }
-    nlohmann::json listPayload;
-    listPayload["title"] = all ? "Installed packages (all subos):"
-                               : "Installed packages (current subos):";
-    listPayload["items"] = std::move(listItems);
-    listPayload["numbered"] = true;
-    stream.emit(DataEvent{"styled_list", listPayload.dump()});
-    log::println("total: {} installed", installed.size());
-    xself::print_migration_hint_once(Config::recorded_client_version(),
-                                     Info::VERSION);
-    return 0;
-}
+int cmd_list(const std::string& filter, EventStream& stream, bool all = false);
 
 // === info command ===
 int cmd_info(const std::string& target, EventStream& stream,
-             bool allVersions = false) {
-    auto& catalog = get_catalog();
-    if (!catalog.is_loaded()) {
-        log::error("package index not available");
-        return 1;
-    }
-
-    auto match = catalog.resolve_target(target, detect_platform());
-    if (!match) {
-        log::error("{}", match.error());
-        return 1;
-    }
-
-    auto pkg = catalog.load_package(*match);
-    if (!pkg) {
-        log::error("failed to load package: {}", pkg.error());
-        return 1;
-    }
-
-    // Build info fields as JSON
-    auto addField = [](nlohmann::json& arr, const std::string& label,
-                       const std::string& value, bool hl = false) {
-        arr.push_back({{"label", label}, {"value", value}, {"highlight", hl}});
-    };
-
-    nlohmann::json fieldsJson = nlohmann::json::array();
-    addField(fieldsJson, "description", std::string(pkg->description));
-    if (!pkg->homepage.empty())
-        addField(fieldsJson, "homepage", std::string(pkg->homepage));
-    if (!pkg->repo.empty())
-        addField(fieldsJson, "repo", std::string(pkg->repo));
-    if (!pkg->licenses.empty()) {
-        std::string licStr;
-        for (auto& l : pkg->licenses) {
-            if (!licStr.empty()) licStr += " ";
-            licStr += l;
-        }
-        addField(fieldsJson, "licenses", licStr);
-    }
-    if (!pkg->categories.empty()) {
-        std::string catStr;
-        for (auto& c : pkg->categories) {
-            if (!catStr.empty()) catStr += " ";
-            catStr += c;
-        }
-        addField(fieldsJson, "categories", catStr);
-    }
-
-    auto platform = detect_platform();
-    auto platformIt = pkg->xpm.entries.find(platform);
-    if (platformIt != pkg->xpm.entries.end()) {
-        // Concrete versions and aliases used to share one comma-joined
-        // `versions` row, so `latest` and the version it points at appeared
-        // side by side — `latest -> 16.1.0, 16.1.0` reads as the list
-        // repeating itself. They are two different facts; they get two rows.
-        std::vector<std::string> versions;
-        std::vector<std::string> aliases;
-        for (auto& [ver, res] : platformIt->second) {
-            if (version_order::is_internal_key(ver)) continue;
-            if (!res.ref.empty()) {
-                aliases.push_back(ver + " -> " + res.ref);
-                continue;
-            }
-            versions.push_back(ver);
-        }
-        version_order::sort_desc(versions);
-        std::ranges::sort(aliases);
-        auto join_wrapped = [](const std::vector<std::string>& values,
-                               std::size_t limit) {
-            std::string result;
-            const auto count = std::min(values.size(), limit);
-            for (std::size_t i = 0; i < count; ++i) {
-                if (!result.empty()) result += (i % 4 == 0 ? "\n" : ", ");
-                result += values[i];
-            }
-            if (values.size() > count) {
-                result += std::format("\n… {} more (--all-versions)",
-                                      values.size() - count);
-            }
-            return result;
-        };
-        auto verStr = join_wrapped(versions,
-            allVersions ? versions.size() : std::size_t{8});
-        auto aliasStr = join_wrapped(aliases, aliases.size());
-        // `available` rather than `versions`: the panel's second half also
-        // had a row called `versions`, meaning the locally installed ones.
-        if (!verStr.empty())   addField(fieldsJson, "available", verStr);
-        if (!aliasStr.empty()) addField(fieldsJson, "aliases", aliasStr);
-    }
-
-    auto join_deps = [](const std::vector<std::string>& v) {
-        std::string s;
-        for (auto& d : v) {
-            if (!s.empty()) s += " ";
-            s += d;
-        }
-        return s;
-    };
-    auto rtIt = pkg->xpm.runtime_deps.find(platform);
-    auto bdIt = pkg->xpm.build_deps.find(platform);
-    bool hasRuntime = (rtIt != pkg->xpm.runtime_deps.end() && !rtIt->second.empty());
-    bool hasBuild   = (bdIt != pkg->xpm.build_deps.end()   && !bdIt->second.empty());
-    if (hasRuntime || hasBuild) {
-        // Show split form when either is non-empty. The legacy `deps`
-        // field was always the union, so omit it to avoid duplication
-        // when a package only declares the array form (loader fans
-        // legacy → both kinds, so listing all three would triple-print).
-        if (hasRuntime) addField(fieldsJson, "runtime deps", join_deps(rtIt->second));
-        if (hasBuild)   addField(fieldsJson, "build deps",   join_deps(bdIt->second));
-    } else {
-        auto depsIt = pkg->xpm.deps.find(platform);
-        if (depsIt != pkg->xpm.deps.end() && !depsIt->second.empty()) {
-            addField(fieldsJson, "deps", join_deps(depsIt->second));
-        }
-    }
-
-    const auto storeName = package_store_name(match->namespaceName, match->name);
-    const auto storePath = match->storeRoot / storeName;
-    // This package's rows only. Building the whole inventory to answer two
-    // booleans about one package made `info` proportional to the index.
-    const auto rows = collect_package_inventory(
-        catalog, match->canonicalName, /*allSubos=*/true);
-    const auto packageInstalled = !rows.empty();
-    const auto selectedInstalled = std::ranges::any_of(rows,
-        [&](const auto& record) {
-            return record.version == xvm::strip_namespace(match->version);
-        });
-    // Two labels, not three, and neither of them is a bare `installed`: the
-    // detail section below already has a row by that name listing the
-    // versions on disk. `package installed yes` / `selected installed no` /
-    // `installed 0.0.1 (active)` is three labels for overlapping facts, and
-    // the middle one is the only question the summary can answer that the
-    // list below cannot.
-    // An incomplete selected version must not render as `yes`. The payload is
-    // there and the records are not, so every command that reads one source
-    // says installed and every command that reads the other says it is not --
-    // which is how a graphics stack wired to nothing reported success on a
-    // real home. Named here so the panel answers the question that brings
-    // people to it.
-    const auto selectedIncomplete = std::ranges::any_of(rows,
-        [&](const auto& record) {
-            return record.version == xvm::strip_namespace(match->version)
-                && record.incomplete;
-        });
-    addField(fieldsJson, "selected version", match->version);
-    addField(fieldsJson, "selected installed",
-             !packageInstalled ? "no (package not installed)"
-             : selectedIncomplete ? "incomplete (payload present, not registered)"
-             : selectedInstalled ? "yes"
-             : "no (other versions are)");
-    if (selectedIncomplete) {
-        addField(fieldsJson, "repair",
-                 std::format("xlings install {}@{}",
-                             match->canonicalName, match->version));
-    }
-
-    nlohmann::json extraJson = nlohmann::json::array();
-    if (packageInstalled) {
-        auto db = Config::versions();
-        auto ws = Config::effective_workspace();
-        auto target = match->name;
-
-        auto activeVer = xvm::get_active_version(ws, target);
-        if (!activeVer.empty()) {
-            addField(extraJson, "active", activeVer, true);
-        }
-
-        auto allVers = xvm::get_all_versions(db, target);
-        if (!allVers.empty()) {
-            std::string verList;
-            for (auto& v : allVers) {
-                if (!verList.empty()) verList += ", ";
-                verList += v;
-                // Spelled out rather than a bare `*`, which needed a legend
-                // the panel never printed.
-                if (v == activeVer) verList += " (active)";
-            }
-            addField(extraJson, "installed", verList);
-        }
-
-        addField(extraJson, "xpkg path", Config::display_path(storePath));
-
-        auto binDir = Config::global_subos_bin_dir();
-        auto shimPath = binDir / target;
-        if (std::filesystem::exists(shimPath)) {
-            addField(extraJson, "shim", Config::display_path(shimPath));
-        }
-
-        auto* vinfo = xvm::get_vinfo(db, target);
-        if (vinfo && !vinfo->bindings.empty()) {
-            std::string bindStr;
-            for (auto& [bindName, verMap] : vinfo->bindings) {
-                if (!bindStr.empty()) bindStr += ", ";
-                bindStr += bindName;
-                if (!activeVer.empty()) {
-                    auto vit = verMap.find(activeVer);
-                    if (vit != verMap.end()) {
-                        bindStr += " -> " + vit->second;
-                    }
-                }
-            }
-            addField(extraJson, "bindings", bindStr);
-        }
-
-        auto subosRefs = profile::find_subos_referencing(
-            Config::paths().homeDir, target);
-        if (!subosRefs.empty()) {
-            std::string refStr;
-            for (auto& s : subosRefs) {
-                if (!refStr.empty()) refStr += ", ";
-                refStr += s;
-            }
-            addField(extraJson, "subos", refStr);
-        }
-    }
-
-    nlohmann::json infoPayload;
-    infoPayload["title"] = match->canonicalName;
-    infoPayload["fields"] = std::move(fieldsJson);
-    infoPayload["extra_fields"] = std::move(extraJson);
-    stream.emit(DataEvent{"info_panel", infoPayload.dump()});
-    return 0;
-}
+             bool allVersions = false);
 
 // === add-xpkg command ===
-int cmd_add_xpkg(const std::string& fileOrUrl, EventStream& stream) {
-    namespace fs = std::filesystem;
-    auto localRepoDir = Config::global_data_dir() / "xim-pkgindex-local";
-    auto pkgsDir = localRepoDir / "pkgs";
-    fs::path luaFile;
-
-    if (fileOrUrl.starts_with("http://") || fileOrUrl.starts_with("https://")) {
-        auto filename = fileOrUrl.substr(fileOrUrl.rfind('/') + 1);
-        if (auto q = filename.find('?'); q != std::string::npos)
-            filename = filename.substr(0, q);
-        // Download to temp location first, then move to letter subdir
-        auto tmpFile = pkgsDir / filename;
-        fs::create_directories(pkgsDir);
-        if (fs::exists(tmpFile)) fs::remove(tmpFile);
-        if (!tinyhttps::fetch_to_file(fileOrUrl, tmpFile)) {
-            log::error("download failed: {}", fileOrUrl);
-            return 1;
-        }
-        luaFile = tmpFile;
-    } else {
-        fs::path src(fileOrUrl);
-        if (!src.is_absolute()) src = fs::current_path() / src;
-        if (!fs::exists(src)) {
-            log::error("file not found: {}", Config::display_path(src));
-            return 1;
-        }
-        luaFile = pkgsDir / src.filename();
-        fs::create_directories(pkgsDir);
-        fs::copy_file(src, luaFile, fs::copy_options::overwrite_existing);
-    }
-
-    // Validate xpkg file
-    auto pkg = xpkg::load_package(luaFile);
-    if (!pkg) {
-        log::error("invalid xpkg: {}", pkg.error());
-        fs::remove(luaFile);
-        return 1;
-    }
-
-    // Move to letter subdirectory (build_index expects pkgs/<letter>/<name>.lua)
-    auto name = pkg->name;
-    if (name.empty()) name = luaFile.stem().string();
-    std::string letter(1, std::tolower(static_cast<unsigned char>(name[0])));
-    auto letterDir = pkgsDir / letter;
-    fs::create_directories(letterDir);
-    auto destFile = letterDir / luaFile.filename();
-    if (destFile != luaFile) {
-        fs::rename(luaFile, destFile);
-        luaFile = destFile;
-    }
-
-    // Give the local index the shared `libs/` too.
-    //
-    // Without this, `--add-xpkg` produces an index holding ONLY `pkgs/`, and a
-    // recipe's top-level `import("xim.pkgindex.sysroot")` resolves against
-    // `<index>/libs/<name>.lua` -- which does not exist -- so libxpkg hands back a
-    // permissive stub whose every call evaporates. Measured 2026-08-08 installing
-    // libXtst this way: `xvm.add` registered the anchor while
-    // `sysroot.declare_libs` produced no lib nodes at all, against a real-index
-    // install of the sibling libXi which produces libXi.so / .so.6 / .so.6.1.0.
-    //
-    // So a local install could not exercise the part of a recipe most likely to be
-    // wrong -- sysroot assets, driver directories, EGL/Vulkan manifests -- and it
-    // reported success. That cost a bug report against `xlings use` (#507) for a
-    // defect that did not exist.
-    //
-    // A symlink rather than a copy: the local index is an OVERLAY on the same
-    // ecosystem, so it should track the primary index's modules rather than
-    // snapshot them -- a stale copy would be its own silent-divergence bug. Falls
-    // back to a directory copy where symlinks need privileges (Windows).
-    {
-        auto primaryLibs = Config::global_data_dir() / "xim-pkgindex" / "libs";
-        auto localLibs = localRepoDir / "libs";
-        std::error_code lec;
-        if (fs::is_directory(primaryLibs, lec) && !fs::exists(localLibs, lec)) {
-            fs::create_directory_symlink(primaryLibs, localLibs, lec);
-            if (lec) {
-                lec.clear();
-                fs::copy(primaryLibs, localLibs,
-                         fs::copy_options::recursive
-                             | fs::copy_options::overwrite_existing, lec);
-            }
-            if (lec) {
-                log::warn("could not provide libs/ to the local index: {} -- "
-                          "`xim.pkgindex.*` calls in this recipe will be silent "
-                          "no-ops", lec.message());
-            }
-        } else if (!fs::is_directory(primaryLibs, lec)) {
-            log::warn("no primary index libs/ at {} -- `xim.pkgindex.*` calls in "
-                      "this recipe will be silent no-ops (run `xlings update`)",
-                      Config::display_path(primaryLibs));
-        }
-    }
-
-    log::println("add xpkg - {}", luaFile.string());
-    // Rebuild index so the new package is immediately available
-    auto& catalog = get_catalog();
-    // get_catalog() already triggers a rebuild on first call,
-    // but the local repo was just modified so we need a fresh rebuild
-    catalog.rebuild();
-    return 0;
-}
+int cmd_add_xpkg(const std::string& fileOrUrl, EventStream& stream);
 
 // === update command ===
 //
@@ -1704,89 +121,6 @@ int cmd_add_xpkg(const std::string& fileOrUrl, EventStream& stream) {
 // keeping the previous install lets the user `xlings use <pkg> <oldver>` if
 // the upgrade misbehaves. We surface a hint at the end pointing at how to
 // remove old versions.
-int cmd_update(const std::string& target, bool yes, EventStream& stream) {
-    // Sync repos
-    if (!sync_all_repos(true)) {
-        log::error("failed to sync repositories");
-        return 1;
-    }
-
-    // Force rebuild index (writes fresh cache)
-    auto& catalog = get_catalog();
-    auto rebuildResult = catalog.rebuild(true);
-    if (!rebuildResult) {
-        log::error("failed to rebuild catalog: {}", rebuildResult.error());
-        return 1;
-    }
-
-    log::println("index updated");
-
-    if (target.empty()) return 0;
-
-    auto match = catalog.resolve_target(target, detect_platform());
-    if (!match) {
-        log::error("{}", match.error());
-        return 1;
-    }
-
-    auto bareName = match->name;
-    auto latest = match->version;
-    auto currentActive = xvm::get_active_version(
-        Config::effective_workspace(), bareName);
-
-    nlohmann::json planPayload;
-    planPayload["name"]    = match->canonicalName;
-    planPayload["current"] = currentActive;
-    planPayload["latest"]  = latest;
-    stream.emit(DataEvent{"update_plan", planPayload.dump()});
-
-    if (currentActive.empty()) {
-        log::warn("{} is not installed — run: xlings install {}",
-                  match->canonicalName, bareName);
-        return 0;
-    }
-
-    if (currentActive == latest) {
-        log::println("{}@{} is already the latest", match->canonicalName, currentActive);
-        return 0;
-    }
-
-    if (!yes) {
-        PromptEvent confirmReq;
-        confirmReq.id = "confirm_update";
-        confirmReq.question = std::format(
-            "Upgrade {} from {} to {} ?",
-            match->canonicalName, currentActive, latest);
-        confirmReq.options = {"y", "n"};
-        confirmReq.defaultValue = "y";
-        auto answer = stream.prompt(std::move(confirmReq));
-        if (answer != "y") {
-            log::println("cancelled");
-            return 0;
-        }
-    }
-
-    // Install the new version. cmd_install handles dependency resolution,
-    // download, and hooks. We pass yes=true because the user already
-    // confirmed the upgrade above (and hook-driven sub-installs should
-    // never re-prompt regardless). useAfterInstall=true because update by
-    // definition moves the active pointer forward to the new version.
-    std::vector<std::string> installTargets = { bareName + "@" + latest };
-    auto rc = cmd_install(installTargets, /*yes=*/true, /*noDeps=*/false, stream,
-                          /*forceGlobal=*/false, /*cancel=*/nullptr,
-                          /*dryRun=*/false, /*useAfterInstall=*/true);
-    if (rc != 0) return rc;
-
-    nlohmann::json summaryPayload;
-    summaryPayload["name"] = match->canonicalName;
-    summaryPayload["from"] = currentActive;
-    summaryPayload["to"]   = latest;
-    stream.emit(DataEvent{"update_summary", summaryPayload.dump()});
-
-    log::println("upgraded {}: {} -> {}", match->canonicalName, currentActive, latest);
-    log::println("  old version retained — remove with: xlings remove {}@{}",
-                 bareName, currentActive);
-    return 0;
-}
+int cmd_update(const std::string& target, bool yes, EventStream& stream);
 
 } // namespace xlings::xim
diff --git a/src/core/xim/compatibility.cpp b/src/core/xim/compatibility.cpp
new file mode 100644
index 00000000..86530e34
--- /dev/null
+++ b/src/core/xim/compatibility.cpp
@@ -0,0 +1,140 @@
+module xlings.core.xim.compatibility;
+
+import std;
+import mcpplibs.xpkg;
+import xlings.platform.target;
+
+namespace xlings::xim {
+
+std::string host_architecture() {
+    return std::string(platform::build_arch());
+}
+
+const mcpplibs::xpkg::PlatformResource* find_entry(
+    const mcpplibs::xpkg::Package& package,
+    std::string_view os,
+    std::string_view version) {
+    const auto platform = package.xpm.entries.find(std::string(os));
+    if (platform == package.xpm.entries.end()) return nullptr;
+    std::string key(version);
+    // `latest -> 1.2.3 -> ...`. Bounded so a recipe with a cyclic alias
+    // returns "no entry" rather than spinning.
+    for (int hop = 0; hop < 8; ++hop) {
+        const auto found = platform->second.find(key);
+        if (found == platform->second.end()) return nullptr;
+        if (found->second.ref.empty()) return &found->second;
+        key = found->second.ref;
+    }
+    return nullptr;
+}
+
+std::set<std::string> entry_architectures(
+    const mcpplibs::xpkg::PlatformResource& entry) {
+    std::set<std::string> archs;
+    for (const auto& pair : entry.archs) {
+        archs.insert(mcpplibs::xpkg::normalize_arch(pair.first));
+    }
+    for (const auto& pair : entry.sha256_by_arch) {
+        archs.insert(mcpplibs::xpkg::normalize_arch(pair.first));
+    }
+    for (const auto& pair : entry.arch_alias) {
+        archs.insert(mcpplibs::xpkg::normalize_arch(pair.first));
+    }
+    return archs;
+}
+
+bool is_arch_templated(const mcpplibs::xpkg::PlatformResource& entry) {
+    const auto templated = [](std::string_view url) {
+        return url.find("${arch}") != std::string_view::npos
+            || url.find("${arch_alias}") != std::string_view::npos;
+    };
+    if (templated(entry.url)) return true;
+    for (const auto& pair : entry.mirrors) {
+        if (templated(pair.second)) return true;
+    }
+    return false;
+}
+
+ArchEvidence classify_arch_evidence(
+    const mcpplibs::xpkg::Package& package,
+    const mcpplibs::xpkg::PlatformResource* entry) {
+    if (entry != nullptr) {
+        if (!entry_architectures(*entry).empty()) return ArchEvidence::Strong;
+        // `res = true` is XLINGS_RES with per-arch checksums; when the loader
+        // has not populated them the resource is still arch-parametric.
+        if (entry->is_res || is_arch_templated(*entry)) {
+            return ArchEvidence::Open;
+        }
+    }
+    return package.archs.empty() ? ArchEvidence::None : ArchEvidence::Weak;
+}
+
+TargetCompatibility check_target_compatibility(
+    const mcpplibs::xpkg::Package& package,
+    const mcpplibs::xpkg::PlatformResource* entry,
+    std::string_view os,
+    std::string_view arch) {
+    TargetCompatibility result;
+    const auto normalizedArch = mcpplibs::xpkg::normalize_arch(arch);
+    result.target = std::string(os) + "-" + normalizedArch;
+    result.evidence = classify_arch_evidence(package, entry);
+
+    const auto label = [&](const std::string& value) {
+        return std::string(os) + "-" + value;
+    };
+
+    switch (result.evidence) {
+        case ArchEvidence::Strong: {
+            const auto archs = entry_architectures(*entry);
+            result.supported = archs.contains(normalizedArch);
+            for (const auto& value : archs) {
+                result.supportedTargets.push_back(label(value));
+            }
+            break;
+        }
+        case ArchEvidence::Weak: {
+            const auto declared = std::ranges::any_of(package.archs,
+                [&](const auto& packageArch) {
+                    return mcpplibs::xpkg::arch_matches(packageArch,
+                                                        normalizedArch);
+                });
+            // Deliberately still supported. This is the V1 under-declaration
+            // case: a single artifact whose `archs` was never enforced and is
+            // routinely wrong for exactly this OS.
+            result.supported = true;
+            if (!declared) {
+                std::string declaredTargets;
+                for (const auto& packageArch : package.archs) {
+                    if (!declaredTargets.empty()) declaredTargets += ", ";
+                    declaredTargets +=
+                        label(mcpplibs::xpkg::normalize_arch(packageArch));
+                }
+                result.advisory = std::format(
+                    "{}: recipe declares {} but ships one artifact for {}; "
+                    "installing it. Add per-arch resources to the recipe to "
+                    "make this checkable.",
+                    package.name, declaredTargets, result.target);
+            }
+            break;
+        }
+        case ArchEvidence::Open:
+        case ArchEvidence::None:
+            break;
+    }
+    return result;
+}
+
+std::string compatibility_error(std::string_view packageName,
+                                const TargetCompatibility& compatibility) {
+    std::string supported;
+    for (const auto& target : compatibility.supportedTargets) {
+        if (!supported.empty()) supported += ", ";
+        supported += target;
+    }
+    if (supported.empty()) supported = "none";
+    return std::format(
+        "E_UNSUPPORTED_TARGET: {} has no {} artifact; supported targets: {}",
+        packageName, compatibility.target, supported);
+}
+
+}
diff --git a/src/core/xim/compatibility.cppm b/src/core/xim/compatibility.cppm
index 04391dc8..332b24b2 100644
--- a/src/core/xim/compatibility.cppm
+++ b/src/core/xim/compatibility.cppm
@@ -60,9 +60,7 @@ struct TargetCompatibility {
 // An x86_64 build running under Rosetta has to install x86_64 artifacts,
 // because those are what it can link against and exec. Kept under the old name
 // so callers do not all move at once; `platform::Target` documents the split.
-std::string host_architecture() {
-    return std::string(platform::build_arch());
-}
+std::string host_architecture();
 
 // The `xpm[os][version]` resource, with version aliases (`ref`) followed.
 // nullptr when this OS or version has no entry -- the caller then has nothing
@@ -70,62 +68,17 @@ std::string host_architecture() {
 const mcpplibs::xpkg::PlatformResource* find_entry(
     const mcpplibs::xpkg::Package& package,
     std::string_view os,
-    std::string_view version) {
-    const auto platform = package.xpm.entries.find(std::string(os));
-    if (platform == package.xpm.entries.end()) return nullptr;
-    std::string key(version);
-    // `latest -> 1.2.3 -> ...`. Bounded so a recipe with a cyclic alias
-    // returns "no entry" rather than spinning.
-    for (int hop = 0; hop < 8; ++hop) {
-        const auto found = platform->second.find(key);
-        if (found == platform->second.end()) return nullptr;
-        if (found->second.ref.empty()) return &found->second;
-        key = found->second.ref;
-    }
-    return nullptr;
-}
+    std::string_view version);
 
 // Architectures this entry names outright, canonicalised.
 std::set<std::string> entry_architectures(
-    const mcpplibs::xpkg::PlatformResource& entry) {
-    std::set<std::string> archs;
-    for (const auto& pair : entry.archs) {
-        archs.insert(mcpplibs::xpkg::normalize_arch(pair.first));
-    }
-    for (const auto& pair : entry.sha256_by_arch) {
-        archs.insert(mcpplibs::xpkg::normalize_arch(pair.first));
-    }
-    for (const auto& pair : entry.arch_alias) {
-        archs.insert(mcpplibs::xpkg::normalize_arch(pair.first));
-    }
-    return archs;
-}
+    const mcpplibs::xpkg::PlatformResource& entry);
 
-bool is_arch_templated(const mcpplibs::xpkg::PlatformResource& entry) {
-    const auto templated = [](std::string_view url) {
-        return url.find("${arch}") != std::string_view::npos
-            || url.find("${arch_alias}") != std::string_view::npos;
-    };
-    if (templated(entry.url)) return true;
-    for (const auto& pair : entry.mirrors) {
-        if (templated(pair.second)) return true;
-    }
-    return false;
-}
+bool is_arch_templated(const mcpplibs::xpkg::PlatformResource& entry);
 
 ArchEvidence classify_arch_evidence(
     const mcpplibs::xpkg::Package& package,
-    const mcpplibs::xpkg::PlatformResource* entry) {
-    if (entry != nullptr) {
-        if (!entry_architectures(*entry).empty()) return ArchEvidence::Strong;
-        // `res = true` is XLINGS_RES with per-arch checksums; when the loader
-        // has not populated them the resource is still arch-parametric.
-        if (entry->is_res || is_arch_templated(*entry)) {
-            return ArchEvidence::Open;
-        }
-    }
-    return package.archs.empty() ? ArchEvidence::None : ArchEvidence::Weak;
-}
+    const mcpplibs::xpkg::PlatformResource* entry);
 
 // `entry` is the resolved `xpm[os][version]` resource, with `ref` already
 // followed. Pass nullptr when no entry could be selected -- the answer then
@@ -134,68 +87,9 @@ TargetCompatibility check_target_compatibility(
     const mcpplibs::xpkg::Package& package,
     const mcpplibs::xpkg::PlatformResource* entry,
     std::string_view os,
-    std::string_view arch) {
-    TargetCompatibility result;
-    const auto normalizedArch = mcpplibs::xpkg::normalize_arch(arch);
-    result.target = std::string(os) + "-" + normalizedArch;
-    result.evidence = classify_arch_evidence(package, entry);
-
-    const auto label = [&](const std::string& value) {
-        return std::string(os) + "-" + value;
-    };
-
-    switch (result.evidence) {
-        case ArchEvidence::Strong: {
-            const auto archs = entry_architectures(*entry);
-            result.supported = archs.contains(normalizedArch);
-            for (const auto& value : archs) {
-                result.supportedTargets.push_back(label(value));
-            }
-            break;
-        }
-        case ArchEvidence::Weak: {
-            const auto declared = std::ranges::any_of(package.archs,
-                [&](const auto& packageArch) {
-                    return mcpplibs::xpkg::arch_matches(packageArch,
-                                                        normalizedArch);
-                });
-            // Deliberately still supported. This is the V1 under-declaration
-            // case: a single artifact whose `archs` was never enforced and is
-            // routinely wrong for exactly this OS.
-            result.supported = true;
-            if (!declared) {
-                std::string declaredTargets;
-                for (const auto& packageArch : package.archs) {
-                    if (!declaredTargets.empty()) declaredTargets += ", ";
-                    declaredTargets +=
-                        label(mcpplibs::xpkg::normalize_arch(packageArch));
-                }
-                result.advisory = std::format(
-                    "{}: recipe declares {} but ships one artifact for {}; "
-                    "installing it. Add per-arch resources to the recipe to "
-                    "make this checkable.",
-                    package.name, declaredTargets, result.target);
-            }
-            break;
-        }
-        case ArchEvidence::Open:
-        case ArchEvidence::None:
-            break;
-    }
-    return result;
-}
+    std::string_view arch);
 
 std::string compatibility_error(std::string_view packageName,
-                                const TargetCompatibility& compatibility) {
-    std::string supported;
-    for (const auto& target : compatibility.supportedTargets) {
-        if (!supported.empty()) supported += ", ";
-        supported += target;
-    }
-    if (supported.empty()) supported = "none";
-    return std::format(
-        "E_UNSUPPORTED_TARGET: {} has no {} artifact; supported targets: {}",
-        packageName, compatibility.target, supported);
-}
+                                const TargetCompatibility& compatibility);
 
 }  // namespace xlings::xim
diff --git a/src/core/xim/downloader.cpp b/src/core/xim/downloader.cpp
new file mode 100644
index 00000000..835c3838
--- /dev/null
+++ b/src/core/xim/downloader.cpp
@@ -0,0 +1,938 @@
+module;
+
+#include <cstdio>
+
+module xlings.core.xim.downloader;
+
+import std;
+import xlings.core.xim.libxpkg.types.type;
+import xlings.core.log;
+import xlings.core.palette;
+import xlings.core.compact;
+import xlings.platform;
+import xlings.core.config;
+import xlings.libs.tinyhttps;
+import xlings.runtime.cancellation;
+import xlings.core.mirror;
+import xlings.libs.sha256;
+import xlings.core.xim.extract;
+
+namespace xlings::xim {
+
+bool is_git_url(const std::string& url) {
+    return url.ends_with(".git");
+}
+
+bool looks_like_archive_filename_(const std::filesystem::path& path) {
+    auto name = path.filename().string();
+    return name.ends_with(".tar.gz")
+        || name.ends_with(".tar.xz")
+        || name.ends_with(".tar.bz2")
+        || name.ends_with(".tar.zst")
+        || name.ends_with(".tgz")
+        || name.ends_with(".zip");
+}
+
+std::string lower_hex_(std::string_view s) {
+    std::string out(s);
+    for (auto& c : out)
+        if (c >= 'A' && c <= 'F') c = static_cast<char>(c - 'A' + 'a');
+    return out;
+}
+
+std::filesystem::path unique_sibling_path_(
+        const std::filesystem::path& base,
+        std::string_view marker) {
+    static std::atomic_uint64_t sequence { 0 };
+    auto path = base;
+    path += std::format(
+        ".{}.{}.{}", marker,
+        std::chrono::steady_clock::now().time_since_epoch().count(),
+        sequence.fetch_add(1));
+    return path;
+}
+
+bool commit_staging_file_(const std::filesystem::path& staging, const std::filesystem::path& destination, std::string& error, bool failAfterBackupForTest) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    auto backup = unique_sibling_path_(destination, "old");
+    const bool hadDestination = fs::exists(destination, ec);
+    if (ec) {
+        error = std::format("failed to inspect {}: {}",
+                            destination.string(), ec.message());
+        return false;
+    }
+    if (hadDestination) {
+        fs::rename(destination, backup, ec);
+        if (ec) {
+            error = std::format("failed to preserve {}: {}",
+                                destination.string(), ec.message());
+            return false;
+        }
+    }
+    if (failAfterBackupForTest) {
+        if (hadDestination) {
+            fs::rename(backup, destination, ec);
+        }
+        error = "injected commit failure after backup";
+        return false;
+    }
+    fs::rename(staging, destination, ec);
+    if (ec) {
+        auto commitError = ec.message();
+        if (hadDestination) {
+            std::error_code restoreEc;
+            fs::rename(backup, destination, restoreEc);
+            if (restoreEc) {
+                error = std::format(
+                    "failed to commit {} ({}) and restore previous file ({})",
+                    destination.string(), commitError, restoreEc.message());
+                return false;
+            }
+        }
+        error = std::format("failed to commit {}: {}",
+                            destination.string(), commitError);
+        return false;
+    }
+    if (hadDestination) {
+        fs::remove(backup, ec);
+    }
+    return true;
+}
+
+bool recover_download_transaction_(
+        const std::filesystem::path& destination,
+        std::string& error) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    std::vector<fs::path> backups;
+    std::vector<fs::path> stagingFiles;
+    const auto backupPrefix = destination.filename().string() + ".old.";
+    const auto stagingPrefix = destination.filename().string() + ".part.";
+    auto parent = destination.parent_path();
+    for (auto it = fs::directory_iterator(parent, ec);
+         !ec && it != std::default_sentinel; it.increment(ec)) {
+        auto name = it->path().filename().string();
+        if (name.starts_with(backupPrefix)) backups.push_back(it->path());
+        else if (name.starts_with(stagingPrefix)) stagingFiles.push_back(it->path());
+    }
+    if (ec) {
+        error = std::format("failed to inspect download transaction for {}: {}",
+                            destination.string(), ec.message());
+        return false;
+    }
+
+    std::ranges::sort(backups);
+    const bool liveExists = fs::exists(destination, ec);
+    if (ec) {
+        error = std::format("failed to inspect {}: {}",
+                            destination.string(), ec.message());
+        return false;
+    }
+    if (!liveExists && !backups.empty()) {
+        auto restore = backups.back();
+        backups.pop_back();
+        fs::rename(restore, destination, ec);
+        if (ec) {
+            error = std::format("failed to restore interrupted download {}: {}",
+                                destination.string(), ec.message());
+            return false;
+        }
+    }
+    for (const auto& path : backups) {
+        fs::remove(path, ec);
+        if (ec) {
+            error = std::format("failed to remove stale backup {}: {}",
+                                path.string(), ec.message());
+            return false;
+        }
+    }
+    for (const auto& path : stagingFiles) {
+        fs::remove(path, ec);
+        if (ec) {
+            error = std::format("failed to remove stale staging file {}: {}",
+                                path.string(), ec.message());
+            return false;
+        }
+    }
+    return true;
+}
+
+std::optional<MetaSidecar_> read_meta_sidecar_(const std::filesystem::path& p) {
+    std::ifstream in(p);
+    if (!in) return std::nullopt;
+    MetaSidecar_ m;
+    std::string line;
+    while (std::getline(in, line)) {
+        auto colon = line.find(':');
+        if (colon == std::string::npos) continue;
+        std::string key = line.substr(0, colon);
+        std::string val = line.substr(colon + 1);
+        // trim
+        auto trim = [](std::string& s) {
+            while (!s.empty() && (s.front() == ' ' || s.front() == '\t' || s.front() == '\r')) s.erase(s.begin());
+            while (!s.empty() && (s.back()  == ' ' || s.back()  == '\t' || s.back()  == '\r')) s.pop_back();
+        };
+        trim(key); trim(val);
+        for (auto& c : key) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+        if (key == "format") {
+            int parsed {};
+            auto [ptr, err] = std::from_chars(val.data(), val.data() + val.size(), parsed);
+            if (err != std::errc{} || ptr != val.data() + val.size()) return std::nullopt;
+            m.format = parsed;
+        } else if (key == "complete") {
+            if (val == "true") m.complete = true;
+            else if (val == "false") m.complete = false;
+            else return std::nullopt;
+        } else if (key == "size") {
+            std::int64_t parsed {};
+            auto [ptr, err] = std::from_chars(val.data(), val.data() + val.size(), parsed);
+            if (err != std::errc{} || ptr != val.data() + val.size() || parsed < 0) {
+                return std::nullopt;
+            }
+            m.size = parsed;
+        } else if (key == "source-url") {
+            m.sourceUrl = std::move(val);
+        } else if (key == "cache-identity") {
+            m.cacheIdentity = std::move(val);
+        } else if (key == "last-modified") {
+            m.lastModified = std::move(val);
+        } else if (key == "etag") {
+            m.etag = std::move(val);
+        }
+    }
+    if (m.format != 1 && m.format != 2) return std::nullopt;
+    if (m.format == 2
+        && (!m.complete || m.size < 0 || m.cacheIdentity.empty())) {
+        return std::nullopt;
+    }
+    return m;
+}
+
+bool write_meta_sidecar_(const std::filesystem::path& p,
+                         const tinyhttps::RemoteFileMeta& meta,
+                         std::int64_t size,
+                         std::string_view cacheIdentity,
+                         std::string_view sourceUrl) {
+    auto staging = unique_sibling_path_(p, "tmp");
+    {
+        std::ofstream out(staging, std::ios::trunc);
+        if (!out) return false;
+        out << "format: 2\n";
+        out << "complete: true\n";
+        out << "size: " << size << "\n";
+        out << "source-url: " << sourceUrl << "\n";
+        out << "cache-identity: " << cacheIdentity << "\n";
+        if (!meta.lastModified.empty()) out << "last-modified: " << meta.lastModified << "\n";
+        if (!meta.etag.empty())         out << "etag: "          << meta.etag         << "\n";
+        out.flush();
+        if (!out) {
+            std::error_code ec;
+            std::filesystem::remove(staging, ec);
+            return false;
+        }
+    }
+    std::string error;
+    if (!commit_staging_file_(staging, p, error)) {
+        std::error_code ec;
+        std::filesystem::remove(staging, ec);
+        return false;
+    }
+    return true;
+}
+
+CacheAdmission_ decide_cache_admission_(const CacheAdmissionInput_& input) {
+    if (input.localSize <= 0) return CacheAdmission_::Redownload;
+
+    if (!input.headSucceeded) {
+        if (!input.sidecar) return CacheAdmission_::Redownload;
+        const auto& stored = *input.sidecar;
+        const bool committedV2 =
+            stored.format == 2
+            && stored.complete
+            && stored.size == input.localSize
+            && !input.expectedCacheIdentity.empty()
+            && stored.cacheIdentity == input.expectedCacheIdentity;
+        return committedV2
+            ? CacheAdmission_::OfflineUnverifiedHit
+            : CacheAdmission_::Redownload;
+    }
+
+    const bool sizeMatch =
+        input.remoteSize > 0 && input.remoteSize == input.localSize;
+    if (!sizeMatch) return CacheAdmission_::Redownload;
+
+    if (!input.sidecar) return CacheAdmission_::Hit;
+    const auto& stored = *input.sidecar;
+    const bool freshMatch =
+        (!input.remoteLastModified.empty()
+            && input.remoteLastModified == stored.lastModified)
+        || (!input.remoteEtag.empty() && input.remoteEtag == stored.etag);
+    const bool noFreshnessEvidence =
+        stored.lastModified.empty() && stored.etag.empty();
+    return (freshMatch || noFreshnessEvidence)
+        ? CacheAdmission_::Hit
+        : CacheAdmission_::Redownload;
+}
+
+tinyhttps::RemoteFileMeta query_remote_meta_(
+        const std::string& url,
+        const DownloadTestHooks_* hooks) {
+    if (hooks && hooks->queryRemoteMeta) return hooks->queryRemoteMeta(url);
+    return tinyhttps::query_remote_meta(url);
+}
+
+std::string git_dest_repo_name_(const std::string& url, const std::string& fallback) {
+    std::string repoName;
+    auto lastSlash = url.rfind('/');
+    if (lastSlash != std::string::npos) {
+        repoName = url.substr(lastSlash + 1);
+        if (repoName.ends_with(".git"))
+            repoName = repoName.substr(0, repoName.size() - 4);
+    }
+    return repoName.empty() ? fallback : repoName;
+}
+
+std::vector<std::string> git_candidate_urls_(const DownloadTask& task) {
+    std::vector<std::string> urls;
+    urls.push_back(task.url);
+    for (auto& fb : task.fallbackUrls) urls.push_back(fb);
+
+    auto mirrored = mirror::expand(task.url, {.type = mirror::ResourceType::Git});
+    for (auto& u : mirrored) {
+        if (std::ranges::find(urls, u) == urls.end())
+            urls.push_back(std::move(u));
+    }
+    return urls;
+}
+
+bool atomic_swap_dir_(const std::filesystem::path& staging,
+                      const std::filesystem::path& live) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    auto old = live.parent_path() / (live.filename().string() + ".old");
+    fs::remove_all(old, ec);          // crashed-run leftovers
+    ec.clear();
+    if (fs::exists(live)) {
+        fs::rename(live, old, ec);
+        if (ec) return false;
+    }
+    fs::rename(staging, live, ec);
+    if (ec) {
+        std::error_code ec2;
+        fs::rename(old, live, ec2);   // best-effort restore
+        return false;
+    }
+    fs::remove_all(old, ec);
+    return true;
+}
+
+DownloadResult git_clone_one(const DownloadTask& task) {
+    namespace fs = std::filesystem;
+
+    DownloadResult result;
+    result.name = task.name;
+
+    std::error_code ec;
+    fs::create_directories(task.destDir, ec);
+    if (ec) {
+        result.error = std::format("failed to create directory {}: {}",
+                                   task.destDir.string(), ec.message());
+        return result;
+    }
+
+    auto repoName = git_dest_repo_name_(task.url, task.name);
+    auto destDir = task.destDir / repoName;
+    result.localFile = destDir;
+
+    // If already cloned, pull latest. Pull is single-URL by design — we
+    // don't switch remotes here. Pull failure falls through to a STAGED
+    // re-clone; the live tree stays untouched until a replacement is ready.
+    const bool hadLive = fs::exists(destDir / ".git");
+    if (hadLive) {
+        log::debug("already cloned {}, pulling latest...", task.name);
+        auto pull = compact::git::pull_ff_only(destDir);
+        if (pull.rc == 0) {
+            result.success = true;
+            return result;
+        }
+        log::warn("pull failed for {}, re-cloning into staging...", task.name);
+    }
+
+    auto staging = task.destDir / (".staging-" + repoName);
+    ec.clear();
+    fs::remove_all(staging, ec);      // crashed-run leftovers
+
+    auto urls = git_candidate_urls_(task);
+    for (std::size_t i = 0; i < urls.size(); ++i) {
+        const auto& url = urls[i];
+        log::debug("cloning {} attempt {}/{}: {}",
+                   task.name, i + 1, urls.size(), url);
+        auto clone = compact::git::clone_shallow(url, staging, true);
+        if (clone.rc == 0 && fs::exists(staging / ".git")) {
+            if (i > 0)
+                log::info("[mirror] git clone fallback succeeded via {}", url);
+            if (atomic_swap_dir_(staging, destDir)) {
+                result.success = true;
+                return result;
+            }
+            log::warn("atomic swap failed for {}", task.name);
+        }
+        // Clean partial staging clone before next attempt.
+        ec.clear();
+        fs::remove_all(staging, ec);
+    }
+
+    if (hadLive) {
+        // Every URL failed but a previous copy exists: keep serving it.
+        log::warn("{}: refresh failed on all URLs; keeping the previous copy",
+                  task.name);
+        result.success = true;
+        return result;
+    }
+    result.error = std::format("all git clone URLs failed for {}", task.name);
+    return result;
+}
+
+DownloadResult download_one(const DownloadTask& task, std::function<void(double total, double now)> onProgress, CancellationToken* cancel, const DownloadTestHooks_* testHooks) {
+    namespace fs = std::filesystem;
+
+    DownloadResult result;
+    result.name = task.name;
+
+    // Ensure dest directory exists
+    std::error_code ec;
+    fs::create_directories(task.destDir, ec);
+    if (ec) {
+        result.error = std::format("failed to create directory {}: {}",
+                                   task.destDir.string(), ec.message());
+        return result;
+    }
+
+    // Git clone for .git URLs. The non-cancellable path delegates to
+    // git_clone_one which already handles mirror fallback; the cancellable
+    // path needs the same fallback wiring inline because it uses
+    // spawn_command/wait_or_kill instead of blocking exec.
+    if (is_git_url(task.url)) {
+        if (cancel) {
+            namespace fs = std::filesystem;
+            auto repoName = git_dest_repo_name_(task.url, task.name);
+            auto destDir = task.destDir / repoName;
+            result.localFile = destDir;
+
+            // Staged acquisition, mirroring git_clone_one: clone into a
+            // sibling .staging dir, atomic-swap on success, and keep any
+            // previous live copy when every URL fails (or on cancel).
+            const bool hadLive = fs::exists(destDir / ".git");
+            auto staging = task.destDir / (".staging-" + repoName);
+            std::error_code ecs;
+            fs::remove_all(staging, ecs);
+
+            auto urls = git_candidate_urls_(task);
+            std::string lastError;
+            for (std::size_t i = 0; i < urls.size(); ++i) {
+                const auto& url = urls[i];
+                log::debug("cloning {} (cancellable) attempt {}/{}: {}",
+                           task.name, i + 1, urls.size(), url);
+                auto h = compact::git::spawn({
+                    "clone", "--depth", "1", "--recursive", "--quiet",
+                    url, staging.string()
+                });
+                if (h.pid <= 0) { lastError = "failed to spawn git"; continue; }
+                auto [code, output] = platform::wait_or_kill(
+                    h, cancel, std::chrono::minutes{10});
+                if (cancel->is_paused() || cancel->is_cancelled()) {
+                    fs::remove_all(staging, ecs);
+                    result.error = "cancelled";
+                    return result;
+                }
+                if (code == 0 && fs::exists(staging / ".git")
+                    && atomic_swap_dir_(staging, destDir)) {
+                    if (i > 0)
+                        log::info("[mirror] git clone fallback succeeded via {}", url);
+                    result.success = true;
+                    return result;
+                }
+                lastError = output;
+                fs::remove_all(staging, ecs);
+            }
+            if (hadLive) {
+                log::warn("{}: refresh failed on all URLs; keeping the previous copy",
+                          task.name);
+                result.success = true;
+                return result;
+            }
+            result.error = lastError.empty()
+                ? std::format("all git clone URLs failed for {}", task.name)
+                : lastError;
+            return result;
+        }
+        return git_clone_one(task);
+    }
+
+    log::debug("downloading {} from {}", task.name, task.url);
+
+    // Extract filename from URL
+    std::string url = task.url;
+    std::string filename;
+    auto lastSlash = url.rfind('/');
+    if (lastSlash != std::string::npos) {
+        filename = url.substr(lastSlash + 1);
+        auto q = filename.find('?');
+        if (q != std::string::npos) filename = filename.substr(0, q);
+    }
+    if (filename.empty()) filename = task.name + ".download";
+
+    auto destFile = task.destDir / filename;
+    auto sidecarPath = destFile;
+    sidecarPath += ".meta";
+    result.localFile = destFile;
+
+    auto lockPath = destFile;
+    lockPath += ".lock";
+    platform::FileLock cacheLock;
+    std::string lockError;
+    auto cancelled = [cancel] {
+        return cancel && (cancel->is_paused() || cancel->is_cancelled());
+    };
+    if (!cacheLock.acquire(
+            lockPath, std::chrono::minutes{10}, cancelled, lockError)) {
+        result.error = std::move(lockError);
+        return result;
+    }
+    if (!recover_download_transaction_(destFile, lockError)) {
+        result.error = std::move(lockError);
+        return result;
+    }
+
+    // ── Cache hit path 1: sha256 verified (cheapest, most reliable) ──
+    // If the recipe declares a sha256 and the on-disk file matches, we're
+    // byte-identical to upstream — skip download outright.
+    if (fs::exists(destFile) && !task.sha256.empty()) {
+        // In-process hash — `sha256sum` is a coreutils tool absent on
+        // stock macOS, where shelling out made every pinned download
+        // "mismatch" (see xlings.libs.sha256 header).
+        auto digest = sha256::hex_file(destFile);
+        if (digest && *digest == lower_hex_(task.sha256)) {
+            log::debug("already downloaded (sha256): {}", destFile.string());
+            result.success = true;
+            return result;
+        }
+        // sha mismatch: stale/corrupt cache. Remove before falling through
+        // so the next download_to_file starts from a clean slate (defends
+        // against a future tinyhttps that might enable Range/resume).
+        // Keep the previous file until a verified replacement is ready.
+    }
+
+    // ── Cache hit path 2: HEAD-based freshness (when sha256 is unset) ──
+    // Trade a tiny HEAD round-trip for not re-downloading toolchain-sized
+    // payloads on every `xlings install`. We only consult this when the
+    // recipe omits sha256 — otherwise path 1 already decided.
+    tinyhttps::RemoteFileMeta probedMeta;
+    bool probedMetaValid = false;
+    if (fs::exists(destFile) && task.sha256.empty()) {
+        probedMeta = query_remote_meta_(task.url, testHooks);
+        probedMetaValid = true;
+
+        if (probedMeta.ok) {
+            std::error_code sec;
+            auto localSize = static_cast<std::int64_t>(fs::file_size(destFile, sec));
+            auto admission = decide_cache_admission_({
+                .localSize = sec ? -1 : localSize,
+                .headSucceeded = true,
+                .remoteSize = probedMeta.contentLength,
+                .remoteLastModified = probedMeta.lastModified,
+                .remoteEtag = probedMeta.etag,
+                .sidecar = read_meta_sidecar_(sidecarPath),
+                .expectedCacheIdentity = task.cacheIdentity,
+            });
+            if (admission == CacheAdmission_::Hit) {
+                log::debug("already downloaded (HEAD cache hit, size={}): {}",
+                           localSize, destFile.string());
+                result.success = true;
+                return result;
+            }
+            // Stale: retain the previous committed pair until the replacement
+            // has transferred and passed all acceptance checks.
+        } else {
+            std::error_code sec;
+            auto localSize = static_cast<std::int64_t>(fs::file_size(destFile, sec));
+            auto admission = decide_cache_admission_({
+                .localSize = sec ? -1 : localSize,
+                .headSucceeded = false,
+                .sidecar = read_meta_sidecar_(sidecarPath),
+                .expectedCacheIdentity = task.cacheIdentity,
+            });
+            if (admission == CacheAdmission_::OfflineUnverifiedHit) {
+                log::warn("HEAD probe failed for {} ({}); using transaction-committed "
+                          "cache without cryptographic verification: {}",
+                          task.url,
+                          probedMeta.error.empty() ? "unknown" : probedMeta.error,
+                          destFile.string());
+                result.success = true;
+                return result;
+            }
+        }
+    }
+
+    // Build ordered list of URLs to try:
+    //   1. primary URL (as-is)
+    //   2. package-author-declared fallback URLs (already mirror-selected
+    //      by upstream resolver)
+    //   3. github mirror fallbacks (only appended if URL is github.com/
+    //      raw.githubusercontent.com/etc and mirror mode != Off)
+    std::vector<std::string> urls;
+    urls.push_back(url);
+    for (auto& fb : task.fallbackUrls) urls.push_back(fb);
+
+    auto mirrored = mirror::expand(url);
+    for (auto& u : mirrored) {
+        if (std::ranges::find(urls, u) == urls.end())
+            urls.push_back(std::move(u));
+    }
+
+    // Adaptive ordering (0.4.49): probe candidate hosts' connect latency
+    // (memoized per process) and order accordingly. With a declared sha256
+    // the bytes are pinned, so faster mirrors may be tried before the
+    // original URL; without one the author-declared URL stays first unless
+    // its host is unreachable/penalized. See
+    // .agents/docs/2026-06-04-github-asset-adaptive-mirror.md.
+    urls = mirror::adaptive::reorder(std::move(urls), !task.sha256.empty());
+
+    // Which sources are in play, in the order they will be tried. When a
+    // download is slow or 404s, the first question is always "where is it
+    // even pulling from, and what else could it have used" -- and until now
+    // nothing answered it, so a CN outage looked like a dead package rather
+    // than a mirror with a gap.
+    if (urls.size() > 1) {
+        std::string candidates;
+        for (const auto& u : urls) {
+            if (!candidates.empty()) candidates += "\n    ";
+            candidates += u;
+        }
+        log::debug("[download] {} candidates ({}):\n    {}",
+                   task.name, urls.size(), candidates);
+    }
+    const std::string primaryUrl = urls.front();
+
+    auto stagingFile = unique_sibling_path_(destFile, "part");
+    tinyhttps::DownloadFileResult transferResult;
+
+    // Use in-process tinyhttps for all downloads (streaming progress).
+    // When a CancellationToken is available, wire isCancelled so ESC aborts.
+    {
+        tinyhttps::DownloadOptions opts;
+        opts.destFile = stagingFile;
+        opts.urls = std::move(urls);
+        opts.retryCount = 3;
+        opts.connectTimeoutSec = 30;
+        opts.maxTimeSec = 600;
+        opts.onProgress = onProgress;
+        if (testHooks) opts.transferOverride = testHooks->transferOverride;
+        if (cancel) {
+            opts.isCancelled = [cancel] { return cancel->is_paused() || cancel->is_cancelled(); };
+        }
+        // A stalled host is throttled for us right now, and a host that
+        // served bytes failing the integrity check is worse — demote both
+        // for the rest of the session so later downloads skip them.
+        opts.onUrlAttemptFailed = [](const std::string& u, const std::string& err) {
+            if (err.rfind("stalled:", 0) == 0
+                || err.rfind("sha256 mismatch", 0) == 0)
+                mirror::adaptive::penalize_host(u);
+        };
+        // Per-candidate integrity acceptance: verify INSIDE the URL loop
+        // so a mirror that wins the latency race but serves corrupted
+        // bytes is rejected and the next candidate (ultimately the
+        // author URL) is tried — previously a single mismatch failed the
+        // whole download with the remaining candidates untried.
+        if (!task.sha256.empty()) {
+            auto want = lower_hex_(task.sha256);
+            opts.onVerify = [stagingFile, want, &task](const std::string& u)
+                -> std::string {
+                auto digest = sha256::hex_file(stagingFile);
+                if (digest && *digest == want) return {};
+                return std::format(
+                    "sha256 mismatch for {} (source {}): got {}, want {}",
+                    task.name, u, digest ? *digest : "<unreadable>", want);
+            };
+        }
+
+        transferResult = tinyhttps::download_file(opts);
+        if (!transferResult.success) {
+            fs::remove(stagingFile, ec);
+            result.error = transferResult.error;
+            return result;
+        }
+        // Say so when the bytes did not come from where the plan said they
+        // would. A fallback that works silently is indistinguishable from a
+        // primary that works, right up until the day the fallback is the only
+        // thing holding the install together and nobody knew.
+        if (!transferResult.sourceUrl.empty()
+            && transferResult.sourceUrl != primaryUrl) {
+            log::info("[mirror] {} served by {}", task.name,
+                      transferResult.sourceUrl);
+        }
+    }
+
+    if (transferResult.expectedBytes
+            && transferResult.bytesWritten != *transferResult.expectedBytes) {
+        result.error = std::format(
+            "incomplete transfer for {}: wrote {} of {} bytes",
+            task.name, transferResult.bytesWritten,
+            *transferResult.expectedBytes);
+        fs::remove(stagingFile, ec);
+        return result;
+    }
+
+    // Size sanity check for archives without sha256. When a recipe
+    // omits sha256 we have no way to cross-check content authenticity,
+    // so a CDN serving 200 OK + a tiny error stub (e.g., gitcode's
+    // 9-byte "Not Found" body for missing release artifacts) would
+    // otherwise propagate to extract and fail there. Reject early so
+    // the error message points at the actual problem instead of a
+    // misleading libarchive "unrecognized format". Skip when sha256
+    // is declared — that's a stronger check than size alone.
+    if (task.sha256.empty() && looks_like_archive_filename_(destFile)) {
+        auto sz = fs::file_size(stagingFile, ec);
+        if (!ec && sz < kMinPlausibleArchiveBytes_) {
+            result.error = std::format(
+                "{}: downloaded payload is only {} bytes — likely an "
+                "error stub returned as 200 OK (no sha256 declared to "
+                "cross-check). URL: {}",
+                task.name, sz, task.url);
+            fs::remove(stagingFile, ec);
+            return result;
+        }
+    }
+
+    // Final SHA256 re-check (defense in depth — the per-candidate
+    // onVerify above already gated acceptance; in-process hash, no
+    // dependency on a host `sha256sum` binary, which stock macOS lacks).
+    if (!task.sha256.empty()) {
+        auto digest = sha256::hex_file(stagingFile);
+        if (!digest || *digest != lower_hex_(task.sha256)) {
+            result.error = std::format("SHA256 mismatch for {}", task.name);
+            fs::remove(stagingFile, ec);
+            return result;
+        }
+    }
+
+    std::string commitError;
+    if (!commit_staging_file_(stagingFile, destFile, commitError)) {
+        fs::remove(stagingFile, ec);
+        result.error = std::move(commitError);
+        return result;
+    }
+
+    if (task.sha256.empty()) {
+        // No sha256 declared: persist server-reported Last-Modified / ETag
+        // alongside the payload so the next install can use a HEAD probe
+        // to decide cache freshness instead of re-downloading.
+        tinyhttps::RemoteFileMeta committedMeta {
+            .ok = transferResult.success,
+            .contentLength = transferResult.expectedBytes.value_or(-1),
+            .lastModified = transferResult.lastModified,
+            .etag = transferResult.etag,
+        };
+        if (committedMeta.lastModified.empty() && committedMeta.etag.empty()
+                && !transferResult.expectedBytes && !probedMetaValid) {
+            probedMeta = query_remote_meta_(task.url, testHooks);
+            probedMetaValid = true;
+        }
+        if (committedMeta.lastModified.empty() && committedMeta.etag.empty()
+                && !transferResult.expectedBytes && probedMetaValid) {
+            committedMeta = probedMeta;
+        }
+        std::error_code sizeEc;
+        auto committedSize = static_cast<std::int64_t>(fs::file_size(destFile, sizeEc));
+        if (!sizeEc && !task.cacheIdentity.empty()) {
+            write_meta_sidecar_(
+                sidecarPath, committedMeta, committedSize,
+                task.cacheIdentity,
+                transferResult.finalUrl.empty()
+                    ? task.url : transferResult.finalUrl);
+        }
+    }
+
+    result.success = true;
+    return result;
+}
+
+std::vector<DownloadResult>
+download_all(std::span<const DownloadTask> tasks, const DownloaderConfig& config, DownloadProgressRenderer onRender, std::function<void(std::string_view name, float progress)> onProgress, CancellationToken* cancel) {
+
+    if (tasks.empty()) return {};
+
+    tinyhttps::global_init();
+
+    std::vector<DownloadResult> results(tasks.size());
+    std::mutex mutex;
+    std::condition_variable cv;
+    int activeCount = 0;
+    int maxConcur = std::max(1, config.maxConcurrency);
+
+    // Shared progress state for TUI
+    std::vector<TaskProgress> progState(tasks.size());
+    for (std::size_t i = 0; i < tasks.size(); ++i)
+        progState[i].name = tasks[i].name;
+
+    std::atomic<bool> allDone { false };
+    std::atomic<bool> sizesReady { false };
+
+    // A byte-count floor for the name column. The renderer re-measures it in
+    // display columns and fits it to the terminal — measuring here would
+    // mean pulling the UI's width table into core.
+    std::size_t nameWidth = 20;
+    for (auto& t : tasks) {
+        if (t.name.size() > nameWidth) nameWidth = t.name.size();
+    }
+    nameWidth += 2; // padding
+
+    // Background HEAD requests to pre-fetch Content-Length for byte-weighted progress.
+    // Runs in parallel with downloads — does not block startup.
+    std::jthread headThread([&]() {
+        std::vector<std::jthread> headWorkers;
+        headWorkers.reserve(tasks.size());
+        for (std::size_t i = 0; i < tasks.size(); ++i) {
+            if (is_git_url(tasks[i].url)) continue;
+            headWorkers.emplace_back([&, i]() {
+                auto len = tinyhttps::query_content_length(tasks[i].url);
+                if (len > 0) {
+                    std::lock_guard lock(mutex);
+                    // Only set if download hasn't already reported a size
+                    if (progState[i].totalBytes <= 0.0)
+                        progState[i].totalBytes = static_cast<double>(len);
+                }
+            });
+        }
+        // jthread destructors join all HEAD workers
+        headWorkers.clear();
+        sizesReady.store(true);
+    });
+
+    // TUI refresh thread: redraws progress every 200ms using FTXUI.
+    // Uses relative cursor movement (\033[<N>A) to overwrite previous frame in-place.
+    auto startTime = std::chrono::steady_clock::now();
+
+    bool canRewrite = palette::cursor_rewrite_allowed();
+    int lastLines = 0;  // lines rendered in previous frame (for cursor-up)
+
+    std::jthread tuiThread([&](std::stop_token stoken) {
+        if (!onRender) return;  // No renderer — skip TUI
+
+        // A destination that cannot be rewritten still deserves progress. It
+        // gets appended frames instead of overwritten ones, throttled so a CI
+        // log or an agent transcript collects a handful of updates rather than
+        // one every 200ms. What it must not get is what it got before: a
+        // silent wait for the whole download and a single frame at the end,
+        // which on a multi-minute install is indistinguishable from a hang.
+        const auto interval = canRewrite ? std::chrono::milliseconds(200)
+                                         : std::chrono::milliseconds(5000);
+        const auto still_running = [&] {
+            return !stoken.stop_requested() && !allDone.load()
+                && !(cancel && (cancel->is_paused() || cancel->is_cancelled()));
+        };
+
+        if (canRewrite) {
+            std::print("\033[?25l");
+            std::fflush(stdout);
+        }
+
+        while (still_running()) {
+            // Slice the wait so a finished or cancelled download is noticed
+            // promptly even on the slow append cadence.
+            for (auto waited = std::chrono::milliseconds(0);
+                 waited < interval && still_running();
+                 waited += std::chrono::milliseconds(50)) {
+                std::this_thread::sleep_for(std::chrono::milliseconds(50));
+            }
+            if (!still_running()) break;
+
+            auto elapsed = std::chrono::steady_clock::now() - startTime;
+            auto elapsedSec = std::chrono::duration<double>(elapsed).count();
+            {
+                std::lock_guard lock(mutex);
+                lastLines = onRender(progState, nameWidth, elapsedSec,
+                                     sizesReady.load(), canRewrite ? lastLines : 0);
+            }
+        }
+
+        // Final render
+        {
+            auto elapsed = std::chrono::steady_clock::now() - startTime;
+            auto elapsedSec = std::chrono::duration<double>(elapsed).count();
+            std::lock_guard lock(mutex);
+            onRender(progState, nameWidth, elapsedSec,
+                     sizesReady.load(), canRewrite ? lastLines : 0);
+        }
+        if (canRewrite) {
+            std::print("\033[?25h");
+            std::fflush(stdout);
+        }
+    });
+
+    std::vector<std::jthread> threads;
+    threads.reserve(tasks.size());
+
+    for (std::size_t i = 0; i < tasks.size(); ++i) {
+        threads.emplace_back([&, i]() {
+            // Wait for concurrency slot
+            {
+                std::unique_lock lock(mutex);
+                cv.wait(lock, [&] {
+                    return activeCount < maxConcur || (cancel && (cancel->is_paused() || cancel->is_cancelled()));
+                });
+                if (cancel && (cancel->is_paused() || cancel->is_cancelled())) {
+                    std::lock_guard lk(mutex);
+                    results[i].name = tasks[i].name;
+                    results[i].error = "cancelled";
+                    progState[i].finished = true;
+                    cv.notify_one();
+                    return;
+                }
+                ++activeCount;
+                progState[i].started = true;
+            }
+
+            if (onProgress) {
+                onProgress(tasks[i].name, 0.0f);
+            }
+
+            // Per-task progress callback updates shared state
+            auto taskProgress = [&](double total, double now) {
+                std::lock_guard lock(mutex);
+                progState[i].totalBytes = total;
+                progState[i].downloadedBytes = now;
+            };
+
+            auto result = download_one(tasks[i], taskProgress, cancel);
+
+            {
+                std::lock_guard lock(mutex);
+                progState[i].finished = true;
+                progState[i].success = result.success;
+                results[i] = std::move(result);
+                --activeCount;
+            }
+
+            if (onProgress) {
+                onProgress(tasks[i].name, results[i].success ? 1.0f : -1.0f);
+            }
+
+            cv.notify_one();
+        });
+    }
+
+    // jthread destructor joins automatically
+    threads.clear();
+    allDone.store(true);
+
+    // Stop TUI thread
+    tuiThread.request_stop();
+    tuiThread.join();
+
+    tinyhttps::global_cleanup();
+    return results;
+}
+
+}
diff --git a/src/core/xim/downloader.cppm b/src/core/xim/downloader.cppm
index 19707796..2a3396e8 100644
--- a/src/core/xim/downloader.cppm
+++ b/src/core/xim/downloader.cppm
@@ -7,37 +7,23 @@ export module xlings.core.xim.downloader;
 import std;
 import xlings.core.xim.libxpkg.types.type;
 import xlings.core.log;
-import xlings.core.palette;
-import xlings.core.compact;
-import xlings.platform;
 import xlings.core.config;
 import xlings.libs.tinyhttps;
 import xlings.runtime.cancellation;
 import xlings.core.mirror;
-import xlings.libs.sha256;
 // Re-export extract_archive so existing importers (installer) keep working.
 export import xlings.core.xim.extract;
 
 export namespace xlings::xim {
 
 // Check if a URL is a git repository URL
-bool is_git_url(const std::string& url) {
-    return url.ends_with(".git");
-}
+bool is_git_url(const std::string& url);
 
 // Filename-based archive sniff for the post-download sanity check
 // below. Kept here (not shared with installer.cppm::is_archive_) so this
 // module stays self-contained — the two predicates can diverge if a
 // downloader-specific format ever needs filtering.
-bool looks_like_archive_filename_(const std::filesystem::path& path) {
-    auto name = path.filename().string();
-    return name.ends_with(".tar.gz")
-        || name.ends_with(".tar.xz")
-        || name.ends_with(".tar.bz2")
-        || name.ends_with(".tar.zst")
-        || name.ends_with(".tgz")
-        || name.ends_with(".zip");
-}
+bool looks_like_archive_filename_(const std::filesystem::path& path);
 
 // Lower bound for what we accept as a real archive payload when there's
 // no sha256 to cross-check. Any compressed archive's own format header
@@ -55,12 +41,7 @@ constexpr std::uintmax_t kMinPlausibleArchiveBytes_ = 1024;
 
 // Lowercase a declared sha256 so it compares against our hex digests
 // regardless of the recipe author's casing.
-std::string lower_hex_(std::string_view s) {
-    std::string out(s);
-    for (auto& c : out)
-        if (c >= 'A' && c <= 'F') c = static_cast<char>(c - 'A' + 'a');
-    return out;
-}
+std::string lower_hex_(std::string_view s);
 
 // ── Sidecar (.meta) helpers for HEAD-based cache freshness ────────────
 //
@@ -84,207 +65,24 @@ struct MetaSidecar_ {
 
 std::filesystem::path unique_sibling_path_(
         const std::filesystem::path& base,
-        std::string_view marker) {
-    static std::atomic_uint64_t sequence { 0 };
-    auto path = base;
-    path += std::format(
-        ".{}.{}.{}", marker,
-        std::chrono::steady_clock::now().time_since_epoch().count(),
-        sequence.fetch_add(1));
-    return path;
-}
+        std::string_view marker);
 
 bool commit_staging_file_(const std::filesystem::path& staging,
                           const std::filesystem::path& destination,
                           std::string& error,
-                          bool failAfterBackupForTest = false) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    auto backup = unique_sibling_path_(destination, "old");
-    const bool hadDestination = fs::exists(destination, ec);
-    if (ec) {
-        error = std::format("failed to inspect {}: {}",
-                            destination.string(), ec.message());
-        return false;
-    }
-    if (hadDestination) {
-        fs::rename(destination, backup, ec);
-        if (ec) {
-            error = std::format("failed to preserve {}: {}",
-                                destination.string(), ec.message());
-            return false;
-        }
-    }
-    if (failAfterBackupForTest) {
-        if (hadDestination) {
-            fs::rename(backup, destination, ec);
-        }
-        error = "injected commit failure after backup";
-        return false;
-    }
-    fs::rename(staging, destination, ec);
-    if (ec) {
-        auto commitError = ec.message();
-        if (hadDestination) {
-            std::error_code restoreEc;
-            fs::rename(backup, destination, restoreEc);
-            if (restoreEc) {
-                error = std::format(
-                    "failed to commit {} ({}) and restore previous file ({})",
-                    destination.string(), commitError, restoreEc.message());
-                return false;
-            }
-        }
-        error = std::format("failed to commit {}: {}",
-                            destination.string(), commitError);
-        return false;
-    }
-    if (hadDestination) {
-        fs::remove(backup, ec);
-    }
-    return true;
-}
+                          bool failAfterBackupForTest = false);
 
 bool recover_download_transaction_(
         const std::filesystem::path& destination,
-        std::string& error) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    std::vector<fs::path> backups;
-    std::vector<fs::path> stagingFiles;
-    const auto backupPrefix = destination.filename().string() + ".old.";
-    const auto stagingPrefix = destination.filename().string() + ".part.";
-    auto parent = destination.parent_path();
-    for (auto it = fs::directory_iterator(parent, ec);
-         !ec && it != std::default_sentinel; it.increment(ec)) {
-        auto name = it->path().filename().string();
-        if (name.starts_with(backupPrefix)) backups.push_back(it->path());
-        else if (name.starts_with(stagingPrefix)) stagingFiles.push_back(it->path());
-    }
-    if (ec) {
-        error = std::format("failed to inspect download transaction for {}: {}",
-                            destination.string(), ec.message());
-        return false;
-    }
+        std::string& error);
 
-    std::ranges::sort(backups);
-    const bool liveExists = fs::exists(destination, ec);
-    if (ec) {
-        error = std::format("failed to inspect {}: {}",
-                            destination.string(), ec.message());
-        return false;
-    }
-    if (!liveExists && !backups.empty()) {
-        auto restore = backups.back();
-        backups.pop_back();
-        fs::rename(restore, destination, ec);
-        if (ec) {
-            error = std::format("failed to restore interrupted download {}: {}",
-                                destination.string(), ec.message());
-            return false;
-        }
-    }
-    for (const auto& path : backups) {
-        fs::remove(path, ec);
-        if (ec) {
-            error = std::format("failed to remove stale backup {}: {}",
-                                path.string(), ec.message());
-            return false;
-        }
-    }
-    for (const auto& path : stagingFiles) {
-        fs::remove(path, ec);
-        if (ec) {
-            error = std::format("failed to remove stale staging file {}: {}",
-                                path.string(), ec.message());
-            return false;
-        }
-    }
-    return true;
-}
-
-std::optional<MetaSidecar_> read_meta_sidecar_(const std::filesystem::path& p) {
-    std::ifstream in(p);
-    if (!in) return std::nullopt;
-    MetaSidecar_ m;
-    std::string line;
-    while (std::getline(in, line)) {
-        auto colon = line.find(':');
-        if (colon == std::string::npos) continue;
-        std::string key = line.substr(0, colon);
-        std::string val = line.substr(colon + 1);
-        // trim
-        auto trim = [](std::string& s) {
-            while (!s.empty() && (s.front() == ' ' || s.front() == '\t' || s.front() == '\r')) s.erase(s.begin());
-            while (!s.empty() && (s.back()  == ' ' || s.back()  == '\t' || s.back()  == '\r')) s.pop_back();
-        };
-        trim(key); trim(val);
-        for (auto& c : key) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
-        if (key == "format") {
-            int parsed {};
-            auto [ptr, err] = std::from_chars(val.data(), val.data() + val.size(), parsed);
-            if (err != std::errc{} || ptr != val.data() + val.size()) return std::nullopt;
-            m.format = parsed;
-        } else if (key == "complete") {
-            if (val == "true") m.complete = true;
-            else if (val == "false") m.complete = false;
-            else return std::nullopt;
-        } else if (key == "size") {
-            std::int64_t parsed {};
-            auto [ptr, err] = std::from_chars(val.data(), val.data() + val.size(), parsed);
-            if (err != std::errc{} || ptr != val.data() + val.size() || parsed < 0) {
-                return std::nullopt;
-            }
-            m.size = parsed;
-        } else if (key == "source-url") {
-            m.sourceUrl = std::move(val);
-        } else if (key == "cache-identity") {
-            m.cacheIdentity = std::move(val);
-        } else if (key == "last-modified") {
-            m.lastModified = std::move(val);
-        } else if (key == "etag") {
-            m.etag = std::move(val);
-        }
-    }
-    if (m.format != 1 && m.format != 2) return std::nullopt;
-    if (m.format == 2
-        && (!m.complete || m.size < 0 || m.cacheIdentity.empty())) {
-        return std::nullopt;
-    }
-    return m;
-}
+std::optional<MetaSidecar_> read_meta_sidecar_(const std::filesystem::path& p);
 
 bool write_meta_sidecar_(const std::filesystem::path& p,
                          const tinyhttps::RemoteFileMeta& meta,
                          std::int64_t size,
                          std::string_view cacheIdentity,
-                         std::string_view sourceUrl) {
-    auto staging = unique_sibling_path_(p, "tmp");
-    {
-        std::ofstream out(staging, std::ios::trunc);
-        if (!out) return false;
-        out << "format: 2\n";
-        out << "complete: true\n";
-        out << "size: " << size << "\n";
-        out << "source-url: " << sourceUrl << "\n";
-        out << "cache-identity: " << cacheIdentity << "\n";
-        if (!meta.lastModified.empty()) out << "last-modified: " << meta.lastModified << "\n";
-        if (!meta.etag.empty())         out << "etag: "          << meta.etag         << "\n";
-        out.flush();
-        if (!out) {
-            std::error_code ec;
-            std::filesystem::remove(staging, ec);
-            return false;
-        }
-    }
-    std::string error;
-    if (!commit_staging_file_(staging, p, error)) {
-        std::error_code ec;
-        std::filesystem::remove(staging, ec);
-        return false;
-    }
-    return true;
-}
+                         std::string_view sourceUrl);
 
 enum class CacheAdmission_ {
     Hit,
@@ -302,39 +100,7 @@ struct CacheAdmissionInput_ {
     std::string expectedCacheIdentity;
 };
 
-CacheAdmission_ decide_cache_admission_(const CacheAdmissionInput_& input) {
-    if (input.localSize <= 0) return CacheAdmission_::Redownload;
-
-    if (!input.headSucceeded) {
-        if (!input.sidecar) return CacheAdmission_::Redownload;
-        const auto& stored = *input.sidecar;
-        const bool committedV2 =
-            stored.format == 2
-            && stored.complete
-            && stored.size == input.localSize
-            && !input.expectedCacheIdentity.empty()
-            && stored.cacheIdentity == input.expectedCacheIdentity;
-        return committedV2
-            ? CacheAdmission_::OfflineUnverifiedHit
-            : CacheAdmission_::Redownload;
-    }
-
-    const bool sizeMatch =
-        input.remoteSize > 0 && input.remoteSize == input.localSize;
-    if (!sizeMatch) return CacheAdmission_::Redownload;
-
-    if (!input.sidecar) return CacheAdmission_::Hit;
-    const auto& stored = *input.sidecar;
-    const bool freshMatch =
-        (!input.remoteLastModified.empty()
-            && input.remoteLastModified == stored.lastModified)
-        || (!input.remoteEtag.empty() && input.remoteEtag == stored.etag);
-    const bool noFreshnessEvidence =
-        stored.lastModified.empty() && stored.etag.empty();
-    return (freshMatch || noFreshnessEvidence)
-        ? CacheAdmission_::Hit
-        : CacheAdmission_::Redownload;
-}
+CacheAdmission_ decide_cache_admission_(const CacheAdmissionInput_& input);
 
 struct DownloadTestHooks_ {
     std::function<tinyhttps::DownloadFileResult(
@@ -344,39 +110,16 @@ struct DownloadTestHooks_ {
 
 tinyhttps::RemoteFileMeta query_remote_meta_(
         const std::string& url,
-        const DownloadTestHooks_* hooks) {
-    if (hooks && hooks->queryRemoteMeta) return hooks->queryRemoteMeta(url);
-    return tinyhttps::query_remote_meta(url);
-}
+        const DownloadTestHooks_* hooks);
 
 // Derive the destination directory name from a git URL, e.g.
 // "https://github.com/user/repo.git" -> "repo" (or task.name fallback).
-std::string git_dest_repo_name_(const std::string& url, const std::string& fallback) {
-    std::string repoName;
-    auto lastSlash = url.rfind('/');
-    if (lastSlash != std::string::npos) {
-        repoName = url.substr(lastSlash + 1);
-        if (repoName.ends_with(".git"))
-            repoName = repoName.substr(0, repoName.size() - 4);
-    }
-    return repoName.empty() ? fallback : repoName;
-}
+std::string git_dest_repo_name_(const std::string& url, const std::string& fallback);
 
 // Build the ordered list of git clone URLs to try: primary + author-
 // declared fallbacks + mirror expansions. Mirror::expand handles the
 // Mode::Off / non-GitHub passthrough cases internally.
-std::vector<std::string> git_candidate_urls_(const DownloadTask& task) {
-    std::vector<std::string> urls;
-    urls.push_back(task.url);
-    for (auto& fb : task.fallbackUrls) urls.push_back(fb);
-
-    auto mirrored = mirror::expand(task.url, {.type = mirror::ResourceType::Git});
-    for (auto& u : mirrored) {
-        if (std::ranges::find(urls, u) == urls.end())
-            urls.push_back(std::move(u));
-    }
-    return urls;
-}
+std::vector<std::string> git_candidate_urls_(const DownloadTask& task);
 
 // Atomically replace `live` with `staging`: live -> live.old,
 // staging -> live, drop live.old. Any failure restores/keeps the previous
@@ -386,25 +129,7 @@ std::vector<std::string> git_candidate_urls_(const DownloadTask& task) {
 // interrupted re-clone left nothing behind and the error surfaced much
 // later at catalog build.)
 bool atomic_swap_dir_(const std::filesystem::path& staging,
-                      const std::filesystem::path& live) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    auto old = live.parent_path() / (live.filename().string() + ".old");
-    fs::remove_all(old, ec);          // crashed-run leftovers
-    ec.clear();
-    if (fs::exists(live)) {
-        fs::rename(live, old, ec);
-        if (ec) return false;
-    }
-    fs::rename(staging, live, ec);
-    if (ec) {
-        std::error_code ec2;
-        fs::rename(old, live, ec2);   // best-effort restore
-        return false;
-    }
-    fs::remove_all(old, ec);
-    return true;
-}
+                      const std::filesystem::path& live);
 
 // Clone a git repository, trying the primary URL then mirror fallbacks.
 // Acquisition is STAGED: clones land in a sibling .staging dir and are
@@ -412,440 +137,13 @@ bool atomic_swap_dir_(const std::filesystem::path& staging,
 // never removed first. When a previous copy exists and every URL fails,
 // the previous copy is kept (stale-but-consistent beats absent) with a
 // loud warning at fetch time.
-DownloadResult git_clone_one(const DownloadTask& task) {
-    namespace fs = std::filesystem;
-
-    DownloadResult result;
-    result.name = task.name;
-
-    std::error_code ec;
-    fs::create_directories(task.destDir, ec);
-    if (ec) {
-        result.error = std::format("failed to create directory {}: {}",
-                                   task.destDir.string(), ec.message());
-        return result;
-    }
-
-    auto repoName = git_dest_repo_name_(task.url, task.name);
-    auto destDir = task.destDir / repoName;
-    result.localFile = destDir;
-
-    // If already cloned, pull latest. Pull is single-URL by design — we
-    // don't switch remotes here. Pull failure falls through to a STAGED
-    // re-clone; the live tree stays untouched until a replacement is ready.
-    const bool hadLive = fs::exists(destDir / ".git");
-    if (hadLive) {
-        log::debug("already cloned {}, pulling latest...", task.name);
-        auto pull = compact::git::pull_ff_only(destDir);
-        if (pull.rc == 0) {
-            result.success = true;
-            return result;
-        }
-        log::warn("pull failed for {}, re-cloning into staging...", task.name);
-    }
-
-    auto staging = task.destDir / (".staging-" + repoName);
-    ec.clear();
-    fs::remove_all(staging, ec);      // crashed-run leftovers
-
-    auto urls = git_candidate_urls_(task);
-    for (std::size_t i = 0; i < urls.size(); ++i) {
-        const auto& url = urls[i];
-        log::debug("cloning {} attempt {}/{}: {}",
-                   task.name, i + 1, urls.size(), url);
-        auto clone = compact::git::clone_shallow(url, staging, true);
-        if (clone.rc == 0 && fs::exists(staging / ".git")) {
-            if (i > 0)
-                log::info("[mirror] git clone fallback succeeded via {}", url);
-            if (atomic_swap_dir_(staging, destDir)) {
-                result.success = true;
-                return result;
-            }
-            log::warn("atomic swap failed for {}", task.name);
-        }
-        // Clean partial staging clone before next attempt.
-        ec.clear();
-        fs::remove_all(staging, ec);
-    }
-
-    if (hadLive) {
-        // Every URL failed but a previous copy exists: keep serving it.
-        log::warn("{}: refresh failed on all URLs; keeping the previous copy",
-                  task.name);
-        result.success = true;
-        return result;
-    }
-    result.error = std::format("all git clone URLs failed for {}", task.name);
-    return result;
-}
+DownloadResult git_clone_one(const DownloadTask& task);
 
 // Download a single file using libcurl with real-time progress callback.
 DownloadResult download_one(const DownloadTask& task,
                             std::function<void(double total, double now)> onProgress = nullptr,
                             CancellationToken* cancel = nullptr,
-                            const DownloadTestHooks_* testHooks = nullptr) {
-    namespace fs = std::filesystem;
-
-    DownloadResult result;
-    result.name = task.name;
-
-    // Ensure dest directory exists
-    std::error_code ec;
-    fs::create_directories(task.destDir, ec);
-    if (ec) {
-        result.error = std::format("failed to create directory {}: {}",
-                                   task.destDir.string(), ec.message());
-        return result;
-    }
-
-    // Git clone for .git URLs. The non-cancellable path delegates to
-    // git_clone_one which already handles mirror fallback; the cancellable
-    // path needs the same fallback wiring inline because it uses
-    // spawn_command/wait_or_kill instead of blocking exec.
-    if (is_git_url(task.url)) {
-        if (cancel) {
-            namespace fs = std::filesystem;
-            auto repoName = git_dest_repo_name_(task.url, task.name);
-            auto destDir = task.destDir / repoName;
-            result.localFile = destDir;
-
-            // Staged acquisition, mirroring git_clone_one: clone into a
-            // sibling .staging dir, atomic-swap on success, and keep any
-            // previous live copy when every URL fails (or on cancel).
-            const bool hadLive = fs::exists(destDir / ".git");
-            auto staging = task.destDir / (".staging-" + repoName);
-            std::error_code ecs;
-            fs::remove_all(staging, ecs);
-
-            auto urls = git_candidate_urls_(task);
-            std::string lastError;
-            for (std::size_t i = 0; i < urls.size(); ++i) {
-                const auto& url = urls[i];
-                log::debug("cloning {} (cancellable) attempt {}/{}: {}",
-                           task.name, i + 1, urls.size(), url);
-                auto h = compact::git::spawn({
-                    "clone", "--depth", "1", "--recursive", "--quiet",
-                    url, staging.string()
-                });
-                if (h.pid <= 0) { lastError = "failed to spawn git"; continue; }
-                auto [code, output] = platform::wait_or_kill(
-                    h, cancel, std::chrono::minutes{10});
-                if (cancel->is_paused() || cancel->is_cancelled()) {
-                    fs::remove_all(staging, ecs);
-                    result.error = "cancelled";
-                    return result;
-                }
-                if (code == 0 && fs::exists(staging / ".git")
-                    && atomic_swap_dir_(staging, destDir)) {
-                    if (i > 0)
-                        log::info("[mirror] git clone fallback succeeded via {}", url);
-                    result.success = true;
-                    return result;
-                }
-                lastError = output;
-                fs::remove_all(staging, ecs);
-            }
-            if (hadLive) {
-                log::warn("{}: refresh failed on all URLs; keeping the previous copy",
-                          task.name);
-                result.success = true;
-                return result;
-            }
-            result.error = lastError.empty()
-                ? std::format("all git clone URLs failed for {}", task.name)
-                : lastError;
-            return result;
-        }
-        return git_clone_one(task);
-    }
-
-    log::debug("downloading {} from {}", task.name, task.url);
-
-    // Extract filename from URL
-    std::string url = task.url;
-    std::string filename;
-    auto lastSlash = url.rfind('/');
-    if (lastSlash != std::string::npos) {
-        filename = url.substr(lastSlash + 1);
-        auto q = filename.find('?');
-        if (q != std::string::npos) filename = filename.substr(0, q);
-    }
-    if (filename.empty()) filename = task.name + ".download";
-
-    auto destFile = task.destDir / filename;
-    auto sidecarPath = destFile;
-    sidecarPath += ".meta";
-    result.localFile = destFile;
-
-    auto lockPath = destFile;
-    lockPath += ".lock";
-    platform::FileLock cacheLock;
-    std::string lockError;
-    auto cancelled = [cancel] {
-        return cancel && (cancel->is_paused() || cancel->is_cancelled());
-    };
-    if (!cacheLock.acquire(
-            lockPath, std::chrono::minutes{10}, cancelled, lockError)) {
-        result.error = std::move(lockError);
-        return result;
-    }
-    if (!recover_download_transaction_(destFile, lockError)) {
-        result.error = std::move(lockError);
-        return result;
-    }
-
-    // ── Cache hit path 1: sha256 verified (cheapest, most reliable) ──
-    // If the recipe declares a sha256 and the on-disk file matches, we're
-    // byte-identical to upstream — skip download outright.
-    if (fs::exists(destFile) && !task.sha256.empty()) {
-        // In-process hash — `sha256sum` is a coreutils tool absent on
-        // stock macOS, where shelling out made every pinned download
-        // "mismatch" (see xlings.libs.sha256 header).
-        auto digest = sha256::hex_file(destFile);
-        if (digest && *digest == lower_hex_(task.sha256)) {
-            log::debug("already downloaded (sha256): {}", destFile.string());
-            result.success = true;
-            return result;
-        }
-        // sha mismatch: stale/corrupt cache. Remove before falling through
-        // so the next download_to_file starts from a clean slate (defends
-        // against a future tinyhttps that might enable Range/resume).
-        // Keep the previous file until a verified replacement is ready.
-    }
-
-    // ── Cache hit path 2: HEAD-based freshness (when sha256 is unset) ──
-    // Trade a tiny HEAD round-trip for not re-downloading toolchain-sized
-    // payloads on every `xlings install`. We only consult this when the
-    // recipe omits sha256 — otherwise path 1 already decided.
-    tinyhttps::RemoteFileMeta probedMeta;
-    bool probedMetaValid = false;
-    if (fs::exists(destFile) && task.sha256.empty()) {
-        probedMeta = query_remote_meta_(task.url, testHooks);
-        probedMetaValid = true;
-
-        if (probedMeta.ok) {
-            std::error_code sec;
-            auto localSize = static_cast<std::int64_t>(fs::file_size(destFile, sec));
-            auto admission = decide_cache_admission_({
-                .localSize = sec ? -1 : localSize,
-                .headSucceeded = true,
-                .remoteSize = probedMeta.contentLength,
-                .remoteLastModified = probedMeta.lastModified,
-                .remoteEtag = probedMeta.etag,
-                .sidecar = read_meta_sidecar_(sidecarPath),
-                .expectedCacheIdentity = task.cacheIdentity,
-            });
-            if (admission == CacheAdmission_::Hit) {
-                log::debug("already downloaded (HEAD cache hit, size={}): {}",
-                           localSize, destFile.string());
-                result.success = true;
-                return result;
-            }
-            // Stale: retain the previous committed pair until the replacement
-            // has transferred and passed all acceptance checks.
-        } else {
-            std::error_code sec;
-            auto localSize = static_cast<std::int64_t>(fs::file_size(destFile, sec));
-            auto admission = decide_cache_admission_({
-                .localSize = sec ? -1 : localSize,
-                .headSucceeded = false,
-                .sidecar = read_meta_sidecar_(sidecarPath),
-                .expectedCacheIdentity = task.cacheIdentity,
-            });
-            if (admission == CacheAdmission_::OfflineUnverifiedHit) {
-                log::warn("HEAD probe failed for {} ({}); using transaction-committed "
-                          "cache without cryptographic verification: {}",
-                          task.url,
-                          probedMeta.error.empty() ? "unknown" : probedMeta.error,
-                          destFile.string());
-                result.success = true;
-                return result;
-            }
-        }
-    }
-
-    // Build ordered list of URLs to try:
-    //   1. primary URL (as-is)
-    //   2. package-author-declared fallback URLs (already mirror-selected
-    //      by upstream resolver)
-    //   3. github mirror fallbacks (only appended if URL is github.com/
-    //      raw.githubusercontent.com/etc and mirror mode != Off)
-    std::vector<std::string> urls;
-    urls.push_back(url);
-    for (auto& fb : task.fallbackUrls) urls.push_back(fb);
-
-    auto mirrored = mirror::expand(url);
-    for (auto& u : mirrored) {
-        if (std::ranges::find(urls, u) == urls.end())
-            urls.push_back(std::move(u));
-    }
-
-    // Adaptive ordering (0.4.49): probe candidate hosts' connect latency
-    // (memoized per process) and order accordingly. With a declared sha256
-    // the bytes are pinned, so faster mirrors may be tried before the
-    // original URL; without one the author-declared URL stays first unless
-    // its host is unreachable/penalized. See
-    // .agents/docs/2026-06-04-github-asset-adaptive-mirror.md.
-    urls = mirror::adaptive::reorder(std::move(urls), !task.sha256.empty());
-
-    // Which sources are in play, in the order they will be tried. When a
-    // download is slow or 404s, the first question is always "where is it
-    // even pulling from, and what else could it have used" -- and until now
-    // nothing answered it, so a CN outage looked like a dead package rather
-    // than a mirror with a gap.
-    if (urls.size() > 1) {
-        std::string candidates;
-        for (const auto& u : urls) {
-            if (!candidates.empty()) candidates += "\n    ";
-            candidates += u;
-        }
-        log::debug("[download] {} candidates ({}):\n    {}",
-                   task.name, urls.size(), candidates);
-    }
-    const std::string primaryUrl = urls.front();
-
-    auto stagingFile = unique_sibling_path_(destFile, "part");
-    tinyhttps::DownloadFileResult transferResult;
-
-    // Use in-process tinyhttps for all downloads (streaming progress).
-    // When a CancellationToken is available, wire isCancelled so ESC aborts.
-    {
-        tinyhttps::DownloadOptions opts;
-        opts.destFile = stagingFile;
-        opts.urls = std::move(urls);
-        opts.retryCount = 3;
-        opts.connectTimeoutSec = 30;
-        opts.maxTimeSec = 600;
-        opts.onProgress = onProgress;
-        if (testHooks) opts.transferOverride = testHooks->transferOverride;
-        if (cancel) {
-            opts.isCancelled = [cancel] { return cancel->is_paused() || cancel->is_cancelled(); };
-        }
-        // A stalled host is throttled for us right now, and a host that
-        // served bytes failing the integrity check is worse — demote both
-        // for the rest of the session so later downloads skip them.
-        opts.onUrlAttemptFailed = [](const std::string& u, const std::string& err) {
-            if (err.rfind("stalled:", 0) == 0
-                || err.rfind("sha256 mismatch", 0) == 0)
-                mirror::adaptive::penalize_host(u);
-        };
-        // Per-candidate integrity acceptance: verify INSIDE the URL loop
-        // so a mirror that wins the latency race but serves corrupted
-        // bytes is rejected and the next candidate (ultimately the
-        // author URL) is tried — previously a single mismatch failed the
-        // whole download with the remaining candidates untried.
-        if (!task.sha256.empty()) {
-            auto want = lower_hex_(task.sha256);
-            opts.onVerify = [stagingFile, want, &task](const std::string& u)
-                -> std::string {
-                auto digest = sha256::hex_file(stagingFile);
-                if (digest && *digest == want) return {};
-                return std::format(
-                    "sha256 mismatch for {} (source {}): got {}, want {}",
-                    task.name, u, digest ? *digest : "<unreadable>", want);
-            };
-        }
-
-        transferResult = tinyhttps::download_file(opts);
-        if (!transferResult.success) {
-            fs::remove(stagingFile, ec);
-            result.error = transferResult.error;
-            return result;
-        }
-        // Say so when the bytes did not come from where the plan said they
-        // would. A fallback that works silently is indistinguishable from a
-        // primary that works, right up until the day the fallback is the only
-        // thing holding the install together and nobody knew.
-        if (!transferResult.sourceUrl.empty()
-            && transferResult.sourceUrl != primaryUrl) {
-            log::info("[mirror] {} served by {}", task.name,
-                      transferResult.sourceUrl);
-        }
-    }
-
-    if (transferResult.expectedBytes
-            && transferResult.bytesWritten != *transferResult.expectedBytes) {
-        result.error = std::format(
-            "incomplete transfer for {}: wrote {} of {} bytes",
-            task.name, transferResult.bytesWritten,
-            *transferResult.expectedBytes);
-        fs::remove(stagingFile, ec);
-        return result;
-    }
-
-    // Size sanity check for archives without sha256. When a recipe
-    // omits sha256 we have no way to cross-check content authenticity,
-    // so a CDN serving 200 OK + a tiny error stub (e.g., gitcode's
-    // 9-byte "Not Found" body for missing release artifacts) would
-    // otherwise propagate to extract and fail there. Reject early so
-    // the error message points at the actual problem instead of a
-    // misleading libarchive "unrecognized format". Skip when sha256
-    // is declared — that's a stronger check than size alone.
-    if (task.sha256.empty() && looks_like_archive_filename_(destFile)) {
-        auto sz = fs::file_size(stagingFile, ec);
-        if (!ec && sz < kMinPlausibleArchiveBytes_) {
-            result.error = std::format(
-                "{}: downloaded payload is only {} bytes — likely an "
-                "error stub returned as 200 OK (no sha256 declared to "
-                "cross-check). URL: {}",
-                task.name, sz, task.url);
-            fs::remove(stagingFile, ec);
-            return result;
-        }
-    }
-
-    // Final SHA256 re-check (defense in depth — the per-candidate
-    // onVerify above already gated acceptance; in-process hash, no
-    // dependency on a host `sha256sum` binary, which stock macOS lacks).
-    if (!task.sha256.empty()) {
-        auto digest = sha256::hex_file(stagingFile);
-        if (!digest || *digest != lower_hex_(task.sha256)) {
-            result.error = std::format("SHA256 mismatch for {}", task.name);
-            fs::remove(stagingFile, ec);
-            return result;
-        }
-    }
-
-    std::string commitError;
-    if (!commit_staging_file_(stagingFile, destFile, commitError)) {
-        fs::remove(stagingFile, ec);
-        result.error = std::move(commitError);
-        return result;
-    }
-
-    if (task.sha256.empty()) {
-        // No sha256 declared: persist server-reported Last-Modified / ETag
-        // alongside the payload so the next install can use a HEAD probe
-        // to decide cache freshness instead of re-downloading.
-        tinyhttps::RemoteFileMeta committedMeta {
-            .ok = transferResult.success,
-            .contentLength = transferResult.expectedBytes.value_or(-1),
-            .lastModified = transferResult.lastModified,
-            .etag = transferResult.etag,
-        };
-        if (committedMeta.lastModified.empty() && committedMeta.etag.empty()
-                && !transferResult.expectedBytes && !probedMetaValid) {
-            probedMeta = query_remote_meta_(task.url, testHooks);
-            probedMetaValid = true;
-        }
-        if (committedMeta.lastModified.empty() && committedMeta.etag.empty()
-                && !transferResult.expectedBytes && probedMetaValid) {
-            committedMeta = probedMeta;
-        }
-        std::error_code sizeEc;
-        auto committedSize = static_cast<std::int64_t>(fs::file_size(destFile, sizeEc));
-        if (!sizeEc && !task.cacheIdentity.empty()) {
-            write_meta_sidecar_(
-                sidecarPath, committedMeta, committedSize,
-                task.cacheIdentity,
-                transferResult.finalUrl.empty()
-                    ? task.url : transferResult.finalUrl);
-        }
-    }
-
-    result.success = true;
-    return result;
-}
+                            const DownloadTestHooks_* testHooks = nullptr);
 
 // Per-task progress state, shared between download threads and the TUI refresh thread
 struct TaskProgress {
@@ -876,181 +174,7 @@ download_all(std::span<const DownloadTask> tasks,
              const DownloaderConfig& config,
              DownloadProgressRenderer onRender,
              std::function<void(std::string_view name, float progress)> onProgress,
-             CancellationToken* cancel = nullptr) {
-
-    if (tasks.empty()) return {};
-
-    tinyhttps::global_init();
-
-    std::vector<DownloadResult> results(tasks.size());
-    std::mutex mutex;
-    std::condition_variable cv;
-    int activeCount = 0;
-    int maxConcur = std::max(1, config.maxConcurrency);
-
-    // Shared progress state for TUI
-    std::vector<TaskProgress> progState(tasks.size());
-    for (std::size_t i = 0; i < tasks.size(); ++i)
-        progState[i].name = tasks[i].name;
-
-    std::atomic<bool> allDone { false };
-    std::atomic<bool> sizesReady { false };
-
-    // A byte-count floor for the name column. The renderer re-measures it in
-    // display columns and fits it to the terminal — measuring here would
-    // mean pulling the UI's width table into core.
-    std::size_t nameWidth = 20;
-    for (auto& t : tasks) {
-        if (t.name.size() > nameWidth) nameWidth = t.name.size();
-    }
-    nameWidth += 2; // padding
-
-    // Background HEAD requests to pre-fetch Content-Length for byte-weighted progress.
-    // Runs in parallel with downloads — does not block startup.
-    std::jthread headThread([&]() {
-        std::vector<std::jthread> headWorkers;
-        headWorkers.reserve(tasks.size());
-        for (std::size_t i = 0; i < tasks.size(); ++i) {
-            if (is_git_url(tasks[i].url)) continue;
-            headWorkers.emplace_back([&, i]() {
-                auto len = tinyhttps::query_content_length(tasks[i].url);
-                if (len > 0) {
-                    std::lock_guard lock(mutex);
-                    // Only set if download hasn't already reported a size
-                    if (progState[i].totalBytes <= 0.0)
-                        progState[i].totalBytes = static_cast<double>(len);
-                }
-            });
-        }
-        // jthread destructors join all HEAD workers
-        headWorkers.clear();
-        sizesReady.store(true);
-    });
-
-    // TUI refresh thread: redraws progress every 200ms using FTXUI.
-    // Uses relative cursor movement (\033[<N>A) to overwrite previous frame in-place.
-    auto startTime = std::chrono::steady_clock::now();
-
-    bool canRewrite = palette::cursor_rewrite_allowed();
-    int lastLines = 0;  // lines rendered in previous frame (for cursor-up)
-
-    std::jthread tuiThread([&](std::stop_token stoken) {
-        if (!onRender) return;  // No renderer — skip TUI
-
-        // A destination that cannot be rewritten still deserves progress. It
-        // gets appended frames instead of overwritten ones, throttled so a CI
-        // log or an agent transcript collects a handful of updates rather than
-        // one every 200ms. What it must not get is what it got before: a
-        // silent wait for the whole download and a single frame at the end,
-        // which on a multi-minute install is indistinguishable from a hang.
-        const auto interval = canRewrite ? std::chrono::milliseconds(200)
-                                         : std::chrono::milliseconds(5000);
-        const auto still_running = [&] {
-            return !stoken.stop_requested() && !allDone.load()
-                && !(cancel && (cancel->is_paused() || cancel->is_cancelled()));
-        };
-
-        if (canRewrite) {
-            std::print("\033[?25l");
-            std::fflush(stdout);
-        }
-
-        while (still_running()) {
-            // Slice the wait so a finished or cancelled download is noticed
-            // promptly even on the slow append cadence.
-            for (auto waited = std::chrono::milliseconds(0);
-                 waited < interval && still_running();
-                 waited += std::chrono::milliseconds(50)) {
-                std::this_thread::sleep_for(std::chrono::milliseconds(50));
-            }
-            if (!still_running()) break;
-
-            auto elapsed = std::chrono::steady_clock::now() - startTime;
-            auto elapsedSec = std::chrono::duration<double>(elapsed).count();
-            {
-                std::lock_guard lock(mutex);
-                lastLines = onRender(progState, nameWidth, elapsedSec,
-                                     sizesReady.load(), canRewrite ? lastLines : 0);
-            }
-        }
-
-        // Final render
-        {
-            auto elapsed = std::chrono::steady_clock::now() - startTime;
-            auto elapsedSec = std::chrono::duration<double>(elapsed).count();
-            std::lock_guard lock(mutex);
-            onRender(progState, nameWidth, elapsedSec,
-                     sizesReady.load(), canRewrite ? lastLines : 0);
-        }
-        if (canRewrite) {
-            std::print("\033[?25h");
-            std::fflush(stdout);
-        }
-    });
-
-    std::vector<std::jthread> threads;
-    threads.reserve(tasks.size());
-
-    for (std::size_t i = 0; i < tasks.size(); ++i) {
-        threads.emplace_back([&, i]() {
-            // Wait for concurrency slot
-            {
-                std::unique_lock lock(mutex);
-                cv.wait(lock, [&] {
-                    return activeCount < maxConcur || (cancel && (cancel->is_paused() || cancel->is_cancelled()));
-                });
-                if (cancel && (cancel->is_paused() || cancel->is_cancelled())) {
-                    std::lock_guard lk(mutex);
-                    results[i].name = tasks[i].name;
-                    results[i].error = "cancelled";
-                    progState[i].finished = true;
-                    cv.notify_one();
-                    return;
-                }
-                ++activeCount;
-                progState[i].started = true;
-            }
-
-            if (onProgress) {
-                onProgress(tasks[i].name, 0.0f);
-            }
-
-            // Per-task progress callback updates shared state
-            auto taskProgress = [&](double total, double now) {
-                std::lock_guard lock(mutex);
-                progState[i].totalBytes = total;
-                progState[i].downloadedBytes = now;
-            };
-
-            auto result = download_one(tasks[i], taskProgress, cancel);
-
-            {
-                std::lock_guard lock(mutex);
-                progState[i].finished = true;
-                progState[i].success = result.success;
-                results[i] = std::move(result);
-                --activeCount;
-            }
-
-            if (onProgress) {
-                onProgress(tasks[i].name, results[i].success ? 1.0f : -1.0f);
-            }
-
-            cv.notify_one();
-        });
-    }
-
-    // jthread destructor joins automatically
-    threads.clear();
-    allDone.store(true);
-
-    // Stop TUI thread
-    tuiThread.request_stop();
-    tuiThread.join();
-
-    tinyhttps::global_cleanup();
-    return results;
-}
+             CancellationToken* cancel = nullptr);
 
 // extract_archive lives in xlings.core.xim.extract (libarchive-backed).
 // Re-exported above so existing importers keep working without changes.
diff --git a/src/core/xim/extract.cpp b/src/core/xim/extract.cpp
new file mode 100644
index 00000000..28f124b4
--- /dev/null
+++ b/src/core/xim/extract.cpp
@@ -0,0 +1,311 @@
+module;
+
+#include <archive.h>
+#include <archive_entry.h>
+#include <clocale>
+
+module xlings.core.xim.extract;
+
+import std;
+
+namespace xlings::xim {
+
+namespace detail_ {
+
+std::expected<std::string, std::string>
+check_safe_pathname_(const char* raw) {
+    if (!raw || !*raw) return std::unexpected("empty pathname");
+    std::string_view sv{raw};
+    if (sv.front() == '/' || (sv.size() >= 3 && sv[1] == ':')) {  // POSIX abs or Windows X:
+        return std::unexpected(std::format("absolute path rejected: {}", sv));
+    }
+    // Block entries that explicitly try to climb out of the staging tree.
+    // libarchive does its own check at extraction time too; this is a
+    // belt-and-braces gate.
+    for (std::size_t i = 0; i + 1 < sv.size(); ++i) {
+        if (sv[i] == '.' && sv[i+1] == '.'
+            && (i == 0 || sv[i-1] == '/' || sv[i-1] == '\\')
+            && (i+2 == sv.size() || sv[i+2] == '/' || sv[i+2] == '\\')) {
+            return std::unexpected(std::format("dot-dot path rejected: {}", sv));
+        }
+    }
+    return std::string{sv};
+}
+
+std::string path_from_wide_(const wchar_t* raw) {
+    if (!raw || !*raw) return {};
+    try {
+        return std::filesystem::path(std::wstring(raw)).generic_string();
+    } catch (...) {
+        return {};
+    }
+}
+
+std::string entry_pathname_(archive_entry* entry) {
+    if (auto* path = ::archive_entry_pathname_utf8(entry); path && *path) {
+        return std::string(path);
+    }
+    if (auto* path = ::archive_entry_pathname(entry); path && *path) {
+        return std::string(path);
+    }
+    return path_from_wide_(::archive_entry_pathname_w(entry));
+}
+
+std::string entry_hardlink_(archive_entry* entry) {
+    if (auto* path = ::archive_entry_hardlink_utf8(entry); path && *path) {
+        return std::string(path);
+    }
+    if (auto* path = ::archive_entry_hardlink(entry); path && *path) {
+        return std::string(path);
+    }
+    return path_from_wide_(::archive_entry_hardlink_w(entry));
+}
+
+std::string libarchive_error_(struct archive* a) {
+    if (auto* msg = ::archive_error_string(a); msg && *msg) {
+        return msg;
+    }
+    return "unknown libarchive error";
+}
+
+// User/group lookup callbacks for archive_write_disk that always return
+// 0 (root). Wired into archive_write_disk_set_user_lookup so libarchive
+// never falls back to getpwnam_r/getgrnam_r — see the call site for the
+// rationale.
+//
+// Signature matches libarchive's `archive_write_disk_set_user_lookup` /
+// `set_group_lookup` callback type:
+//     la_int64_t (*lookup)(void* private_data, const char* name, la_int64_t id);
+la_int64_t const_root_lookup_uid_(void*, const char*, la_int64_t) { return 0; }
+
+la_int64_t const_root_lookup_gid_(void*, const char*, la_int64_t) { return 0; }
+
+// Read each block of an entry's payload from `src` and write to `dst`.
+std::expected<void, ExtractError>
+copy_entry_data_(struct archive* src, struct archive* dst) {
+    const void* buff = nullptr;
+    std::size_t size = 0;
+    la_int64_t offset = 0;
+    for (;;) {
+        int r = ::archive_read_data_block(src, &buff, &size, &offset);
+        if (r == ARCHIVE_EOF) return {};
+        if (r < ARCHIVE_OK) {
+            return std::unexpected(ExtractError{
+                ExtractErrorKind::InvalidInputArchive,
+                "read_data_block: " + libarchive_error_(src)});
+        }
+        r = ::archive_write_data_block(dst, buff, size, offset);
+        if (r < ARCHIVE_OK) {
+            return std::unexpected(ExtractError{
+                ExtractErrorKind::LocalWriteFailure,
+                "write_data_block: " + libarchive_error_(dst)});
+        }
+    }
+}
+
+void ensure_archive_locale_() {
+    static std::once_flag once;
+    std::call_once(once, [] {
+#ifdef _WIN32
+        if (!std::setlocale(LC_CTYPE, ".UTF-8")) {
+            std::setlocale(LC_CTYPE, "");
+        }
+#else
+        if (!std::setlocale(LC_CTYPE, "C.UTF-8")
+            && !std::setlocale(LC_CTYPE, "en_US.UTF-8")) {
+            std::setlocale(LC_CTYPE, "");
+        }
+#endif
+    });
+}
+
+}
+
+std::expected<std::filesystem::path, ExtractError>
+extract_archive_detailed(const std::filesystem::path& archive,
+                         const std::filesystem::path& destDir) {
+    namespace fs = std::filesystem;
+    detail_::ensure_archive_locale_();
+
+    std::error_code ec;
+    fs::create_directories(destDir, ec);
+    if (ec) {
+        return std::unexpected(ExtractError{
+            ExtractErrorKind::LocalWriteFailure,
+            std::format("create_directories({}) failed: {}",
+                        destDir.string(), ec.message())});
+    }
+
+    if (!fs::exists(archive)) {
+        return std::unexpected(ExtractError{
+            ExtractErrorKind::InvalidInputArchive,
+            std::format("archive does not exist: {}", archive.string())});
+    }
+
+    // Resolve symlinks in the destination root before handing paths to
+    // libarchive. macOS exposes the temp dir under /var → /private/var,
+    // and ARCHIVE_EXTRACT_SECURE_SYMLINKS refuses to write through any
+    // symlink on the path. weakly_canonical follows existing prefix
+    // links and leaves not-yet-created tail components alone.
+    auto canonicalDest = fs::weakly_canonical(destDir, ec);
+    if (ec) canonicalDest = destDir;  // fall back if canonicalization fails
+
+    struct archive* src = ::archive_read_new();
+    struct archive* dst = ::archive_write_disk_new();
+
+    auto cleanup = [&] {
+        if (src) {
+            ::archive_read_close(src);
+            ::archive_read_free(src);
+            src = nullptr;
+        }
+        if (dst) {
+            ::archive_write_close(dst);
+            ::archive_write_free(dst);
+            dst = nullptr;
+        }
+    };
+
+    if (!src || !dst) {
+        cleanup();
+        return std::unexpected(ExtractError{
+            ExtractErrorKind::Internal,
+            "libarchive: failed to allocate handles"});
+    }
+
+    ::archive_read_support_filter_all(src);
+    ::archive_read_support_format_all(src);
+    ::archive_read_set_format_option(src, "zip", "hdrcharset", "UTF-8");
+    ::archive_write_disk_set_options(dst, detail_::kWriteFlags);
+
+    // Custom user/group lookup that always returns 0 (root). xim-pkgindex
+    // tarballs are packed root:root by convention, and even when they
+    // aren't, a non-root extractor can't honor non-root ownership anyway —
+    // libarchive silently ignores the chown. The default
+    // `archive_write_disk_set_standard_lookup` calls getpwnam_r/getgrnam_r
+    // per unique uname/gname, which can stall multi-second when NSS routes
+    // through LDAP / sssd / nscd that's misbehaving. Skipping that path
+    // entirely is a 0-LOC-of-runtime-cost win with no observable
+    // behavior change.
+    ::archive_write_disk_set_user_lookup(dst, nullptr,
+        &detail_::const_root_lookup_uid_, nullptr);
+    ::archive_write_disk_set_group_lookup(dst, nullptr,
+        &detail_::const_root_lookup_gid_, nullptr);
+
+    // 4 MiB read block (was 64 KiB pre-0.4.20). For the 808 MiB musl-gcc
+    // tarball that originally surfaced this, the change alone took
+    // wall-clock from 217 s → 5.8 s — even faster than `tar -xpf` at 9.3 s
+    // on the same input. Tiny block + one-syscall-per-block is the dominant
+    // cost on multi-GiB archives; 4 MiB matches what GNU tar uses
+    // internally and stays within libarchive's stack-friendly allocation
+    // envelope.
+    constexpr std::size_t kReadBlockSize = 4 * 1024 * 1024;
+    if (::archive_read_open_filename(src, archive.string().c_str(), kReadBlockSize) != ARCHIVE_OK) {
+        std::string err = std::format("open {}: {}",
+            archive.string(), detail_::libarchive_error_(src));
+        cleanup();
+        return std::unexpected(ExtractError{
+            ExtractErrorKind::InvalidInputArchive, std::move(err)});
+    }
+
+    for (;;) {
+        struct archive_entry* entry = nullptr;
+        int r = ::archive_read_next_header(src, &entry);
+        if (r == ARCHIVE_EOF) break;
+        if (r < ARCHIVE_WARN) {
+            std::string err = "next_header: " + detail_::libarchive_error_(src);
+            cleanup();
+            return std::unexpected(ExtractError{
+                ExtractErrorKind::InvalidInputArchive, std::move(err)});
+        }
+
+        // Reroot the entry under destDir. archive_entry_pathname is a
+        // relative path inside the archive; we vet it and prepend destDir.
+        auto original = detail_::entry_pathname_(entry);
+        auto safeRel = detail_::check_safe_pathname_(original.c_str());
+        if (!safeRel) {
+            cleanup();
+            return std::unexpected(ExtractError{
+                ExtractErrorKind::InvalidInputArchive,
+                std::move(safeRel).error()});
+        }
+        auto rebased = (canonicalDest / *safeRel).lexically_normal().string();
+        ::archive_entry_set_pathname(entry, rebased.c_str());
+
+        // Hardlinks may carry inner paths that point to other archive
+        // entries — same vetting + rebase rule. Symlink *targets* stay
+        // relative to the symlink (not vetted here); SECURE_SYMLINKS
+        // prevents following them during extraction.
+        auto hardlink = detail_::entry_hardlink_(entry);
+        if (!hardlink.empty()) {
+            auto safeHl = detail_::check_safe_pathname_(hardlink.c_str());
+            if (!safeHl) {
+                cleanup();
+                return std::unexpected(ExtractError{
+                    ExtractErrorKind::InvalidInputArchive,
+                    std::move(safeHl).error()});
+            }
+            auto rebasedHl = (canonicalDest / *safeHl).lexically_normal().string();
+            ::archive_entry_set_hardlink(entry, rebasedHl.c_str());
+        }
+
+        // Harden permissions: strip setuid / setgid / world-writable bits
+        // from every entry before it hits disk. Package payloads have no
+        // business shipping setuid binaries — the few that legitimately need
+        // it (e.g. bwrap) get it from an explicit install hook, not tarball
+        // mode bits — and a setuid entry extracted under root/sudo would
+        // silently become setuid-root. Remaining mode bits are still honored
+        // (ARCHIVE_EXTRACT_PERM), so executables stay executable.
+        {
+            constexpr unsigned kStrip = 04000u | 02000u | 0002u;  // suid|sgid|o+w
+            auto perm = static_cast<unsigned>(::archive_entry_perm(entry));
+            // libarchive's set_perm takes its own mode type; the masked
+            // unsigned converts implicitly (no platform/libarchive macro).
+            ::archive_entry_set_perm(entry, perm & ~kStrip);
+        }
+
+        r = ::archive_write_header(dst, entry);
+        if (r < ARCHIVE_OK) {
+            // Write may complain on platform mismatch (e.g., trying to
+            // chown on Windows) but still extract the file. Treat
+            // non-fatal warnings as recoverable.
+            if (r < ARCHIVE_WARN) {
+                std::string err = std::format(
+                    "write_header({}): {}",
+                    rebased, detail_::libarchive_error_(dst));
+                cleanup();
+                return std::unexpected(ExtractError{
+                    ExtractErrorKind::LocalWriteFailure, std::move(err)});
+            }
+        }
+
+        if (::archive_entry_size(entry) > 0) {
+            if (auto copied = detail_::copy_entry_data_(src, dst); !copied) {
+                cleanup();
+                return std::unexpected(std::move(copied).error());
+            }
+        }
+
+        if (::archive_write_finish_entry(dst) < ARCHIVE_WARN) {
+            std::string err = std::format(
+                "finish_entry({}): {}",
+                rebased, detail_::libarchive_error_(dst));
+            cleanup();
+            return std::unexpected(ExtractError{
+                ExtractErrorKind::LocalWriteFailure, std::move(err)});
+        }
+    }
+
+    cleanup();
+    return canonicalDest;
+}
+
+std::expected<std::filesystem::path, std::string>
+extract_archive(const std::filesystem::path& archive,
+                const std::filesystem::path& destDir) {
+    auto result = extract_archive_detailed(archive, destDir);
+    if (!result) return std::unexpected(std::move(result).error().message);
+    return *result;
+}
+
+}
diff --git a/src/core/xim/extract.cppm b/src/core/xim/extract.cppm
index 6d578ef9..9007a012 100644
--- a/src/core/xim/extract.cppm
+++ b/src/core/xim/extract.cppm
@@ -72,298 +72,16 @@ constexpr int kWriteFlags =
 // reject the former here so we can still rebase relative entries onto
 // our chosen destDir. Returns the entry's *original* relative pathname.
 std::expected<std::string, std::string>
-check_safe_pathname_(const char* raw) {
-    if (!raw || !*raw) return std::unexpected("empty pathname");
-    std::string_view sv{raw};
-    if (sv.front() == '/' || (sv.size() >= 3 && sv[1] == ':')) {  // POSIX abs or Windows X:
-        return std::unexpected(std::format("absolute path rejected: {}", sv));
-    }
-    // Block entries that explicitly try to climb out of the staging tree.
-    // libarchive does its own check at extraction time too; this is a
-    // belt-and-braces gate.
-    for (std::size_t i = 0; i + 1 < sv.size(); ++i) {
-        if (sv[i] == '.' && sv[i+1] == '.'
-            && (i == 0 || sv[i-1] == '/' || sv[i-1] == '\\')
-            && (i+2 == sv.size() || sv[i+2] == '/' || sv[i+2] == '\\')) {
-            return std::unexpected(std::format("dot-dot path rejected: {}", sv));
-        }
-    }
-    return std::string{sv};
-}
-
-std::string path_from_wide_(const wchar_t* raw) {
-    if (!raw || !*raw) return {};
-    try {
-        return std::filesystem::path(std::wstring(raw)).generic_string();
-    } catch (...) {
-        return {};
-    }
-}
-
-std::string entry_pathname_(archive_entry* entry) {
-    if (auto* path = ::archive_entry_pathname_utf8(entry); path && *path) {
-        return std::string(path);
-    }
-    if (auto* path = ::archive_entry_pathname(entry); path && *path) {
-        return std::string(path);
-    }
-    return path_from_wide_(::archive_entry_pathname_w(entry));
-}
-
-std::string entry_hardlink_(archive_entry* entry) {
-    if (auto* path = ::archive_entry_hardlink_utf8(entry); path && *path) {
-        return std::string(path);
-    }
-    if (auto* path = ::archive_entry_hardlink(entry); path && *path) {
-        return std::string(path);
-    }
-    return path_from_wide_(::archive_entry_hardlink_w(entry));
-}
-
-std::string libarchive_error_(struct archive* a) {
-    if (auto* msg = ::archive_error_string(a); msg && *msg) {
-        return msg;
-    }
-    return "unknown libarchive error";
-}
-
-// User/group lookup callbacks for archive_write_disk that always return
-// 0 (root). Wired into archive_write_disk_set_user_lookup so libarchive
-// never falls back to getpwnam_r/getgrnam_r — see the call site for the
-// rationale.
-//
-// Signature matches libarchive's `archive_write_disk_set_user_lookup` /
-// `set_group_lookup` callback type:
-//     la_int64_t (*lookup)(void* private_data, const char* name, la_int64_t id);
-la_int64_t const_root_lookup_uid_(void*, const char*, la_int64_t) { return 0; }
-la_int64_t const_root_lookup_gid_(void*, const char*, la_int64_t) { return 0; }
-
-// Read each block of an entry's payload from `src` and write to `dst`.
-std::expected<void, ExtractError>
-copy_entry_data_(struct archive* src, struct archive* dst) {
-    const void* buff = nullptr;
-    std::size_t size = 0;
-    la_int64_t offset = 0;
-    for (;;) {
-        int r = ::archive_read_data_block(src, &buff, &size, &offset);
-        if (r == ARCHIVE_EOF) return {};
-        if (r < ARCHIVE_OK) {
-            return std::unexpected(ExtractError{
-                ExtractErrorKind::InvalidInputArchive,
-                "read_data_block: " + libarchive_error_(src)});
-        }
-        r = ::archive_write_data_block(dst, buff, size, offset);
-        if (r < ARCHIVE_OK) {
-            return std::unexpected(ExtractError{
-                ExtractErrorKind::LocalWriteFailure,
-                "write_data_block: " + libarchive_error_(dst)});
-        }
-    }
-}
-
-void ensure_archive_locale_() {
-    static std::once_flag once;
-    std::call_once(once, [] {
-#ifdef _WIN32
-        if (!std::setlocale(LC_CTYPE, ".UTF-8")) {
-            std::setlocale(LC_CTYPE, "");
-        }
-#else
-        if (!std::setlocale(LC_CTYPE, "C.UTF-8")
-            && !std::setlocale(LC_CTYPE, "en_US.UTF-8")) {
-            std::setlocale(LC_CTYPE, "");
-        }
-#endif
-    });
-}
+check_safe_pathname_(const char* raw);
 
 } // namespace detail_
 
 std::expected<std::filesystem::path, ExtractError>
 extract_archive_detailed(const std::filesystem::path& archive,
-                         const std::filesystem::path& destDir) {
-    namespace fs = std::filesystem;
-    detail_::ensure_archive_locale_();
-
-    std::error_code ec;
-    fs::create_directories(destDir, ec);
-    if (ec) {
-        return std::unexpected(ExtractError{
-            ExtractErrorKind::LocalWriteFailure,
-            std::format("create_directories({}) failed: {}",
-                        destDir.string(), ec.message())});
-    }
-
-    if (!fs::exists(archive)) {
-        return std::unexpected(ExtractError{
-            ExtractErrorKind::InvalidInputArchive,
-            std::format("archive does not exist: {}", archive.string())});
-    }
-
-    // Resolve symlinks in the destination root before handing paths to
-    // libarchive. macOS exposes the temp dir under /var → /private/var,
-    // and ARCHIVE_EXTRACT_SECURE_SYMLINKS refuses to write through any
-    // symlink on the path. weakly_canonical follows existing prefix
-    // links and leaves not-yet-created tail components alone.
-    auto canonicalDest = fs::weakly_canonical(destDir, ec);
-    if (ec) canonicalDest = destDir;  // fall back if canonicalization fails
-
-    struct archive* src = ::archive_read_new();
-    struct archive* dst = ::archive_write_disk_new();
-
-    auto cleanup = [&] {
-        if (src) {
-            ::archive_read_close(src);
-            ::archive_read_free(src);
-            src = nullptr;
-        }
-        if (dst) {
-            ::archive_write_close(dst);
-            ::archive_write_free(dst);
-            dst = nullptr;
-        }
-    };
-
-    if (!src || !dst) {
-        cleanup();
-        return std::unexpected(ExtractError{
-            ExtractErrorKind::Internal,
-            "libarchive: failed to allocate handles"});
-    }
-
-    ::archive_read_support_filter_all(src);
-    ::archive_read_support_format_all(src);
-    ::archive_read_set_format_option(src, "zip", "hdrcharset", "UTF-8");
-    ::archive_write_disk_set_options(dst, detail_::kWriteFlags);
-
-    // Custom user/group lookup that always returns 0 (root). xim-pkgindex
-    // tarballs are packed root:root by convention, and even when they
-    // aren't, a non-root extractor can't honor non-root ownership anyway —
-    // libarchive silently ignores the chown. The default
-    // `archive_write_disk_set_standard_lookup` calls getpwnam_r/getgrnam_r
-    // per unique uname/gname, which can stall multi-second when NSS routes
-    // through LDAP / sssd / nscd that's misbehaving. Skipping that path
-    // entirely is a 0-LOC-of-runtime-cost win with no observable
-    // behavior change.
-    ::archive_write_disk_set_user_lookup(dst, nullptr,
-        &detail_::const_root_lookup_uid_, nullptr);
-    ::archive_write_disk_set_group_lookup(dst, nullptr,
-        &detail_::const_root_lookup_gid_, nullptr);
-
-    // 4 MiB read block (was 64 KiB pre-0.4.20). For the 808 MiB musl-gcc
-    // tarball that originally surfaced this, the change alone took
-    // wall-clock from 217 s → 5.8 s — even faster than `tar -xpf` at 9.3 s
-    // on the same input. Tiny block + one-syscall-per-block is the dominant
-    // cost on multi-GiB archives; 4 MiB matches what GNU tar uses
-    // internally and stays within libarchive's stack-friendly allocation
-    // envelope.
-    constexpr std::size_t kReadBlockSize = 4 * 1024 * 1024;
-    if (::archive_read_open_filename(src, archive.string().c_str(), kReadBlockSize) != ARCHIVE_OK) {
-        std::string err = std::format("open {}: {}",
-            archive.string(), detail_::libarchive_error_(src));
-        cleanup();
-        return std::unexpected(ExtractError{
-            ExtractErrorKind::InvalidInputArchive, std::move(err)});
-    }
-
-    for (;;) {
-        struct archive_entry* entry = nullptr;
-        int r = ::archive_read_next_header(src, &entry);
-        if (r == ARCHIVE_EOF) break;
-        if (r < ARCHIVE_WARN) {
-            std::string err = "next_header: " + detail_::libarchive_error_(src);
-            cleanup();
-            return std::unexpected(ExtractError{
-                ExtractErrorKind::InvalidInputArchive, std::move(err)});
-        }
-
-        // Reroot the entry under destDir. archive_entry_pathname is a
-        // relative path inside the archive; we vet it and prepend destDir.
-        auto original = detail_::entry_pathname_(entry);
-        auto safeRel = detail_::check_safe_pathname_(original.c_str());
-        if (!safeRel) {
-            cleanup();
-            return std::unexpected(ExtractError{
-                ExtractErrorKind::InvalidInputArchive,
-                std::move(safeRel).error()});
-        }
-        auto rebased = (canonicalDest / *safeRel).lexically_normal().string();
-        ::archive_entry_set_pathname(entry, rebased.c_str());
-
-        // Hardlinks may carry inner paths that point to other archive
-        // entries — same vetting + rebase rule. Symlink *targets* stay
-        // relative to the symlink (not vetted here); SECURE_SYMLINKS
-        // prevents following them during extraction.
-        auto hardlink = detail_::entry_hardlink_(entry);
-        if (!hardlink.empty()) {
-            auto safeHl = detail_::check_safe_pathname_(hardlink.c_str());
-            if (!safeHl) {
-                cleanup();
-                return std::unexpected(ExtractError{
-                    ExtractErrorKind::InvalidInputArchive,
-                    std::move(safeHl).error()});
-            }
-            auto rebasedHl = (canonicalDest / *safeHl).lexically_normal().string();
-            ::archive_entry_set_hardlink(entry, rebasedHl.c_str());
-        }
-
-        // Harden permissions: strip setuid / setgid / world-writable bits
-        // from every entry before it hits disk. Package payloads have no
-        // business shipping setuid binaries — the few that legitimately need
-        // it (e.g. bwrap) get it from an explicit install hook, not tarball
-        // mode bits — and a setuid entry extracted under root/sudo would
-        // silently become setuid-root. Remaining mode bits are still honored
-        // (ARCHIVE_EXTRACT_PERM), so executables stay executable.
-        {
-            constexpr unsigned kStrip = 04000u | 02000u | 0002u;  // suid|sgid|o+w
-            auto perm = static_cast<unsigned>(::archive_entry_perm(entry));
-            // libarchive's set_perm takes its own mode type; the masked
-            // unsigned converts implicitly (no platform/libarchive macro).
-            ::archive_entry_set_perm(entry, perm & ~kStrip);
-        }
-
-        r = ::archive_write_header(dst, entry);
-        if (r < ARCHIVE_OK) {
-            // Write may complain on platform mismatch (e.g., trying to
-            // chown on Windows) but still extract the file. Treat
-            // non-fatal warnings as recoverable.
-            if (r < ARCHIVE_WARN) {
-                std::string err = std::format(
-                    "write_header({}): {}",
-                    rebased, detail_::libarchive_error_(dst));
-                cleanup();
-                return std::unexpected(ExtractError{
-                    ExtractErrorKind::LocalWriteFailure, std::move(err)});
-            }
-        }
-
-        if (::archive_entry_size(entry) > 0) {
-            if (auto copied = detail_::copy_entry_data_(src, dst); !copied) {
-                cleanup();
-                return std::unexpected(std::move(copied).error());
-            }
-        }
-
-        if (::archive_write_finish_entry(dst) < ARCHIVE_WARN) {
-            std::string err = std::format(
-                "finish_entry({}): {}",
-                rebased, detail_::libarchive_error_(dst));
-            cleanup();
-            return std::unexpected(ExtractError{
-                ExtractErrorKind::LocalWriteFailure, std::move(err)});
-        }
-    }
-
-    cleanup();
-    return canonicalDest;
-}
+                         const std::filesystem::path& destDir);
 
 std::expected<std::filesystem::path, std::string>
 extract_archive(const std::filesystem::path& archive,
-                const std::filesystem::path& destDir) {
-    auto result = extract_archive_detailed(archive, destDir);
-    if (!result) return std::unexpected(std::move(result).error().message);
-    return *result;
-}
+                const std::filesystem::path& destDir);
 
 } // namespace xlings::xim
diff --git a/src/core/xim/index.cpp b/src/core/xim/index.cpp
new file mode 100644
index 00000000..f6a974af
--- /dev/null
+++ b/src/core/xim/index.cpp
@@ -0,0 +1,325 @@
+module xlings.core.xim.index;
+
+import std;
+import mcpplibs.xpkg;
+import mcpplibs.xpkg.loader;
+import mcpplibs.xpkg.index;
+import xlings.libs.json;
+import xlings.core.log;
+import xlings.core.config;
+import xlings.platform;
+
+namespace xlings::xim::cache_detail_ {
+
+int type_to_int(xpkg::PackageType t) {
+    return static_cast<int>(t);
+}
+
+xpkg::PackageType int_to_type(int v) {
+    switch (v) {
+        case 1: return xpkg::PackageType::Script;
+        case 2: return xpkg::PackageType::Template;
+        case 3: return xpkg::PackageType::Config;
+        case 4: return xpkg::PackageType::Subos;
+        default: return xpkg::PackageType::Package;
+    }
+}
+
+bool save_index_cache(const xpkg::PackageIndex& index,
+                      const std::filesystem::path& cacheFile,
+                      const std::string& repoHeadHash,
+                      const std::string& defaultNamespace) {
+    try {
+        nlohmann::json entries = nlohmann::json::object();
+        for (auto& [key, entry] : index.entries) {
+            entries[key] = {
+                {"identity", {
+                    {"namespace", entry.identity.namespaceName},
+                    {"name", entry.identity.name}
+                }},
+                {"canonical_name", entry.canonicalName},
+                {"entry_key", entry.entryKey},
+                {"name", entry.name},
+                {"version", entry.version},
+                {"path", entry.path.string()},
+                {"type", type_to_int(entry.type)},
+                {"description", entry.description},
+                {"ref", entry.ref}
+            };
+        }
+
+        nlohmann::json mutexGroups = nlohmann::json::object();
+        for (auto& [gkey, members] : index.mutex_groups) {
+            mutexGroups[gkey] = members;
+        }
+
+        nlohmann::json root = {
+            {"version", CACHE_FORMAT_VERSION},
+            {"repo_head_hash", repoHeadHash},
+            {"default_namespace", defaultNamespace},
+            {"entries", std::move(entries)},
+            {"mutex_groups", std::move(mutexGroups)}
+        };
+
+        std::filesystem::create_directories(cacheFile.parent_path());
+        platform::write_string_to_file(cacheFile.string(), root.dump());
+        return true;
+    } catch (...) {
+        return false;
+    }
+}
+
+CacheResult load_index_cache(const std::filesystem::path& cacheFile,
+                             xpkg::PackageIndex& index,
+                             const std::string& defaultNamespace) {
+    CacheResult result;
+    if (!std::filesystem::exists(cacheFile)) return result;
+
+    try {
+        auto content = platform::read_file_to_string(cacheFile.string());
+        auto root = nlohmann::json::parse(content, nullptr, false);
+        if (root.is_discarded() || !root.is_object()) return result;
+
+        if (root.value("version", 0) != CACHE_FORMAT_VERSION) return result;
+        if (root.value("default_namespace", std::string{}) != defaultNamespace) {
+            return result;
+        }
+
+        result.repoHeadHash = root.value("repo_head_hash", "");
+
+        if (!root.contains("entries") || !root["entries"].is_object()) {
+            return result;
+        }
+        for (auto it = root["entries"].begin(); it != root["entries"].end(); ++it) {
+            auto& val = it.value();
+            if (!val.is_object()
+                    || !val.contains("identity")
+                    || !val["identity"].is_object()) {
+                return result;
+            }
+            auto& identity = val["identity"];
+            if (!identity.contains("namespace")
+                    || !identity["namespace"].is_string()
+                    || !identity.contains("name")
+                    || !identity["name"].is_string()
+                    || !val.contains("canonical_name")
+                    || !val["canonical_name"].is_string()
+                    || !val.contains("entry_key")
+                    || !val["entry_key"].is_string()) {
+                return result;
+            }
+
+            xpkg::IndexEntry entry;
+            entry.identity.namespaceName = identity["namespace"].get<std::string>();
+            entry.identity.name = identity["name"].get<std::string>();
+            entry.canonicalName = val["canonical_name"].get<std::string>();
+            entry.entryKey = val["entry_key"].get<std::string>();
+            entry.name = val.value("name", "");
+            entry.version = val.value("version", "");
+            entry.path = std::filesystem::path(val.value("path", ""));
+            entry.type = int_to_type(val.value("type", 0));
+            entry.description = val.value("description", "");
+            entry.ref = val.value("ref", "");
+
+            if (entry.identity.name.empty()
+                    || entry.identity.canonical_name() != entry.canonicalName
+                    || entry.entryKey != it.key()
+                    || entry.name != entry.identity.name) {
+                return result;
+            }
+
+            auto [_, inserted] = index.entries.emplace(entry.entryKey, entry);
+            if (!inserted) return result;
+            index.identityEntries[entry.canonicalName].push_back(entry.entryKey);
+            index.shortNames[entry.identity.name].push_back(entry.canonicalName);
+        }
+
+        for (auto& [_, candidates] : index.identityEntries) {
+            std::ranges::sort(candidates);
+            auto uniqueEnd = std::ranges::unique(candidates).begin();
+            candidates.erase(uniqueEnd, candidates.end());
+        }
+        for (auto& [_, candidates] : index.shortNames) {
+            std::ranges::sort(candidates);
+            auto uniqueEnd = std::ranges::unique(candidates).begin();
+            candidates.erase(uniqueEnd, candidates.end());
+        }
+
+        if (root.contains("mutex_groups") && root["mutex_groups"].is_object()) {
+            for (auto it = root["mutex_groups"].begin(); it != root["mutex_groups"].end(); ++it) {
+                std::vector<std::string> members;
+                for (auto& m : it.value()) {
+                    members.push_back(m.get<std::string>());
+                }
+                index.mutex_groups[it.key()] = std::move(members);
+            }
+        }
+
+        result.valid = true;
+    } catch (...) {
+        // Corrupt cache — caller will rebuild
+    }
+    return result;
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::xim {
+
+IndexManager::IndexManager(const std::filesystem::path& repoDir, std::string defaultNamespace) : repoDir_(repoDir),
+      defaultNamespace_(std::move(defaultNamespace)) {}
+
+void IndexManager::set_repo_dir(const std::filesystem::path& dir) {
+    repoDir_ = dir;
+}
+
+void IndexManager::set_default_namespace(std::string defaultNamespace) {
+    defaultNamespace_ = std::move(defaultNamespace);
+}
+
+std::expected<void, std::string> IndexManager::rebuild() {
+    namespace fs = std::filesystem;
+
+    if (repoDir_.empty()) {
+        return std::unexpected("repo directory not set");
+    }
+
+    if (!fs::exists(repoDir_ / "pkgs")) {
+        return std::unexpected(
+            std::format("pkgs/ directory not found in {}", repoDir_.string()));
+    }
+
+    log::debug("building package index from {}", repoDir_.string());
+
+    auto result = xpkg::build_index(repoDir_, defaultNamespace_);
+    if (!result) {
+        return std::unexpected(
+            std::format("build_index failed: {}", result.error()));
+    }
+
+    index_ = std::move(*result);
+    loaded_ = true;
+
+    log::debug("index built: {} entries", index_.entries.size());
+    return {};
+}
+
+std::expected<void, std::string> IndexManager::load_or_rebuild(const std::string& repoHeadHash, bool forceRebuild) {
+    if (repoDir_.empty()) {
+        return std::unexpected("repo directory not set");
+    }
+
+    auto cacheFile = repoDir_ / ".xlings-index-cache.json";
+
+    // Try loading from cache (unless forced or no git hash)
+    if (!forceRebuild && !repoHeadHash.empty()) {
+        xpkg::PackageIndex cached;
+        auto cacheResult = cache_detail_::load_index_cache(
+            cacheFile, cached, defaultNamespace_);
+        if (cacheResult.valid && cacheResult.repoHeadHash == repoHeadHash) {
+            index_ = std::move(cached);
+            loaded_ = true;
+            log::debug("index loaded from cache: {} entries", index_.entries.size());
+            return {};
+        }
+    }
+
+    // Cache miss or forced: full rebuild
+    auto result = rebuild();
+    if (!result) return result;
+
+    // Save cache (best effort)
+    if (!cache_detail_::save_index_cache(
+            index_, cacheFile, repoHeadHash, defaultNamespace_)) {
+        log::warn("failed to save index cache for {}", repoDir_.string());
+    }
+
+    return {};
+}
+
+bool IndexManager::is_loaded() const { return loaded_; }
+
+std::size_t IndexManager::size() const { return index_.entries.size(); }
+
+std::vector<std::string> IndexManager::search(const std::string& keyword) const {
+    return xpkg::search(index_, keyword);
+}
+
+std::vector<std::string> IndexManager::find_candidates(std::string_view name, std::optional<std::string_view> namespaceName) const {
+    return xpkg::find_candidates(index_, name, namespaceName);
+}
+
+std::optional<std::string> IndexManager::match_version(const std::string& name) const {
+    if (name.contains(':') || index_.entries.contains(name)) {
+        return xpkg::match_version(index_, name);
+    }
+    auto candidates = find_candidates(name);
+    if (candidates.size() != 1) return std::nullopt;
+    return xpkg::match_version(index_, candidates.front());
+}
+
+std::string IndexManager::resolve(const std::string& name) const {
+    if (name.contains(':') || index_.entries.contains(name)) {
+        return xpkg::resolve(index_, name);
+    }
+    auto candidates = find_candidates(name);
+    if (candidates.size() != 1) return name;
+    return xpkg::resolve(index_, candidates.front());
+}
+
+std::vector<std::string> IndexManager::mutex_packages(const std::string& name) const {
+    return xpkg::mutex_packages(index_, name);
+}
+
+std::expected<xpkg::Package, std::string> IndexManager::load_package(const std::string& name) const {
+    auto it = index_.entries.find(name);
+    if (it == index_.entries.end()) {
+        return std::unexpected(std::format("package '{}' not found in index", name));
+    }
+    return xpkg::load_package(it->second.path);
+}
+
+const xpkg::IndexEntry* IndexManager::find_entry(const std::string& name) const {
+    auto it = index_.entries.find(name);
+    return it != index_.entries.end() ? &it->second : nullptr;
+}
+
+void IndexManager::mark_installed(const std::string& name, bool installed) {
+    xpkg::set_installed(index_, name, installed);
+}
+
+void IndexManager::merge(xpkg::PackageIndex other, const std::string& ns) {
+    index_ = xpkg::merge(std::move(index_), other, ns);
+}
+
+std::vector<std::string> IndexManager::all_names() const {
+    std::vector<std::string> names;
+    names.reserve(index_.entries.size());
+    for (auto& [k, v] : index_.entries) {
+        names.push_back(k);
+    }
+    std::sort(names.begin(), names.end());
+    return names;
+}
+
+std::vector<std::string> IndexManager::installed_names() const {
+    std::vector<std::string> names;
+    for (auto& [k, v] : index_.entries) {
+        if (v.installed) names.push_back(k);
+    }
+    std::sort(names.begin(), names.end());
+    return names;
+}
+
+const xpkg::PackageIndex& IndexManager::raw_index() const { return index_; }
+
+std::optional<std::filesystem::path> IndexManager::entry_path(const std::string& name) const {
+    auto it = index_.entries.find(name);
+    if (it == index_.entries.end()) return std::nullopt;
+    return it->second.path;
+}
+
+} // namespace xlings::xim
diff --git a/src/core/xim/index.cppm b/src/core/xim/index.cppm
index 7b100e7f..f0148826 100644
--- a/src/core/xim/index.cppm
+++ b/src/core/xim/index.cppm
@@ -4,10 +4,7 @@ import std;
 import mcpplibs.xpkg;
 import mcpplibs.xpkg.loader;
 import mcpplibs.xpkg.index;
-import xlings.libs.json;
-import xlings.core.log;
 import xlings.core.config;
-import xlings.platform;
 
 // All libxpkg functions live in mcpplibs::xpkg namespace regardless of module name
 namespace xpkg = mcpplibs::xpkg;
@@ -16,63 +13,10 @@ namespace xlings::xim::cache_detail_ {
 
 constexpr int CACHE_FORMAT_VERSION = 2;
 
-int type_to_int(xpkg::PackageType t) {
-    return static_cast<int>(t);
-}
-
-xpkg::PackageType int_to_type(int v) {
-    switch (v) {
-        case 1: return xpkg::PackageType::Script;
-        case 2: return xpkg::PackageType::Template;
-        case 3: return xpkg::PackageType::Config;
-        case 4: return xpkg::PackageType::Subos;
-        default: return xpkg::PackageType::Package;
-    }
-}
-
 bool save_index_cache(const xpkg::PackageIndex& index,
                       const std::filesystem::path& cacheFile,
                       const std::string& repoHeadHash,
-                      const std::string& defaultNamespace) {
-    try {
-        nlohmann::json entries = nlohmann::json::object();
-        for (auto& [key, entry] : index.entries) {
-            entries[key] = {
-                {"identity", {
-                    {"namespace", entry.identity.namespaceName},
-                    {"name", entry.identity.name}
-                }},
-                {"canonical_name", entry.canonicalName},
-                {"entry_key", entry.entryKey},
-                {"name", entry.name},
-                {"version", entry.version},
-                {"path", entry.path.string()},
-                {"type", type_to_int(entry.type)},
-                {"description", entry.description},
-                {"ref", entry.ref}
-            };
-        }
-
-        nlohmann::json mutexGroups = nlohmann::json::object();
-        for (auto& [gkey, members] : index.mutex_groups) {
-            mutexGroups[gkey] = members;
-        }
-
-        nlohmann::json root = {
-            {"version", CACHE_FORMAT_VERSION},
-            {"repo_head_hash", repoHeadHash},
-            {"default_namespace", defaultNamespace},
-            {"entries", std::move(entries)},
-            {"mutex_groups", std::move(mutexGroups)}
-        };
-
-        std::filesystem::create_directories(cacheFile.parent_path());
-        platform::write_string_to_file(cacheFile.string(), root.dump());
-        return true;
-    } catch (...) {
-        return false;
-    }
-}
+                      const std::string& defaultNamespace);
 
 struct CacheResult {
     std::string repoHeadHash;
@@ -81,96 +25,7 @@ struct CacheResult {
 
 CacheResult load_index_cache(const std::filesystem::path& cacheFile,
                              xpkg::PackageIndex& index,
-                             const std::string& defaultNamespace) {
-    CacheResult result;
-    if (!std::filesystem::exists(cacheFile)) return result;
-
-    try {
-        auto content = platform::read_file_to_string(cacheFile.string());
-        auto root = nlohmann::json::parse(content, nullptr, false);
-        if (root.is_discarded() || !root.is_object()) return result;
-
-        if (root.value("version", 0) != CACHE_FORMAT_VERSION) return result;
-        if (root.value("default_namespace", std::string{}) != defaultNamespace) {
-            return result;
-        }
-
-        result.repoHeadHash = root.value("repo_head_hash", "");
-
-        if (!root.contains("entries") || !root["entries"].is_object()) {
-            return result;
-        }
-        for (auto it = root["entries"].begin(); it != root["entries"].end(); ++it) {
-            auto& val = it.value();
-            if (!val.is_object()
-                    || !val.contains("identity")
-                    || !val["identity"].is_object()) {
-                return result;
-            }
-            auto& identity = val["identity"];
-            if (!identity.contains("namespace")
-                    || !identity["namespace"].is_string()
-                    || !identity.contains("name")
-                    || !identity["name"].is_string()
-                    || !val.contains("canonical_name")
-                    || !val["canonical_name"].is_string()
-                    || !val.contains("entry_key")
-                    || !val["entry_key"].is_string()) {
-                return result;
-            }
-
-            xpkg::IndexEntry entry;
-            entry.identity.namespaceName = identity["namespace"].get<std::string>();
-            entry.identity.name = identity["name"].get<std::string>();
-            entry.canonicalName = val["canonical_name"].get<std::string>();
-            entry.entryKey = val["entry_key"].get<std::string>();
-            entry.name = val.value("name", "");
-            entry.version = val.value("version", "");
-            entry.path = std::filesystem::path(val.value("path", ""));
-            entry.type = int_to_type(val.value("type", 0));
-            entry.description = val.value("description", "");
-            entry.ref = val.value("ref", "");
-
-            if (entry.identity.name.empty()
-                    || entry.identity.canonical_name() != entry.canonicalName
-                    || entry.entryKey != it.key()
-                    || entry.name != entry.identity.name) {
-                return result;
-            }
-
-            auto [_, inserted] = index.entries.emplace(entry.entryKey, entry);
-            if (!inserted) return result;
-            index.identityEntries[entry.canonicalName].push_back(entry.entryKey);
-            index.shortNames[entry.identity.name].push_back(entry.canonicalName);
-        }
-
-        for (auto& [_, candidates] : index.identityEntries) {
-            std::ranges::sort(candidates);
-            auto uniqueEnd = std::ranges::unique(candidates).begin();
-            candidates.erase(uniqueEnd, candidates.end());
-        }
-        for (auto& [_, candidates] : index.shortNames) {
-            std::ranges::sort(candidates);
-            auto uniqueEnd = std::ranges::unique(candidates).begin();
-            candidates.erase(uniqueEnd, candidates.end());
-        }
-
-        if (root.contains("mutex_groups") && root["mutex_groups"].is_object()) {
-            for (auto it = root["mutex_groups"].begin(); it != root["mutex_groups"].end(); ++it) {
-                std::vector<std::string> members;
-                for (auto& m : it.value()) {
-                    members.push_back(m.get<std::string>());
-                }
-                index.mutex_groups[it.key()] = std::move(members);
-            }
-        }
-
-        result.valid = true;
-    } catch (...) {
-        // Corrupt cache — caller will rebuild
-    }
-    return result;
-}
+                             const std::string& defaultNamespace);
 
 }  // namespace xlings::xim::cache_detail_
 
@@ -186,178 +41,64 @@ public:
     IndexManager() = default;
 
     explicit IndexManager(const std::filesystem::path& repoDir,
-                          std::string defaultNamespace = {})
-        : repoDir_(repoDir),
-          defaultNamespace_(std::move(defaultNamespace)) {}
+                          std::string defaultNamespace = {});
 
-    void set_repo_dir(const std::filesystem::path& dir) {
-        repoDir_ = dir;
-    }
+    void set_repo_dir(const std::filesystem::path& dir);
 
-    void set_default_namespace(std::string defaultNamespace) {
-        defaultNamespace_ = std::move(defaultNamespace);
-    }
+    void set_default_namespace(std::string defaultNamespace);
 
     // Build index by scanning pkgs/ directory via libxpkg
-    std::expected<void, std::string> rebuild() {
-        namespace fs = std::filesystem;
-
-        if (repoDir_.empty()) {
-            return std::unexpected("repo directory not set");
-        }
-
-        if (!fs::exists(repoDir_ / "pkgs")) {
-            return std::unexpected(
-                std::format("pkgs/ directory not found in {}", repoDir_.string()));
-        }
-
-        log::debug("building package index from {}", repoDir_.string());
-
-        auto result = xpkg::build_index(repoDir_, defaultNamespace_);
-        if (!result) {
-            return std::unexpected(
-                std::format("build_index failed: {}", result.error()));
-        }
-
-        index_ = std::move(*result);
-        loaded_ = true;
-
-        log::debug("index built: {} entries", index_.entries.size());
-        return {};
-    }
+    std::expected<void, std::string> rebuild();
 
     // Load from cache if valid, else rebuild and save cache.
     std::expected<void, std::string> load_or_rebuild(
             const std::string& repoHeadHash,
-            bool forceRebuild = false) {
-        if (repoDir_.empty()) {
-            return std::unexpected("repo directory not set");
-        }
-
-        auto cacheFile = repoDir_ / ".xlings-index-cache.json";
-
-        // Try loading from cache (unless forced or no git hash)
-        if (!forceRebuild && !repoHeadHash.empty()) {
-            xpkg::PackageIndex cached;
-            auto cacheResult = cache_detail_::load_index_cache(
-                cacheFile, cached, defaultNamespace_);
-            if (cacheResult.valid && cacheResult.repoHeadHash == repoHeadHash) {
-                index_ = std::move(cached);
-                loaded_ = true;
-                log::debug("index loaded from cache: {} entries", index_.entries.size());
-                return {};
-            }
-        }
-
-        // Cache miss or forced: full rebuild
-        auto result = rebuild();
-        if (!result) return result;
-
-        // Save cache (best effort)
-        if (!cache_detail_::save_index_cache(
-                index_, cacheFile, repoHeadHash, defaultNamespace_)) {
-            log::warn("failed to save index cache for {}", repoDir_.string());
-        }
-
-        return {};
-    }
+            bool forceRebuild = false);
 
-    bool is_loaded() const { return loaded_; }
-    std::size_t size() const { return index_.entries.size(); }
+    bool is_loaded() const;
+    std::size_t size() const;
 
     // Search packages by keyword (fuzzy, case-insensitive)
-    std::vector<std::string> search(const std::string& keyword) const {
-        return xpkg::search(index_, keyword);
-    }
+    std::vector<std::string> search(const std::string& keyword) const;
 
     std::vector<std::string>
     find_candidates(
             std::string_view name,
-            std::optional<std::string_view> namespaceName = std::nullopt) const {
-        return xpkg::find_candidates(index_, name, namespaceName);
-    }
+            std::optional<std::string_view> namespaceName = std::nullopt) const;
 
     // Match a version query like "gcc@15" to best version "gcc@15.1.0"
-    std::optional<std::string> match_version(const std::string& name) const {
-        if (name.contains(':') || index_.entries.contains(name)) {
-            return xpkg::match_version(index_, name);
-        }
-        auto candidates = find_candidates(name);
-        if (candidates.size() != 1) return std::nullopt;
-        return xpkg::match_version(index_, candidates.front());
-    }
+    std::optional<std::string> match_version(const std::string& name) const;
 
     // Resolve an alias (e.g., "c" -> "gcc")
-    std::string resolve(const std::string& name) const {
-        if (name.contains(':') || index_.entries.contains(name)) {
-            return xpkg::resolve(index_, name);
-        }
-        auto candidates = find_candidates(name);
-        if (candidates.size() != 1) return name;
-        return xpkg::resolve(index_, candidates.front());
-    }
+    std::string resolve(const std::string& name) const;
 
     // Get mutex group packages for conflict detection
-    std::vector<std::string> mutex_packages(const std::string& name) const {
-        return xpkg::mutex_packages(index_, name);
-    }
+    std::vector<std::string> mutex_packages(const std::string& name) const;
 
     // Load full Package data for a specific entry
     std::expected<xpkg::Package, std::string>
-    load_package(const std::string& name) const {
-        auto it = index_.entries.find(name);
-        if (it == index_.entries.end()) {
-            return std::unexpected(std::format("package '{}' not found in index", name));
-        }
-        return xpkg::load_package(it->second.path);
-    }
+    load_package(const std::string& name) const;
 
     // Get entry by name
-    const xpkg::IndexEntry* find_entry(const std::string& name) const {
-        auto it = index_.entries.find(name);
-        return it != index_.entries.end() ? &it->second : nullptr;
-    }
+    const xpkg::IndexEntry* find_entry(const std::string& name) const;
 
     // Mark installed state
-    void mark_installed(const std::string& name, bool installed) {
-        xpkg::set_installed(index_, name, installed);
-    }
+    void mark_installed(const std::string& name, bool installed);
 
     // Merge another index (for sub-repos)
-    void merge(xpkg::PackageIndex other, const std::string& ns = "") {
-        index_ = xpkg::merge(std::move(index_), other, ns);
-    }
+    void merge(xpkg::PackageIndex other, const std::string& ns = "");
 
     // Get all entry names (sorted)
-    std::vector<std::string> all_names() const {
-        std::vector<std::string> names;
-        names.reserve(index_.entries.size());
-        for (auto& [k, v] : index_.entries) {
-            names.push_back(k);
-        }
-        std::sort(names.begin(), names.end());
-        return names;
-    }
+    std::vector<std::string> all_names() const;
 
     // Get all installed entry names
-    std::vector<std::string> installed_names() const {
-        std::vector<std::string> names;
-        for (auto& [k, v] : index_.entries) {
-            if (v.installed) names.push_back(k);
-        }
-        std::sort(names.begin(), names.end());
-        return names;
-    }
+    std::vector<std::string> installed_names() const;
 
     // Get the raw index
-    const xpkg::PackageIndex& raw_index() const { return index_; }
+    const xpkg::PackageIndex& raw_index() const;
 
     // Get entry path for creating executors
-    std::optional<std::filesystem::path> entry_path(const std::string& name) const {
-        auto it = index_.entries.find(name);
-        if (it == index_.entries.end()) return std::nullopt;
-        return it->second.path;
-    }
+    std::optional<std::filesystem::path> entry_path(const std::string& name) const;
 };
 
 } // namespace xlings::xim
diff --git a/src/core/xim/index_cmd.cpp b/src/core/xim/index_cmd.cpp
new file mode 100644
index 00000000..cf4c4127
--- /dev/null
+++ b/src/core/xim/index_cmd.cpp
@@ -0,0 +1,229 @@
+module xlings.core.xim.index_cmd;
+
+import std;
+import xlings.libs.json;
+import xlings.core.config;
+import xlings.core.home_config;
+import xlings.core.log;
+import xlings.core.version_order;
+import xlings.core.xim.indexfetch;
+import xlings.platform;
+import xlings.runtime;
+
+namespace xlings::xim {
+
+std::string installed_index_version(const std::filesystem::path& repoDir) {
+    std::error_code ec;
+    auto marker = repoDir / ".xlings-index-version";
+    if (!std::filesystem::exists(marker, ec)) return {};
+    try {
+        auto v = platform::read_file_to_string(marker.string());
+        while (!v.empty() && (v.back() == '\n' || v.back() == '\r' || v.back() == ' '))
+            v.pop_back();
+        return v;
+    } catch (...) { return {}; }
+}
+
+std::vector<IndexSourceView> collect_index_sources() {
+    std::vector<IndexSourceView> views;
+    for (const auto& repo : Config::global_index_repos()) {
+        IndexSourceView view;
+        view.name = repo.name;
+        view.pin  = repo.version;
+        view.installed = installed_index_version(Config::repo_dir_for(repo, false));
+
+        auto source = artifact_source_for(repo);
+        const auto& pointers = load_index_pointers(Config::mirror(),
+                                                   source ? &*source : nullptr);
+        const auto key = source ? source->key : repo.name;
+        const auto* manifest = select_manifest(pointers, key, source.has_value());
+        if (!manifest) {
+            view.error = pointers.empty()
+                ? "pointer unavailable (offline, or this repo is git-only)"
+                : std::format("no pointer entry for '{}'", key);
+            views.push_back(std::move(view));
+            continue;
+        }
+        view.hasPointer = true;
+        view.snapshots  = snapshots_of(*manifest);
+        view.truncated  = manifest->history_truncated;
+        if (auto choice = choose_snapshot(*manifest, Info::VERSION, repo.version)) {
+            view.current = choice->snapshot.index_version;
+        } else {
+            view.error = choice.error();
+        }
+        views.push_back(std::move(view));
+    }
+    return views;
+}
+
+nlohmann::json index_sources_json(const std::vector<IndexSourceView>& views) {
+    nlohmann::json out = nlohmann::json::array();
+    for (const auto& view : views) {
+        nlohmann::json entry;
+        entry["name"]      = view.name;
+        entry["pinned"]    = view.pin;
+        entry["current"]   = view.current;
+        // What is on disk, which is not the same question as what would be
+        // picked: between a pointer moving and the next `update`, the two differ
+        // and only this one describes the tree the client is actually reading.
+        entry["installed"] = view.installed;
+        entry["truncated"] = view.truncated;
+        if (!view.error.empty()) entry["error"] = view.error;
+        entry["snapshots"] = nlohmann::json::array();
+        for (const auto& s : view.snapshots) {
+            nlohmann::json row;
+            row["index_version"] = s.index_version;
+            row["generated_at"]  = s.generated_at;
+            row["current"]       = s.index_version == view.current;
+            row["installed"]     = !view.installed.empty()
+                                   && s.index_version == view.installed;
+            // Verbatim. Normalising here would make xlings an interpreter of
+            // contracts it does not own.
+            row["requires"]      = s.requirements;
+            row["artifact"]      = { {"name", s.artifact_name},
+                                     {"sha256", s.artifact_sha256},
+                                     {"size", s.artifact_size} };
+            entry["snapshots"].push_back(std::move(row));
+        }
+        out.push_back(std::move(entry));
+    }
+    return out;
+}
+
+int cmd_index_list(const std::string& filter, bool asJson, EventStream& stream) {
+    auto views = collect_index_sources();
+    if (!filter.empty()) {
+        std::erase_if(views, [&](const auto& v) { return v.name != filter; });
+        if (views.empty()) {
+            log::error("no index source named '{}'", filter);
+            return 1;
+        }
+    }
+
+    if (asJson) {
+        std::println("{}", index_sources_json(views).dump(2));
+        return 0;
+    }
+
+    for (const auto& view : views) {
+        log::println("");
+        log::println("  ◆ {}{}", view.name,
+                     view.pin.empty() ? "" : std::format("  (pinned: {})", view.pin));
+        if (!view.error.empty()) {
+            log::println("    {}", view.error);
+            continue;
+        }
+        for (const auto& s : view.snapshots) {
+            const auto req = requirement_for(s.requirements, "xlings");
+            std::string note;
+            if (req) {
+                if (!req->min.empty()) note += ">= " + req->min;
+                if (!req->max.empty()) note += (note.empty() ? "" : " ") + std::string("< ") + req->max;
+                note = "  requires xlings " + note;
+            }
+            // `*` is the tree on disk -- the packages this client resolves
+            // against right now. `>` is what the next `update` would fetch.
+            // They differ whenever the pointer moved since the last update, and
+            // reporting only the second would answer a question the user did
+            // not ask while looking like it answered theirs.
+            const bool onDisk = !view.installed.empty()
+                                && s.index_version == view.installed;
+            log::println("    {} {}{}{}",
+                         onDisk ? "*" : (s.index_version == view.current ? ">" : " "),
+                         s.index_version,
+                         s.generated_at.empty() ? "" : "  " + s.generated_at,
+                         note);
+        }
+        if (view.truncated) {
+            log::println("      … older snapshots exist but are not listed");
+        }
+        if (view.installed.empty()) {
+            log::println("      (no index on disk yet — run `xlings update`)");
+        } else if (!view.current.empty() && view.current != view.installed) {
+            log::println("      on disk: {} — run `xlings update` to move to {}",
+                         view.installed, view.current);
+        }
+    }
+    log::println("");
+    return 0;
+}
+
+int cmd_index_use(const std::string& name, const std::string& version,
+                  EventStream& stream) {
+    if (name.empty()) {
+        log::error("usage: xlings index use <name> <version|latest>");
+        return 2;
+    }
+    const bool clearing = version.empty() || version == "latest";
+
+    // Refuse a version the pointer does not offer -- accepting it would leave a
+    // config that only fails on the next update, far from the command that
+    // wrote it.
+    if (!clearing) {
+        auto views = collect_index_sources();
+        const auto hit = std::ranges::find_if(views,
+            [&](const auto& v) { return v.name == name; });
+        if (hit == views.end()) {
+            log::error("no index source named '{}'", name);
+            return 1;
+        }
+        const bool known = std::ranges::any_of(hit->snapshots,
+            [&](const auto& s) { return s.index_version == version; });
+        if (!known) {
+            log::error("index '{}' has no published snapshot '{}'", name, version);
+            std::string list;
+            for (const auto& s : hit->snapshots) {
+                if (!list.empty()) list += ", ";
+                list += s.index_version;
+            }
+            log::error("  available: {}", list.empty() ? "(none)" : list);
+            return 1;
+        }
+    }
+
+    auto applied = update_home_config(Config::paths().homeDir,
+        [&](nlohmann::json& json) {
+            if (!json.contains("index_repos") || !json["index_repos"].is_array()) {
+                json["index_repos"] = nlohmann::json::array();
+            }
+            for (auto& entry : json["index_repos"]) {
+                if (!entry.is_object() || !entry.contains("name")) continue;
+                if (entry["name"].get<std::string>() != name) continue;
+                if (clearing) entry.erase("version");
+                else entry["version"] = version;
+                return true;
+            }
+            // The source exists in the effective config but not in the file --
+            // it is a built-in default. Materialise the entry so the pin has
+            // somewhere to live.
+            for (const auto& repo : Config::global_index_repos()) {
+                if (repo.name != name) continue;
+                nlohmann::json entry;
+                entry["name"] = repo.name;
+                entry["url"]  = repo.url;
+                if (!clearing) entry["version"] = version;
+                json["index_repos"].push_back(entry);
+                return true;
+            }
+            return false;
+        });
+
+    if (!applied) {
+        log::error("{}", applied.error());
+        return 1;
+    }
+    if (!*applied) {
+        log::error("no index source named '{}'", name);
+        return 1;
+    }
+    if (clearing) {
+        log::println("index '{}' follows the newest compatible snapshot", name);
+    } else {
+        log::println("index '{}' pinned to {}", name, version);
+    }
+    log::println("  run `xlings update` to apply");
+    return 0;
+}
+
+}
diff --git a/src/core/xim/index_cmd.cppm b/src/core/xim/index_cmd.cppm
index a2597111..0eb0b16a 100644
--- a/src/core/xim/index_cmd.cppm
+++ b/src/core/xim/index_cmd.cppm
@@ -3,11 +3,8 @@ export module xlings.core.xim.index_cmd;
 import std;
 import xlings.libs.json;
 import xlings.core.config;
-import xlings.core.home_config;
 import xlings.core.log;
-import xlings.core.version_order;
 import xlings.core.xim.indexfetch;
-import xlings.platform;
 import xlings.runtime;
 
 // `xlings index` — see which index snapshots exist and choose between them.
@@ -34,225 +31,22 @@ struct IndexSourceView {
 // What the local index tree says it is, from the marker written at swap time.
 // Empty when the index was never fetched as an artifact (git-managed, or not
 // fetched at all) -- absent is a real answer here, not a failure.
-std::string installed_index_version(const std::filesystem::path& repoDir) {
-    std::error_code ec;
-    auto marker = repoDir / ".xlings-index-version";
-    if (!std::filesystem::exists(marker, ec)) return {};
-    try {
-        auto v = platform::read_file_to_string(marker.string());
-        while (!v.empty() && (v.back() == '\n' || v.back() == '\r' || v.back() == ' '))
-            v.pop_back();
-        return v;
-    } catch (...) { return {}; }
-}
+std::string installed_index_version(const std::filesystem::path& repoDir);
 
 // Read every configured index source and resolve what this client would pick.
 // Never throws and never fails the command: a source whose pointer cannot be
 // read is reported as such, because "I could not look" and "there is nothing"
 // are different answers.
-std::vector<IndexSourceView> collect_index_sources() {
-    std::vector<IndexSourceView> views;
-    for (const auto& repo : Config::global_index_repos()) {
-        IndexSourceView view;
-        view.name = repo.name;
-        view.pin  = repo.version;
-        view.installed = installed_index_version(Config::repo_dir_for(repo, false));
+std::vector<IndexSourceView> collect_index_sources();
 
-        auto source = artifact_source_for(repo);
-        const auto& pointers = load_index_pointers(Config::mirror(),
-                                                   source ? &*source : nullptr);
-        const auto key = source ? source->key : repo.name;
-        const auto* manifest = select_manifest(pointers, key, source.has_value());
-        if (!manifest) {
-            view.error = pointers.empty()
-                ? "pointer unavailable (offline, or this repo is git-only)"
-                : std::format("no pointer entry for '{}'", key);
-            views.push_back(std::move(view));
-            continue;
-        }
-        view.hasPointer = true;
-        view.snapshots  = snapshots_of(*manifest);
-        view.truncated  = manifest->history_truncated;
-        if (auto choice = choose_snapshot(*manifest, Info::VERSION, repo.version)) {
-            view.current = choice->snapshot.index_version;
-        } else {
-            view.error = choice.error();
-        }
-        views.push_back(std::move(view));
-    }
-    return views;
-}
+nlohmann::json index_sources_json(const std::vector<IndexSourceView>& views);
 
-nlohmann::json index_sources_json(const std::vector<IndexSourceView>& views) {
-    nlohmann::json out = nlohmann::json::array();
-    for (const auto& view : views) {
-        nlohmann::json entry;
-        entry["name"]      = view.name;
-        entry["pinned"]    = view.pin;
-        entry["current"]   = view.current;
-        // What is on disk, which is not the same question as what would be
-        // picked: between a pointer moving and the next `update`, the two differ
-        // and only this one describes the tree the client is actually reading.
-        entry["installed"] = view.installed;
-        entry["truncated"] = view.truncated;
-        if (!view.error.empty()) entry["error"] = view.error;
-        entry["snapshots"] = nlohmann::json::array();
-        for (const auto& s : view.snapshots) {
-            nlohmann::json row;
-            row["index_version"] = s.index_version;
-            row["generated_at"]  = s.generated_at;
-            row["current"]       = s.index_version == view.current;
-            row["installed"]     = !view.installed.empty()
-                                   && s.index_version == view.installed;
-            // Verbatim. Normalising here would make xlings an interpreter of
-            // contracts it does not own.
-            row["requires"]      = s.requirements;
-            row["artifact"]      = { {"name", s.artifact_name},
-                                     {"sha256", s.artifact_sha256},
-                                     {"size", s.artifact_size} };
-            entry["snapshots"].push_back(std::move(row));
-        }
-        out.push_back(std::move(entry));
-    }
-    return out;
-}
-
-int cmd_index_list(const std::string& filter, bool asJson, EventStream& stream) {
-    auto views = collect_index_sources();
-    if (!filter.empty()) {
-        std::erase_if(views, [&](const auto& v) { return v.name != filter; });
-        if (views.empty()) {
-            log::error("no index source named '{}'", filter);
-            return 1;
-        }
-    }
-
-    if (asJson) {
-        std::println("{}", index_sources_json(views).dump(2));
-        return 0;
-    }
-
-    for (const auto& view : views) {
-        log::println("");
-        log::println("  ◆ {}{}", view.name,
-                     view.pin.empty() ? "" : std::format("  (pinned: {})", view.pin));
-        if (!view.error.empty()) {
-            log::println("    {}", view.error);
-            continue;
-        }
-        for (const auto& s : view.snapshots) {
-            const auto req = requirement_for(s.requirements, "xlings");
-            std::string note;
-            if (req) {
-                if (!req->min.empty()) note += ">= " + req->min;
-                if (!req->max.empty()) note += (note.empty() ? "" : " ") + std::string("< ") + req->max;
-                note = "  requires xlings " + note;
-            }
-            // `*` is the tree on disk -- the packages this client resolves
-            // against right now. `>` is what the next `update` would fetch.
-            // They differ whenever the pointer moved since the last update, and
-            // reporting only the second would answer a question the user did
-            // not ask while looking like it answered theirs.
-            const bool onDisk = !view.installed.empty()
-                                && s.index_version == view.installed;
-            log::println("    {} {}{}{}",
-                         onDisk ? "*" : (s.index_version == view.current ? ">" : " "),
-                         s.index_version,
-                         s.generated_at.empty() ? "" : "  " + s.generated_at,
-                         note);
-        }
-        if (view.truncated) {
-            log::println("      … older snapshots exist but are not listed");
-        }
-        if (view.installed.empty()) {
-            log::println("      (no index on disk yet — run `xlings update`)");
-        } else if (!view.current.empty() && view.current != view.installed) {
-            log::println("      on disk: {} — run `xlings update` to move to {}",
-                         view.installed, view.current);
-        }
-    }
-    log::println("");
-    return 0;
-}
+int cmd_index_list(const std::string& filter, bool asJson, EventStream& stream);
 
 // Pin (or unpin) a source. Writes index_repos[].version so the choice is
 // visible in the config afterwards -- a one-shot flag would be reverted by the
 // next `xlings update` with nothing to show it ever applied.
 int cmd_index_use(const std::string& name, const std::string& version,
-                  EventStream& stream) {
-    if (name.empty()) {
-        log::error("usage: xlings index use <name> <version|latest>");
-        return 2;
-    }
-    const bool clearing = version.empty() || version == "latest";
-
-    // Refuse a version the pointer does not offer -- accepting it would leave a
-    // config that only fails on the next update, far from the command that
-    // wrote it.
-    if (!clearing) {
-        auto views = collect_index_sources();
-        const auto hit = std::ranges::find_if(views,
-            [&](const auto& v) { return v.name == name; });
-        if (hit == views.end()) {
-            log::error("no index source named '{}'", name);
-            return 1;
-        }
-        const bool known = std::ranges::any_of(hit->snapshots,
-            [&](const auto& s) { return s.index_version == version; });
-        if (!known) {
-            log::error("index '{}' has no published snapshot '{}'", name, version);
-            std::string list;
-            for (const auto& s : hit->snapshots) {
-                if (!list.empty()) list += ", ";
-                list += s.index_version;
-            }
-            log::error("  available: {}", list.empty() ? "(none)" : list);
-            return 1;
-        }
-    }
-
-    auto applied = update_home_config(Config::paths().homeDir,
-        [&](nlohmann::json& json) {
-            if (!json.contains("index_repos") || !json["index_repos"].is_array()) {
-                json["index_repos"] = nlohmann::json::array();
-            }
-            for (auto& entry : json["index_repos"]) {
-                if (!entry.is_object() || !entry.contains("name")) continue;
-                if (entry["name"].get<std::string>() != name) continue;
-                if (clearing) entry.erase("version");
-                else entry["version"] = version;
-                return true;
-            }
-            // The source exists in the effective config but not in the file --
-            // it is a built-in default. Materialise the entry so the pin has
-            // somewhere to live.
-            for (const auto& repo : Config::global_index_repos()) {
-                if (repo.name != name) continue;
-                nlohmann::json entry;
-                entry["name"] = repo.name;
-                entry["url"]  = repo.url;
-                if (!clearing) entry["version"] = version;
-                json["index_repos"].push_back(entry);
-                return true;
-            }
-            return false;
-        });
-
-    if (!applied) {
-        log::error("{}", applied.error());
-        return 1;
-    }
-    if (!*applied) {
-        log::error("no index source named '{}'", name);
-        return 1;
-    }
-    if (clearing) {
-        log::println("index '{}' follows the newest compatible snapshot", name);
-    } else {
-        log::println("index '{}' pinned to {}", name, version);
-    }
-    log::println("  run `xlings update` to apply");
-    return 0;
-}
+                  EventStream& stream);
 
 }  // namespace xlings::xim
diff --git a/src/core/xim/indexfetch.cpp b/src/core/xim/indexfetch.cpp
new file mode 100644
index 00000000..edc6c167
--- /dev/null
+++ b/src/core/xim/indexfetch.cpp
@@ -0,0 +1,710 @@
+module xlings.core.xim.indexfetch;
+
+import std;
+import xlings.libs.json;
+import xlings.libs.tinyhttps;
+import xlings.libs.sha256;
+import xlings.core.log;
+import xlings.core.config;
+import xlings.core.mirror;
+import xlings.platform;
+import xlings.core.xim.extract;
+import xlings.core.version_order;
+
+namespace xlings::xim {
+
+namespace detail_ {
+
+// Repo + tag are fixed discovery anchors; overridable for testing/mirrors.
+std::string index_repo_name_() {
+    if (auto* e = std::getenv("XLINGS_INDEX_REPO"); e && *e) return e;
+    return "xim-index";
+}
+
+std::string index_tag_() {
+    if (auto* e = std::getenv("XLINGS_INDEX_TAG"); e && *e) return e;
+    return "latest";
+}
+
+std::string lower_hex_(std::string s) {
+    for (auto& c : s) c = static_cast<char>(std::tolower((unsigned char)c));
+    return s;
+}
+
+// Download the first working candidate URL into destFile, trying each candidate
+// explicitly and continuing past ANY failure — including HTTP 404. This differs
+// from tinyhttps::download_file's internal candidate loop, which treats 404 as a
+// definitive not-found and stops (correct for a single authoritative asset, but
+// wrong for index mirrors: one server 404ing must fall through to the next, e.g.
+// gitcode 404 -> github). When wantSha256 is set, a candidate is accepted only
+// if its bytes match. Returns empty string on success, else the last error.
+std::string download_candidates_(std::vector<std::string> urls,
+                                 const std::filesystem::path& destFile,
+                                 std::string_view wantSha256) {
+    if (urls.empty()) return "no candidate URLs";
+    // With a pinned sha256, mirrors may race ahead of the authoritative URL;
+    // without one (the manifest pointer), keep the authoritative server first.
+    urls = mirror::adaptive::reorder(std::move(urls), !wantSha256.empty());
+
+    std::string want = wantSha256.empty() ? std::string{} : lower_hex_(std::string(wantSha256));
+    std::string lastErr;
+    for (const auto& u : urls) {
+        tinyhttps::DownloadOptions opts;
+        opts.destFile = destFile;
+        opts.urls = { u };          // one URL per call: we own the fallthrough
+        opts.retryCount = 1;        // breadth over depth; don't hammer a 404
+        opts.onUrlAttemptFailed = [](const std::string& url, const std::string& e) {
+            // Demote a host that stalled / served bad bytes / timed out / gave no
+            // response so later fetches this session skip it. Do NOT penalize on
+            // plain 404/401: the asset is just absent on that mirror (e.g. gitcode
+            // 404s .json) — the host is fine for other assets.
+            if (e.find("404") == std::string::npos && e.find("401") == std::string::npos)
+                mirror::adaptive::penalize_host(url);
+        };
+        if (!want.empty()) {
+            opts.onVerify = [destFile, want](const std::string& url) -> std::string {
+                auto digest = sha256::hex_file(destFile);
+                if (digest && *digest == want) return {};
+                return std::format("sha256 mismatch (source {}): got {}, want {}",
+                                   url, digest ? *digest : "<unreadable>", want);
+            };
+        }
+        auto r = tinyhttps::download_file(opts);
+        if (r.success) return {};
+        lastErr = r.error.empty() ? ("failed: " + u) : r.error;
+        log::debug("[index] candidate failed ({}): {}", u, lastErr);
+    }
+    return lastErr.empty() ? "all candidates failed" : lastErr;
+}
+
+BaseOverride resolve_base_() {
+    BaseOverride b;
+    std::string v;
+    if (auto* e = std::getenv("XLINGS_INDEX_BASE_URL"); e && *e) v = e;
+    else v = Config::index_base();   // .xlings.json xim.index-base (region-aware), else ""
+    if (v.empty()) return b;
+    while (!v.empty() && v.back() == '/') v.pop_back();
+    b.base = v;
+    if (v.starts_with("file://")) b.local = std::filesystem::path(v.substr(7));
+    else if (v.find("://") == std::string::npos) b.local = std::filesystem::path(v);
+    return b;
+}
+
+// Obtain `filename` into `dest`: local-dir copy, or remote (base override, else
+// the given remoteUrls). Verifies sha256 when wantSha is non-empty.
+// #377: `forced` replaces the global env/config base override entirely — a
+// custom source must never be redirected by XLINGS_INDEX_BASE_URL; a forge
+// custom source passes an EMPTY override ("use the URL list as-is").
+std::string obtain_file(const std::string& filename, std::vector<std::string> remoteUrls,
+                        const std::filesystem::path& dest, std::string_view wantSha,
+                        const BaseOverride* forced = nullptr) {
+    namespace fs = std::filesystem;
+    auto b = forced ? *forced : resolve_base_();
+    if (b.local) {
+        std::error_code ec;
+        auto src = *b.local / filename;
+        if (!fs::exists(src, ec)) return std::format("local file not found: {}", src.string());
+        fs::copy_file(src, dest, fs::copy_options::overwrite_existing, ec);
+        if (ec) return std::format("copy {} failed: {}", src.string(), ec.message());
+        if (!wantSha.empty()) {
+            auto digest = sha256::hex_file(dest);
+            auto want = lower_hex_(std::string(wantSha));
+            if (!digest || *digest != want)
+                return std::format("sha256 mismatch (local {}): got {}, want {}",
+                                   src.string(), digest ? *digest : "<unreadable>", want);
+        }
+        return {};
+    }
+    auto urls = b.base.empty() ? std::move(remoteUrls)
+                               : std::vector<std::string>{ b.base + "/" + filename };
+    return download_candidates_(std::move(urls), dest, wantSha);
+}
+
+// #377: forced base for a custom source: local-dir copy, flat-remote base, or
+// (for forge bases) an EMPTY override meaning "use the passed URL list, but do
+// NOT apply the global index-base override".
+BaseOverride base_override_for_(const ArtifactSource& src) {
+    BaseOverride b;
+    if (src.localDir) { b.local = src.localDir; b.base = src.base; }
+    else if (!src.forge()) b.base = src.base;
+    return b;
+}
+
+}
+
+std::optional<IndexManifest> parse_index_manifest(std::string_view jsonText) {
+    try {
+        auto j = nlohmann::json::parse(jsonText);
+        if (!j.is_object() || !j.contains("artifact") || !j["artifact"].is_object())
+            return std::nullopt;
+        auto& art = j["artifact"];
+        if (!art.contains("name") || !art.contains("sha256")) return std::nullopt;
+
+        IndexManifest m;
+        m.format_version  = j.value("format_version", 0);
+        m.index_version   = j.value("index_version", std::string{});
+        m.index_name      = j.value("index_name", std::string{"xim"});
+        m.generated_at    = j.value("generated_at", std::string{});
+        m.source_commit   = j.value("source_commit", std::string{});
+        m.artifact_name   = art.value("name", std::string{});
+        m.artifact_sha256 = detail_::lower_hex_(art.value("sha256", std::string{}));
+        m.artifact_size   = art.value("size", std::uint64_t{0});
+        if (m.artifact_name.empty() || m.artifact_sha256.empty()) return std::nullopt;
+
+        // #476, all optional: a pointer without them parses exactly as before.
+        if (j.contains("requires") && j["requires"].is_object()) {
+            m.requirements = j["requires"];
+        }
+        m.history_truncated = j.value("history_truncated", false);
+        if (j.contains("history") && j["history"].is_array()) {
+            for (const auto& e : j["history"]) {
+                if (!e.is_object() || !e.contains("artifact")
+                    || !e["artifact"].is_object()) continue;
+                const auto& ea = e["artifact"];
+                IndexSnapshot s;
+                s.index_version   = e.value("index_version", std::string{});
+                s.generated_at    = e.value("generated_at", std::string{});
+                s.artifact_name   = ea.value("name", std::string{});
+                s.artifact_sha256 = detail_::lower_hex_(ea.value("sha256", std::string{}));
+                s.artifact_size   = ea.value("size", std::uint64_t{0});
+                if (e.contains("requires") && e["requires"].is_object()) {
+                    s.requirements = e["requires"];
+                }
+                // A history entry with no artifact identity is unusable; drop it
+                // rather than carrying a row that cannot be selected.
+                if (s.index_version.empty() || s.artifact_name.empty()
+                    || s.artifact_sha256.empty()) continue;
+                m.history.push_back(std::move(s));
+            }
+        }
+        return m;
+    } catch (...) {
+        return std::nullopt;
+    }
+}
+
+std::optional<IndexRequirement> requirement_for(const nlohmann::json& requirements,
+                                                std::string_view consumer) {
+    if (!requirements.is_object()) return std::nullopt;
+    const auto it = requirements.find(std::string(consumer));
+    if (it == requirements.end() || !it->is_object()) return std::nullopt;
+    IndexRequirement req;
+    req.min = it->value("min", std::string{});
+    req.max = it->value("max", std::string{});
+    if (req.empty()) return std::nullopt;
+    return req;
+}
+
+bool satisfies_requirement(std::string_view selfVersion, const IndexRequirement& req) {
+    if (!req.min.empty() && version_order::compare(selfVersion, req.min) < 0) return false;
+    if (!req.max.empty() && version_order::compare(selfVersion, req.max) >= 0) return false;
+    return true;
+}
+
+std::vector<IndexSnapshot> snapshots_of(const IndexManifest& manifest) {
+    if (!manifest.history.empty()) return manifest.history;
+    IndexSnapshot only;
+    only.index_version   = manifest.index_version;
+    only.generated_at    = manifest.generated_at;
+    only.artifact_name   = manifest.artifact_name;
+    only.artifact_sha256 = manifest.artifact_sha256;
+    only.artifact_size   = manifest.artifact_size;
+    only.requirements    = manifest.requirements;
+    return {only};
+}
+
+namespace detail_ {
+
+std::string describe_requirement_(const IndexSnapshot& s) {
+    const auto req = requirement_for(s.requirements, "xlings");
+    if (!req) return "no requirement";
+    std::string out;
+    if (!req->min.empty()) out += ">= " + req->min;
+    if (!req->max.empty()) out += (out.empty() ? "" : " ") + std::string("< ") + req->max;
+    return out;
+}
+
+}
+
+std::expected<SnapshotChoice, std::string> choose_snapshot(
+    const IndexManifest& manifest, std::string_view selfVersion, std::string_view pin) {
+    const auto snapshots = snapshots_of(manifest);
+    if (snapshots.empty()) return std::unexpected("pointer lists no index snapshot");
+
+    const auto available = [&] {
+        std::string list;
+        for (const auto& s : snapshots) {
+            if (!list.empty()) list += ", ";
+            list += s.index_version;
+        }
+        if (manifest.history_truncated) list += ", … (history truncated)";
+        return list;
+    };
+
+    // "newest": take the head of the list whatever it requires. This is the
+    // escape hatch `self update` runs on, and it is what breaks the deadlock a
+    // routed-back client would otherwise sit in forever -- an old snapshot's
+    // own xlings recipe names an old `latest`, so a client routed there could
+    // never see, let alone install, the version that would let it move on.
+    if (pin == "newest") {
+        SnapshotChoice choice{snapshots.front(), true, {}};
+        return choice;
+    }
+
+    // Explicit pin: honour it exactly. It bypasses the contract check -- asking
+    // for a specific snapshot is a deliberate act, often to reproduce a bug --
+    // but never the sha256 check downstream.
+    if (!pin.empty() && pin != "latest") {
+        for (const auto& s : snapshots) {
+            if (s.index_version == pin) {
+                SnapshotChoice choice{s, &s == &snapshots.front(), {}};
+                if (!choice.isNewest) {
+                    choice.reason = std::format("pinned to {}", pin);
+                }
+                return choice;
+            }
+        }
+        return std::unexpected(std::format(
+            "E_INDEX_VERSION_NOT_FOUND: pinned to '{}', which the pointer does "
+            "not offer; available: {}", pin, available()));
+    }
+
+    // Automatic routing: newest snapshot whose contract this client meets.
+    for (std::size_t i = 0; i < snapshots.size(); ++i) {
+        const auto& s = snapshots[i];
+        const auto req = requirement_for(s.requirements, "xlings");
+        if (req && !satisfies_requirement(selfVersion, *req)) continue;
+        SnapshotChoice choice{s, i == 0, {}};
+        if (i != 0) {
+            choice.reason = std::format(
+                "{} requires xlings {}, this is {}",
+                snapshots.front().index_version,
+                detail_::describe_requirement_(snapshots.front()), selfVersion);
+        }
+        return choice;
+    }
+
+    return std::unexpected(std::format(
+        "E_INDEX_NO_COMPATIBLE_SNAPSHOT: this xlings is {} and no published "
+        "snapshot accepts it (newest {} requires xlings {}); available: {}",
+        selfVersion, snapshots.front().index_version,
+        detail_::describe_requirement_(snapshots.front()), available()));
+}
+
+std::optional<ArtifactSource> artifact_source_for(const IndexRepo& repo) {
+    std::string base = repo.artifactBase;
+    if (base.empty()) return std::nullopt;
+    while (base.size() > 1 && base.ends_with('/')) base.pop_back();
+
+    ArtifactSource src;
+    src.base = base;
+    src.key  = repo.name;
+
+    std::string pathPart = base;
+    if (base.starts_with("file://")) {
+        src.localDir = std::filesystem::path(base.substr(7)).lexically_normal();
+        pathPart = src.localDir->generic_string();
+    } else if (base.find("://") == std::string::npos) {
+        src.localDir = std::filesystem::path(base).lexically_normal();
+        pathPart = src.localDir->generic_string();
+    }
+
+    auto slash = pathPart.find_last_of("/\\");
+    src.repoName = slash == std::string::npos ? pathPart : pathPart.substr(slash + 1);
+    if (src.repoName.empty()) return std::nullopt;
+
+    if (!src.localDir) {
+        auto rest = base.substr(base.find("://") + 3);
+        auto firstSlash = rest.find('/');
+        auto host = firstSlash == std::string::npos ? rest : rest.substr(0, firstSlash);
+        if (host.find("github.com") != std::string::npos ||
+            host.find("gitcode.com") != std::string::npos) {
+            src.server = base.substr(0, base.find_last_of('/'));  // scheme://host/org
+        }
+    }
+    return src;
+}
+
+const IndexManifest* select_manifest(const std::map<std::string, IndexManifest>& pointers,
+                                     std::string_view key, bool soleEntryFallback) {
+    if (auto it = pointers.find(std::string(key)); it != pointers.end()) return &it->second;
+    if (soleEntryFallback && pointers.size() == 1) return &pointers.begin()->second;
+    return nullptr;
+}
+
+std::vector<std::string> index_asset_urls(std::string_view filename,
+                                          std::string_view mirror,
+                                          std::string_view version,
+                                          const ArtifactSource* custom) {
+    // #377: a per-repo source replaces the official server set entirely.
+    if (custom) {
+        if (custom->forge()) {
+            std::vector<std::string> tags;
+            if (!version.empty()) tags.push_back("v" + std::string(version));
+            tags.push_back("latest");   // GitHub rolling fallback; a 404 falls through
+            std::vector<std::string> urls;
+            for (auto& tag : tags)
+                urls.push_back(std::format("{}/{}/releases/download/{}/{}",
+                                           custom->server, custom->repoName, tag, filename));
+            return urls;
+        }
+        if (!custom->localDir) return { custom->base + "/" + std::string(filename) };
+        return {};  // local dir: obtain_file consumes a forced BaseOverride instead
+    }
+
+    std::vector<std::string> urls;
+    auto add = [&](const std::string& u) {
+        if (!u.empty() && std::ranges::find(urls, u) == urls.end()) urls.push_back(u);
+    };
+
+    auto repo = detail_::index_repo_name_();
+
+    // Release tag(s) to try, in order. GitCode only serves release assets via
+    // the VERSIONED tag (`v<version>`); its rolling `latest` tag 404s on the
+    // `releases/download/latest/<asset>` path (GitHub serves both). So when we
+    // know the version, try `v<version>` first and keep `latest` as a fallback.
+    std::vector<std::string> tags;
+    if (!version.empty()) tags.push_back("v" + std::string(version));
+    if (auto def = detail_::index_tag_(); std::ranges::find(tags, def) == tags.end())
+        tags.push_back(def);
+
+    // Selected (latency-probed) server first, then all other candidates.
+    auto selected = Config::resource_server(mirror);
+    auto buildFor = [&](const std::string& server, const std::string& tag) {
+        return std::format("{}/{}/releases/download/{}/{}", server, repo, tag, filename);
+    };
+    auto addServer = [&](const std::string& server) {
+        if (server.empty()) return;
+        for (auto& tag : tags) add(buildFor(server, tag));
+    };
+    addServer(selected);
+    for (auto& server : Config::resource_servers(mirror)) addServer(server);
+    // Always include GLOBAL (github) servers as fallback for the index — even
+    // under CN. Unlike package binaries (where the regional mirror is
+    // authoritative), the index must stay reachable if the regional mirror
+    // lacks the asset; combined with 404-fallthrough this gives CN: gitcode ->
+    // github -> github proxies.
+    for (auto& server : Config::resource_servers("GLOBAL")) addServer(server);
+
+    // NB: deliberately NO github-proxy expansion (ghfast/ghproxy/kkgithub) for
+    // the index. Those proxies are often TCP-reachable but don't actually serve
+    // the asset, so a fast-latency-but-dead proxy ranked ahead of github causes
+    // a ~30s timeout per dead host (the CN "fetching package index" hang). The
+    // index is small; gitcode + github-direct (region-ordered) is enough, and a
+    // gitcode 404/miss falls through to github fast.
+    return urls;
+}
+
+std::vector<std::string> index_pointer_urls(std::string_view filename,
+                                            std::string_view mirror,
+                                            const ArtifactSource* custom) {
+    auto rawFor = [&](const std::string& server, const std::string& repo) -> std::string {
+        auto pos = server.find("://");
+        std::string rest = pos == std::string::npos ? server : server.substr(pos + 3);
+        auto slash = rest.find('/');
+        if (slash == std::string::npos) return {};
+        std::string host = rest.substr(0, slash);
+        std::string org  = rest.substr(slash + 1);
+        while (!org.empty() && org.back() == '/') org.pop_back();
+        if (host.find("github.com") != std::string::npos)
+            return std::format("https://raw.githubusercontent.com/{}/{}/main/{}", org, repo, filename);
+        if (host.find("gitcode.com") != std::string::npos)
+            // Correct raw form is .../<o>/<r>/raw/main/<f> — it serves the RAW
+            // bytes (incl .json). The .../main/<f> form (no /raw/) returns the
+            // HTML web page. (403s seen while probing were request rate-limiting.)
+            return std::format("https://raw.gitcode.com/{}/{}/raw/main/{}", org, repo, filename);
+        return {};
+    };
+
+    // #377: per-repo source — one authoritative location, no official mirrors.
+    if (custom) {
+        if (custom->forge()) {
+            if (auto u = rawFor(custom->server, custom->repoName); !u.empty()) return {u};
+            return {};
+        }
+        if (!custom->localDir) return { custom->base + "/" + std::string(filename) };
+        return {};  // local dir: obtain_file consumes a forced BaseOverride instead
+    }
+
+    auto repo = detail_::index_repo_name_();
+    std::vector<std::string> urls;
+    auto add = [&](const std::string& u){
+        if (!u.empty() && std::ranges::find(urls, u) == urls.end()) urls.push_back(u);
+    };
+    auto selected = Config::resource_server(mirror);
+    if (!selected.empty()) add(rawFor(selected, repo));
+    for (auto& s : Config::resource_servers(mirror))   add(rawFor(s, repo));
+    for (auto& s : Config::resource_servers("GLOBAL")) add(rawFor(s, repo));
+    return urls;
+}
+
+  // namespace detail_
+
+// Newest published version of `consumer` as the pointer advertises it, or ""
+// when the pointer does not say. Requires load_index_pointers() to have run
+// for the same source (fetch_index_artifact always does).
+std::string client_latest_for(std::string_view consumer, const ArtifactSource* custom) {
+    const std::string cacheKey = custom ? custom->base : std::string{};
+    const auto& all = detail_::client_latest_cache_();
+    const auto base = all.find(cacheKey);
+    if (base == all.end()) return {};
+    const auto hit = base->second.find(std::string(consumer));
+    return hit == base->second.end() ? std::string{} : hit->second;
+}
+
+const std::map<std::string, IndexManifest>& load_index_pointers(std::string_view mirror,
+                                                                const ArtifactSource* custom) {
+    // #377: keyed per base (official = ""), same fetch-once-per-process
+    // semantics the old once_flag gave the official pointer.
+    static std::mutex mu;
+    static std::map<std::string, std::map<std::string, IndexManifest>> cacheByBase;
+    static std::set<std::string> fetched;
+    std::string cacheKey = custom ? custom->base : std::string{};
+    std::scoped_lock lk(mu);
+    auto& cache = cacheByBase[cacheKey];
+    if (fetched.contains(cacheKey)) return cache;
+    fetched.insert(cacheKey);
+
+    std::string filename = custom ? custom->repoName + "-pointers.json"
+                                  : std::string("xim-index-pointers.json");
+    namespace fs = std::filesystem;
+    auto tmp = fs::temp_directory_path() /
+               std::format("xim-index-pointers.{}.{}.json", platform::get_pid(), fetched.size());
+    std::error_code ec; fs::remove(tmp, ec);
+    detail_::BaseOverride forcedStorage;
+    const detail_::BaseOverride* forced = nullptr;
+    if (custom) { forcedStorage = detail_::base_override_for_(*custom); forced = &forcedStorage; }
+    auto err = detail_::obtain_file(filename, index_pointer_urls(filename, mirror, custom),
+                                    tmp, {}, forced);
+    if (!err.empty()) { log::warn("[index] pointer fetch failed: {}", err); return cache; }
+    std::string text;
+    { std::ifstream in(tmp, std::ios::binary); std::stringstream ss; ss << in.rdbuf(); text = ss.str(); }
+    fs::remove(tmp, ec);
+    try {
+        auto j = nlohmann::json::parse(text);
+        if (j.contains("indexes") && j["indexes"].is_object())
+            for (auto it = j["indexes"].begin(); it != j["indexes"].end(); ++it)
+                if (auto m = parse_index_manifest(it.value().dump())) cache[it.key()] = *m;
+        // #476: newest CLIENT version, carried at pointer top level so it is
+        // readable no matter which index snapshot this client routes to. That
+        // is the half of the deadlock fix a routed-back client depends on: an
+        // old snapshot's own xlings recipe names an old `latest`, so without
+        // this the client could never learn a newer one exists.
+        if (j.contains("client_latest") && j["client_latest"].is_object()) {
+            auto& slot = detail_::client_latest_cache_()[cacheKey];
+            for (auto it = j["client_latest"].begin(); it != j["client_latest"].end(); ++it)
+                if (it.value().is_string()) slot[it.key()] = it.value().get<std::string>();
+        }
+    } catch (...) { log::warn("[index] pointer parse failed"); }
+    return cache;
+}
+
+bool fetch_index_artifact(const std::filesystem::path& destIndexDir,
+                          std::string& err,
+                          std::string_view subName,
+                          const ArtifactSource* custom,
+                          std::string_view pin) {
+    namespace fs = std::filesystem;
+    auto mirrorKey = Config::mirror();
+    std::string key = custom ? custom->key
+                             : (subName.empty() ? std::string("xim") : std::string(subName));
+
+    std::string label = subName.empty()
+        ? std::string("package index")
+        : std::format("sub-index '{}'", subName);
+    log::info("[index] fetching {} (mirror={})...",
+              label, mirrorKey.empty() ? "GLOBAL" : mirrorKey);
+
+    auto& pointers = load_index_pointers(mirrorKey, custom);
+    const IndexManifest* pm = select_manifest(pointers, key, custom != nullptr);
+    if (!pm) {
+        err = std::format("no pointer entry for '{}' ({} entries)", key, pointers.size());
+        return false;
+    }
+    const IndexManifest& manifest = *pm;
+    if (manifest.format_version != 1) {
+        err = std::format("unsupported index manifest format_version {}", manifest.format_version);
+        return false;
+    }
+
+    // #476: route to the newest snapshot this client's version accepts, or to
+    // an explicit pin. On failure the local index tree is left alone -- keeping
+    // the last snapshot that worked beats replacing it with a wrong one.
+    // XLINGS_INDEX_PIN overrides the per-repo pin: an escape hatch for
+    // debugging, and the mechanism `self update` uses to reach a newer client
+    // through an index this version would not otherwise route to.
+    std::string effectivePin{pin};
+    if (const auto* env = std::getenv("XLINGS_INDEX_PIN"); env && *env) {
+        effectivePin = env;
+    }
+    const auto choice = choose_snapshot(manifest, Info::VERSION, effectivePin);
+    if (!choice) { err = choice.error(); return false; }
+    const IndexSnapshot& snapshot = choice->snapshot;
+
+    // Say it when we step back. A client that silently sits on an older index
+    // looks to its user exactly like one on the newest, right up until a
+    // package it expects is missing.
+    if (!choice->isNewest) {
+        log::warn("[index] {}: using {} instead of {}", key,
+                  snapshot.index_version, manifest.index_version);
+        log::warn("[index]   {}", choice->reason);
+        if (auto newer = client_latest_for("xlings", custom);
+            !newer.empty() && version_order::compare(newer, Info::VERSION) > 0) {
+            log::warn("[index]   upgrade to {}: xlings self update", newer);
+        }
+    }
+
+    std::error_code ec;
+    auto tmpRoot = fs::path(destIndexDir.string() + ".artifact." +
+                            std::to_string(platform::get_pid()));
+    fs::remove_all(tmpRoot, ec);
+    fs::create_directories(tmpRoot, ec);
+    if (ec) { err = std::format("create temp dir failed: {}", ec.message()); return false; }
+    struct Cleanup { fs::path p; ~Cleanup(){ std::error_code e; fs::remove_all(p,e);} } cleanup{tmpRoot};
+
+    // Artifact (sha256-pinned by the manifest); release asset, versioned name.
+    auto artifactFile = tmpRoot / snapshot.artifact_name;
+    detail_::BaseOverride forcedStorage;
+    const detail_::BaseOverride* forced = nullptr;
+    if (custom) { forcedStorage = detail_::base_override_for_(*custom); forced = &forcedStorage; }
+    if (auto e = detail_::obtain_file(snapshot.artifact_name,
+                    index_asset_urls(snapshot.artifact_name, mirrorKey,
+                                     snapshot.index_version, custom),
+                    artifactFile, snapshot.artifact_sha256, forced); !e.empty()) {
+        err = std::format("fetch index artifact failed: {}", e);
+        return false;
+    }
+
+    // 3. Extract to a staging dir, sanity-check, atomically swap into place.
+    auto stage = tmpRoot / "stage";
+    auto extracted = extract_archive(artifactFile, stage);
+    if (!extracted) { err = std::format("extract index artifact failed: {}", extracted.error()); return false; }
+    if (!fs::exists(stage / "pkgs", ec)) {
+        err = "extracted index missing pkgs/";
+        return false;
+    }
+
+    // Record the installed version for diagnostics / future ETag-style checks.
+    // This is the version of the snapshot that actually lands, NOT the head of
+    // the pointer -- routing (#476) makes those differ, and both readers care:
+    // a human debugging "where did my package go" reads this file, and
+    // get_repo_head_hash() keys the parsed-index cache on it. Writing the head
+    // here would name a tree that is not on disk, and would change on every
+    // publish for a client that keeps landing on the same old snapshot --
+    // rebuilding that client's cache forever.
+    {
+        std::ofstream v(stage / ".xlings-index-version", std::ios::binary);
+        v << snapshot.index_version;
+    }
+
+    auto backup = fs::path(destIndexDir.string() + ".old." +
+                           std::to_string(platform::get_pid()));
+    fs::remove_all(backup, ec);
+    if (fs::exists(destIndexDir, ec)) {
+        // Preferred path: a single atomic exchange of the live dir and the staged
+        // dir. There is no instant where destIndexDir is missing, so a crash /
+        // SIGKILL mid-swap cannot strand the index (which previously degraded the
+        // official index to a destructive git clone on the next run — see
+        // .agents/docs/2026-06-30-index-artifact-git-regression-analysis.md).
+        if (platform::atomic_swap_paths(destIndexDir, stage)) {
+            // After the exchange, `stage` now holds the OLD tree — drop it.
+            fs::remove_all(stage, ec);
+            log::info("[index] updated from artifact {} ({})",
+                      snapshot.artifact_name,
+                      snapshot.index_version.empty() ? "?" : snapshot.index_version);
+            return true;
+        }
+        // Fallback (non-Linux / kernel without renameat2): manual move-aside.
+        // Narrow the kill-window by keeping the backup recoverable — a leftover
+        // `.old.<pid>` that still holds pkgs/ is restored on the next run by
+        // reconcile_index_temps() before any git fallback can fire.
+        fs::rename(destIndexDir, backup, ec);
+        if (ec) { err = std::format("swap (move old) failed: {}", ec.message()); return false; }
+    }
+    fs::rename(stage, destIndexDir, ec);
+    if (ec) {
+        // Roll back to the old tree if the swap-in failed.
+        std::error_code e2;
+        if (fs::exists(backup, e2)) fs::rename(backup, destIndexDir, e2);
+        err = std::format("swap (move new) failed: {}", ec.message());
+        return false;
+    }
+    fs::remove_all(backup, ec);
+
+    // The SNAPSHOT that landed, not the manifest's head. Reporting the head
+    // here would print `updated from xim-index-new0003` immediately after
+    // "using old0001 instead of new0003" -- and this line is what the release
+    // verification runbook greps to decide which artifact a run actually used
+    // (reference_index_publish_lag).
+    log::info("[index] updated from artifact {} ({})",
+              snapshot.artifact_name,
+              snapshot.index_version.empty() ? "?" : snapshot.index_version);
+    return true;
+}
+
+void reconcile_index_temps(const std::filesystem::path& dataDir) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    if (!fs::is_directory(dataDir, ec)) return;
+
+    struct Temp { fs::path path; fs::path base; std::string kind; int pid; };
+    std::vector<Temp> temps;
+    // Compare against std::default_sentinel (not a second directory_iterator):
+    // clang/libc++ only provides operator==(default_sentinel_t), so a two-iterator
+    // range-for fails to compile there. Increment with the error_code overload so
+    // a bad entry never throws out of this best-effort reconciler.
+    for (auto it = fs::directory_iterator(dataDir, ec);
+         it != std::default_sentinel; it.increment(ec)) {
+        if (ec) break;
+        const auto& entry = *it;
+        std::error_code dec;
+        if (!entry.is_directory(dec)) continue;
+        auto name = entry.path().filename().string();
+        for (std::string_view kind : {".artifact.", ".old.", ".tmp."}) {
+            auto pos = name.rfind(kind);
+            if (pos == std::string::npos) continue;
+            auto pidStr = name.substr(pos + kind.size());
+            int pid = 0;
+            auto* begin = pidStr.data();
+            auto* end = begin + pidStr.size();
+            auto [ptr, errc] = std::from_chars(begin, end, pid);
+            if (errc != std::errc{} || ptr != end) break;  // suffix isn't a bare pid
+            temps.push_back({entry.path(), dataDir / name.substr(0, pos),
+                             std::string(kind), pid});
+            break;
+        }
+    }
+
+    for (auto& t : temps) {
+        // Never touch staging owned by an in-flight xlings process.
+        if (t.pid > 0 && platform::is_process_alive(t.pid)) continue;
+
+        bool baseUsable   = fs::exists(t.base / "pkgs", ec);
+        bool orphanUsable = fs::exists(t.path / "pkgs", ec);
+
+        if (t.kind == ".old." && orphanUsable && !baseUsable) {
+            // Interrupted swap: this orphan is the only surviving index copy.
+            fs::remove_all(t.base, ec);          // clear an empty / partial base
+            fs::rename(t.path, t.base, ec);
+            if (!ec)
+                log::warn("[index] recovered interrupted index swap: restored {} from {}",
+                          t.base.filename().string(), t.path.filename().string());
+            continue;
+        }
+        // Spent staging / leaked temp from a dead process — reclaim the space.
+        fs::remove_all(t.path, ec);
+    }
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::xim {
+
+bool IndexRequirement::empty() const { return min.empty() && max.empty(); }
+
+bool ArtifactSource::forge() const { return !server.empty(); }
+
+} // namespace xlings::xim
diff --git a/src/core/xim/indexfetch.cppm b/src/core/xim/indexfetch.cppm
index 884ab064..612cd9e4 100644
--- a/src/core/xim/indexfetch.cppm
+++ b/src/core/xim/indexfetch.cppm
@@ -24,13 +24,9 @@ export module xlings.core.xim.indexfetch;
 import std;
 import xlings.libs.json;
 import xlings.libs.tinyhttps;
-import xlings.libs.sha256;
-import xlings.core.log;
 import xlings.core.config;
 import xlings.core.mirror;
-import xlings.platform;
 import xlings.core.xim.extract;
-import xlings.core.version_order;
 
 export namespace xlings::xim {
 
@@ -43,7 +39,7 @@ export namespace xlings::xim {
 struct IndexRequirement {
     std::string min;   // inclusive
     std::string max;   // exclusive
-    bool empty() const { return min.empty() && max.empty(); }
+    bool empty() const;
 };
 
 // One addressable index snapshot: an artifact plus what it asks of its client.
@@ -129,7 +125,7 @@ struct ArtifactSource {
     std::string repoName;  // last path segment of base — pointer file prefix
     std::string key;       // manifest lookup key (config repo name)
     std::optional<std::filesystem::path> localDir;  // set when base is local
-    bool forge() const { return !server.empty(); }
+    bool forge() const;
 };
 
 // Build an ArtifactSource for a repo, or nullopt when it declares none.
@@ -193,67 +189,6 @@ namespace xlings::xim {
 
 namespace detail_ {
 
-// Repo + tag are fixed discovery anchors; overridable for testing/mirrors.
-std::string index_repo_name_() {
-    if (auto* e = std::getenv("XLINGS_INDEX_REPO"); e && *e) return e;
-    return "xim-index";
-}
-std::string index_tag_() {
-    if (auto* e = std::getenv("XLINGS_INDEX_TAG"); e && *e) return e;
-    return "latest";
-}
-
-std::string lower_hex_(std::string s) {
-    for (auto& c : s) c = static_cast<char>(std::tolower((unsigned char)c));
-    return s;
-}
-
-// Download the first working candidate URL into destFile, trying each candidate
-// explicitly and continuing past ANY failure — including HTTP 404. This differs
-// from tinyhttps::download_file's internal candidate loop, which treats 404 as a
-// definitive not-found and stops (correct for a single authoritative asset, but
-// wrong for index mirrors: one server 404ing must fall through to the next, e.g.
-// gitcode 404 -> github). When wantSha256 is set, a candidate is accepted only
-// if its bytes match. Returns empty string on success, else the last error.
-std::string download_candidates_(std::vector<std::string> urls,
-                                 const std::filesystem::path& destFile,
-                                 std::string_view wantSha256) {
-    if (urls.empty()) return "no candidate URLs";
-    // With a pinned sha256, mirrors may race ahead of the authoritative URL;
-    // without one (the manifest pointer), keep the authoritative server first.
-    urls = mirror::adaptive::reorder(std::move(urls), !wantSha256.empty());
-
-    std::string want = wantSha256.empty() ? std::string{} : lower_hex_(std::string(wantSha256));
-    std::string lastErr;
-    for (const auto& u : urls) {
-        tinyhttps::DownloadOptions opts;
-        opts.destFile = destFile;
-        opts.urls = { u };          // one URL per call: we own the fallthrough
-        opts.retryCount = 1;        // breadth over depth; don't hammer a 404
-        opts.onUrlAttemptFailed = [](const std::string& url, const std::string& e) {
-            // Demote a host that stalled / served bad bytes / timed out / gave no
-            // response so later fetches this session skip it. Do NOT penalize on
-            // plain 404/401: the asset is just absent on that mirror (e.g. gitcode
-            // 404s .json) — the host is fine for other assets.
-            if (e.find("404") == std::string::npos && e.find("401") == std::string::npos)
-                mirror::adaptive::penalize_host(url);
-        };
-        if (!want.empty()) {
-            opts.onVerify = [destFile, want](const std::string& url) -> std::string {
-                auto digest = sha256::hex_file(destFile);
-                if (digest && *digest == want) return {};
-                return std::format("sha256 mismatch (source {}): got {}, want {}",
-                                   url, digest ? *digest : "<unreadable>", want);
-            };
-        }
-        auto r = tinyhttps::download_file(opts);
-        if (r.success) return {};
-        lastErr = r.error.empty() ? ("failed: " + u) : r.error;
-        log::debug("[index] candidate failed ({}): {}", u, lastErr);
-    }
-    return lastErr.empty() ? "all candidates failed" : lastErr;
-}
-
 // Index source base override (env now; config key folded in by the caller via
 // Config). When set to a local dir / file:// it's copied; a remote base means
 // "<base>/<filename>". Empty => use the passed remoteUrls (xlings-res default).
@@ -261,323 +196,34 @@ struct BaseOverride {
     std::string base;                      // remote base, or empty
     std::optional<std::filesystem::path> local;  // local dir, if base is local
 };
-BaseOverride resolve_base_() {
-    BaseOverride b;
-    std::string v;
-    if (auto* e = std::getenv("XLINGS_INDEX_BASE_URL"); e && *e) v = e;
-    else v = Config::index_base();   // .xlings.json xim.index-base (region-aware), else ""
-    if (v.empty()) return b;
-    while (!v.empty() && v.back() == '/') v.pop_back();
-    b.base = v;
-    if (v.starts_with("file://")) b.local = std::filesystem::path(v.substr(7));
-    else if (v.find("://") == std::string::npos) b.local = std::filesystem::path(v);
-    return b;
-}
-
-// Obtain `filename` into `dest`: local-dir copy, or remote (base override, else
-// the given remoteUrls). Verifies sha256 when wantSha is non-empty.
-// #377: `forced` replaces the global env/config base override entirely — a
-// custom source must never be redirected by XLINGS_INDEX_BASE_URL; a forge
-// custom source passes an EMPTY override ("use the URL list as-is").
-std::string obtain_file(const std::string& filename, std::vector<std::string> remoteUrls,
-                        const std::filesystem::path& dest, std::string_view wantSha,
-                        const BaseOverride* forced = nullptr) {
-    namespace fs = std::filesystem;
-    auto b = forced ? *forced : resolve_base_();
-    if (b.local) {
-        std::error_code ec;
-        auto src = *b.local / filename;
-        if (!fs::exists(src, ec)) return std::format("local file not found: {}", src.string());
-        fs::copy_file(src, dest, fs::copy_options::overwrite_existing, ec);
-        if (ec) return std::format("copy {} failed: {}", src.string(), ec.message());
-        if (!wantSha.empty()) {
-            auto digest = sha256::hex_file(dest);
-            auto want = lower_hex_(std::string(wantSha));
-            if (!digest || *digest != want)
-                return std::format("sha256 mismatch (local {}): got {}, want {}",
-                                   src.string(), digest ? *digest : "<unreadable>", want);
-        }
-        return {};
-    }
-    auto urls = b.base.empty() ? std::move(remoteUrls)
-                               : std::vector<std::string>{ b.base + "/" + filename };
-    return download_candidates_(std::move(urls), dest, wantSha);
-}
-
-// #377: forced base for a custom source: local-dir copy, flat-remote base, or
-// (for forge bases) an EMPTY override meaning "use the passed URL list, but do
-// NOT apply the global index-base override".
-BaseOverride base_override_for_(const ArtifactSource& src) {
-    BaseOverride b;
-    if (src.localDir) { b.local = src.localDir; b.base = src.base; }
-    else if (!src.forge()) b.base = src.base;
-    return b;
-}
 
 } // namespace detail_
 
-std::optional<IndexManifest> parse_index_manifest(std::string_view jsonText) {
-    try {
-        auto j = nlohmann::json::parse(jsonText);
-        if (!j.is_object() || !j.contains("artifact") || !j["artifact"].is_object())
-            return std::nullopt;
-        auto& art = j["artifact"];
-        if (!art.contains("name") || !art.contains("sha256")) return std::nullopt;
-
-        IndexManifest m;
-        m.format_version  = j.value("format_version", 0);
-        m.index_version   = j.value("index_version", std::string{});
-        m.index_name      = j.value("index_name", std::string{"xim"});
-        m.generated_at    = j.value("generated_at", std::string{});
-        m.source_commit   = j.value("source_commit", std::string{});
-        m.artifact_name   = art.value("name", std::string{});
-        m.artifact_sha256 = detail_::lower_hex_(art.value("sha256", std::string{}));
-        m.artifact_size   = art.value("size", std::uint64_t{0});
-        if (m.artifact_name.empty() || m.artifact_sha256.empty()) return std::nullopt;
-
-        // #476, all optional: a pointer without them parses exactly as before.
-        if (j.contains("requires") && j["requires"].is_object()) {
-            m.requirements = j["requires"];
-        }
-        m.history_truncated = j.value("history_truncated", false);
-        if (j.contains("history") && j["history"].is_array()) {
-            for (const auto& e : j["history"]) {
-                if (!e.is_object() || !e.contains("artifact")
-                    || !e["artifact"].is_object()) continue;
-                const auto& ea = e["artifact"];
-                IndexSnapshot s;
-                s.index_version   = e.value("index_version", std::string{});
-                s.generated_at    = e.value("generated_at", std::string{});
-                s.artifact_name   = ea.value("name", std::string{});
-                s.artifact_sha256 = detail_::lower_hex_(ea.value("sha256", std::string{}));
-                s.artifact_size   = ea.value("size", std::uint64_t{0});
-                if (e.contains("requires") && e["requires"].is_object()) {
-                    s.requirements = e["requires"];
-                }
-                // A history entry with no artifact identity is unusable; drop it
-                // rather than carrying a row that cannot be selected.
-                if (s.index_version.empty() || s.artifact_name.empty()
-                    || s.artifact_sha256.empty()) continue;
-                m.history.push_back(std::move(s));
-            }
-        }
-        return m;
-    } catch (...) {
-        return std::nullopt;
-    }
-}
+std::optional<IndexManifest> parse_index_manifest(std::string_view jsonText);
 
 std::optional<IndexRequirement> requirement_for(const nlohmann::json& requirements,
-                                                std::string_view consumer) {
-    if (!requirements.is_object()) return std::nullopt;
-    const auto it = requirements.find(std::string(consumer));
-    if (it == requirements.end() || !it->is_object()) return std::nullopt;
-    IndexRequirement req;
-    req.min = it->value("min", std::string{});
-    req.max = it->value("max", std::string{});
-    if (req.empty()) return std::nullopt;
-    return req;
-}
+                                                std::string_view consumer);
 
-bool satisfies_requirement(std::string_view selfVersion, const IndexRequirement& req) {
-    if (!req.min.empty() && version_order::compare(selfVersion, req.min) < 0) return false;
-    if (!req.max.empty() && version_order::compare(selfVersion, req.max) >= 0) return false;
-    return true;
-}
+bool satisfies_requirement(std::string_view selfVersion, const IndexRequirement& req);
 
-std::vector<IndexSnapshot> snapshots_of(const IndexManifest& manifest) {
-    if (!manifest.history.empty()) return manifest.history;
-    IndexSnapshot only;
-    only.index_version   = manifest.index_version;
-    only.generated_at    = manifest.generated_at;
-    only.artifact_name   = manifest.artifact_name;
-    only.artifact_sha256 = manifest.artifact_sha256;
-    only.artifact_size   = manifest.artifact_size;
-    only.requirements    = manifest.requirements;
-    return {only};
-}
+std::vector<IndexSnapshot> snapshots_of(const IndexManifest& manifest);
 
 namespace detail_ {
 
-std::string describe_requirement_(const IndexSnapshot& s) {
-    const auto req = requirement_for(s.requirements, "xlings");
-    if (!req) return "no requirement";
-    std::string out;
-    if (!req->min.empty()) out += ">= " + req->min;
-    if (!req->max.empty()) out += (out.empty() ? "" : " ") + std::string("< ") + req->max;
-    return out;
-}
-
 }  // namespace detail_
 
 std::expected<SnapshotChoice, std::string> choose_snapshot(
-    const IndexManifest& manifest, std::string_view selfVersion, std::string_view pin) {
-    const auto snapshots = snapshots_of(manifest);
-    if (snapshots.empty()) return std::unexpected("pointer lists no index snapshot");
-
-    const auto available = [&] {
-        std::string list;
-        for (const auto& s : snapshots) {
-            if (!list.empty()) list += ", ";
-            list += s.index_version;
-        }
-        if (manifest.history_truncated) list += ", … (history truncated)";
-        return list;
-    };
-
-    // "newest": take the head of the list whatever it requires. This is the
-    // escape hatch `self update` runs on, and it is what breaks the deadlock a
-    // routed-back client would otherwise sit in forever -- an old snapshot's
-    // own xlings recipe names an old `latest`, so a client routed there could
-    // never see, let alone install, the version that would let it move on.
-    if (pin == "newest") {
-        SnapshotChoice choice{snapshots.front(), true, {}};
-        return choice;
-    }
-
-    // Explicit pin: honour it exactly. It bypasses the contract check -- asking
-    // for a specific snapshot is a deliberate act, often to reproduce a bug --
-    // but never the sha256 check downstream.
-    if (!pin.empty() && pin != "latest") {
-        for (const auto& s : snapshots) {
-            if (s.index_version == pin) {
-                SnapshotChoice choice{s, &s == &snapshots.front(), {}};
-                if (!choice.isNewest) {
-                    choice.reason = std::format("pinned to {}", pin);
-                }
-                return choice;
-            }
-        }
-        return std::unexpected(std::format(
-            "E_INDEX_VERSION_NOT_FOUND: pinned to '{}', which the pointer does "
-            "not offer; available: {}", pin, available()));
-    }
-
-    // Automatic routing: newest snapshot whose contract this client meets.
-    for (std::size_t i = 0; i < snapshots.size(); ++i) {
-        const auto& s = snapshots[i];
-        const auto req = requirement_for(s.requirements, "xlings");
-        if (req && !satisfies_requirement(selfVersion, *req)) continue;
-        SnapshotChoice choice{s, i == 0, {}};
-        if (i != 0) {
-            choice.reason = std::format(
-                "{} requires xlings {}, this is {}",
-                snapshots.front().index_version,
-                detail_::describe_requirement_(snapshots.front()), selfVersion);
-        }
-        return choice;
-    }
-
-    return std::unexpected(std::format(
-        "E_INDEX_NO_COMPATIBLE_SNAPSHOT: this xlings is {} and no published "
-        "snapshot accepts it (newest {} requires xlings {}); available: {}",
-        selfVersion, snapshots.front().index_version,
-        detail_::describe_requirement_(snapshots.front()), available()));
-}
+    const IndexManifest& manifest, std::string_view selfVersion, std::string_view pin);
 
-std::optional<ArtifactSource> artifact_source_for(const IndexRepo& repo) {
-    std::string base = repo.artifactBase;
-    if (base.empty()) return std::nullopt;
-    while (base.size() > 1 && base.ends_with('/')) base.pop_back();
-
-    ArtifactSource src;
-    src.base = base;
-    src.key  = repo.name;
-
-    std::string pathPart = base;
-    if (base.starts_with("file://")) {
-        src.localDir = std::filesystem::path(base.substr(7)).lexically_normal();
-        pathPart = src.localDir->generic_string();
-    } else if (base.find("://") == std::string::npos) {
-        src.localDir = std::filesystem::path(base).lexically_normal();
-        pathPart = src.localDir->generic_string();
-    }
-
-    auto slash = pathPart.find_last_of("/\\");
-    src.repoName = slash == std::string::npos ? pathPart : pathPart.substr(slash + 1);
-    if (src.repoName.empty()) return std::nullopt;
-
-    if (!src.localDir) {
-        auto rest = base.substr(base.find("://") + 3);
-        auto firstSlash = rest.find('/');
-        auto host = firstSlash == std::string::npos ? rest : rest.substr(0, firstSlash);
-        if (host.find("github.com") != std::string::npos ||
-            host.find("gitcode.com") != std::string::npos) {
-            src.server = base.substr(0, base.find_last_of('/'));  // scheme://host/org
-        }
-    }
-    return src;
-}
+std::optional<ArtifactSource> artifact_source_for(const IndexRepo& repo);
 
 const IndexManifest* select_manifest(const std::map<std::string, IndexManifest>& pointers,
-                                     std::string_view key, bool soleEntryFallback) {
-    if (auto it = pointers.find(std::string(key)); it != pointers.end()) return &it->second;
-    if (soleEntryFallback && pointers.size() == 1) return &pointers.begin()->second;
-    return nullptr;
-}
+                                     std::string_view key, bool soleEntryFallback);
 
 std::vector<std::string> index_asset_urls(std::string_view filename,
                                           std::string_view mirror,
                                           std::string_view version,
-                                          const ArtifactSource* custom) {
-    // #377: a per-repo source replaces the official server set entirely.
-    if (custom) {
-        if (custom->forge()) {
-            std::vector<std::string> tags;
-            if (!version.empty()) tags.push_back("v" + std::string(version));
-            tags.push_back("latest");   // GitHub rolling fallback; a 404 falls through
-            std::vector<std::string> urls;
-            for (auto& tag : tags)
-                urls.push_back(std::format("{}/{}/releases/download/{}/{}",
-                                           custom->server, custom->repoName, tag, filename));
-            return urls;
-        }
-        if (!custom->localDir) return { custom->base + "/" + std::string(filename) };
-        return {};  // local dir: obtain_file consumes a forced BaseOverride instead
-    }
-
-    std::vector<std::string> urls;
-    auto add = [&](const std::string& u) {
-        if (!u.empty() && std::ranges::find(urls, u) == urls.end()) urls.push_back(u);
-    };
-
-    auto repo = detail_::index_repo_name_();
-
-    // Release tag(s) to try, in order. GitCode only serves release assets via
-    // the VERSIONED tag (`v<version>`); its rolling `latest` tag 404s on the
-    // `releases/download/latest/<asset>` path (GitHub serves both). So when we
-    // know the version, try `v<version>` first and keep `latest` as a fallback.
-    std::vector<std::string> tags;
-    if (!version.empty()) tags.push_back("v" + std::string(version));
-    if (auto def = detail_::index_tag_(); std::ranges::find(tags, def) == tags.end())
-        tags.push_back(def);
-
-    // Selected (latency-probed) server first, then all other candidates.
-    auto selected = Config::resource_server(mirror);
-    auto buildFor = [&](const std::string& server, const std::string& tag) {
-        return std::format("{}/{}/releases/download/{}/{}", server, repo, tag, filename);
-    };
-    auto addServer = [&](const std::string& server) {
-        if (server.empty()) return;
-        for (auto& tag : tags) add(buildFor(server, tag));
-    };
-    addServer(selected);
-    for (auto& server : Config::resource_servers(mirror)) addServer(server);
-    // Always include GLOBAL (github) servers as fallback for the index — even
-    // under CN. Unlike package binaries (where the regional mirror is
-    // authoritative), the index must stay reachable if the regional mirror
-    // lacks the asset; combined with 404-fallthrough this gives CN: gitcode ->
-    // github -> github proxies.
-    for (auto& server : Config::resource_servers("GLOBAL")) addServer(server);
-
-    // NB: deliberately NO github-proxy expansion (ghfast/ghproxy/kkgithub) for
-    // the index. Those proxies are often TCP-reachable but don't actually serve
-    // the asset, so a fast-latency-but-dead proxy ranked ahead of github causes
-    // a ~30s timeout per dead host (the CN "fetching package index" hang). The
-    // index is small; gitcode + github-direct (region-ordered) is enough, and a
-    // gitcode 404/miss falls through to github fast.
-    return urls;
-}
+                                          const ArtifactSource* custom);
 
 // Raw-file URLs for the rolling pointer (a file committed to the index repo,
 // updated by git push, served raw). github.com/<org> ->
@@ -585,46 +231,7 @@ std::vector<std::string> index_asset_urls(std::string_view filename,
 // raw.gitcode.com/<org>/<repo>/raw/main/<f>. Region-ordered + GLOBAL fallback.
 std::vector<std::string> index_pointer_urls(std::string_view filename,
                                             std::string_view mirror,
-                                            const ArtifactSource* custom) {
-    auto rawFor = [&](const std::string& server, const std::string& repo) -> std::string {
-        auto pos = server.find("://");
-        std::string rest = pos == std::string::npos ? server : server.substr(pos + 3);
-        auto slash = rest.find('/');
-        if (slash == std::string::npos) return {};
-        std::string host = rest.substr(0, slash);
-        std::string org  = rest.substr(slash + 1);
-        while (!org.empty() && org.back() == '/') org.pop_back();
-        if (host.find("github.com") != std::string::npos)
-            return std::format("https://raw.githubusercontent.com/{}/{}/main/{}", org, repo, filename);
-        if (host.find("gitcode.com") != std::string::npos)
-            // Correct raw form is .../<o>/<r>/raw/main/<f> — it serves the RAW
-            // bytes (incl .json). The .../main/<f> form (no /raw/) returns the
-            // HTML web page. (403s seen while probing were request rate-limiting.)
-            return std::format("https://raw.gitcode.com/{}/{}/raw/main/{}", org, repo, filename);
-        return {};
-    };
-
-    // #377: per-repo source — one authoritative location, no official mirrors.
-    if (custom) {
-        if (custom->forge()) {
-            if (auto u = rawFor(custom->server, custom->repoName); !u.empty()) return {u};
-            return {};
-        }
-        if (!custom->localDir) return { custom->base + "/" + std::string(filename) };
-        return {};  // local dir: obtain_file consumes a forced BaseOverride instead
-    }
-
-    auto repo = detail_::index_repo_name_();
-    std::vector<std::string> urls;
-    auto add = [&](const std::string& u){
-        if (!u.empty() && std::ranges::find(urls, u) == urls.end()) urls.push_back(u);
-    };
-    auto selected = Config::resource_server(mirror);
-    if (!selected.empty()) add(rawFor(selected, repo));
-    for (auto& s : Config::resource_servers(mirror))   add(rawFor(s, repo));
-    for (auto& s : Config::resource_servers("GLOBAL")) add(rawFor(s, repo));
-    return urls;
-}
+                                            const ArtifactSource* custom);
 
 namespace detail_ {
 // base -> consumer -> newest version, filled by load_index_pointers().
@@ -632,18 +239,6 @@ inline std::map<std::string, std::map<std::string, std::string>>& client_latest_
     static std::map<std::string, std::map<std::string, std::string>> value;
     return value;
 }
-}  // namespace detail_
-
-// Newest published version of `consumer` as the pointer advertises it, or ""
-// when the pointer does not say. Requires load_index_pointers() to have run
-// for the same source (fetch_index_artifact always does).
-std::string client_latest_for(std::string_view consumer, const ArtifactSource* custom) {
-    const std::string cacheKey = custom ? custom->base : std::string{};
-    const auto& all = detail_::client_latest_cache_();
-    const auto base = all.find(cacheKey);
-    if (base == all.end()) return {};
-    const auto hit = base->second.find(std::string(consumer));
-    return hit == base->second.end() ? std::string{} : hit->second;
 }
 
 // Cached fetch of the COMBINED pointer file (xim-index-pointers.json): ONE raw
@@ -652,194 +247,13 @@ std::string client_latest_for(std::string_view consumer, const ArtifactSource* c
 // index server must serve. Format:
 //   {"format_version":1,"indexes":{"xim":{<manifest>},"awesome":{<manifest>},...}}
 const std::map<std::string, IndexManifest>& load_index_pointers(std::string_view mirror,
-                                                                const ArtifactSource* custom) {
-    // #377: keyed per base (official = ""), same fetch-once-per-process
-    // semantics the old once_flag gave the official pointer.
-    static std::mutex mu;
-    static std::map<std::string, std::map<std::string, IndexManifest>> cacheByBase;
-    static std::set<std::string> fetched;
-    std::string cacheKey = custom ? custom->base : std::string{};
-    std::scoped_lock lk(mu);
-    auto& cache = cacheByBase[cacheKey];
-    if (fetched.contains(cacheKey)) return cache;
-    fetched.insert(cacheKey);
-
-    std::string filename = custom ? custom->repoName + "-pointers.json"
-                                  : std::string("xim-index-pointers.json");
-    namespace fs = std::filesystem;
-    auto tmp = fs::temp_directory_path() /
-               std::format("xim-index-pointers.{}.{}.json", platform::get_pid(), fetched.size());
-    std::error_code ec; fs::remove(tmp, ec);
-    detail_::BaseOverride forcedStorage;
-    const detail_::BaseOverride* forced = nullptr;
-    if (custom) { forcedStorage = detail_::base_override_for_(*custom); forced = &forcedStorage; }
-    auto err = detail_::obtain_file(filename, index_pointer_urls(filename, mirror, custom),
-                                    tmp, {}, forced);
-    if (!err.empty()) { log::warn("[index] pointer fetch failed: {}", err); return cache; }
-    std::string text;
-    { std::ifstream in(tmp, std::ios::binary); std::stringstream ss; ss << in.rdbuf(); text = ss.str(); }
-    fs::remove(tmp, ec);
-    try {
-        auto j = nlohmann::json::parse(text);
-        if (j.contains("indexes") && j["indexes"].is_object())
-            for (auto it = j["indexes"].begin(); it != j["indexes"].end(); ++it)
-                if (auto m = parse_index_manifest(it.value().dump())) cache[it.key()] = *m;
-        // #476: newest CLIENT version, carried at pointer top level so it is
-        // readable no matter which index snapshot this client routes to. That
-        // is the half of the deadlock fix a routed-back client depends on: an
-        // old snapshot's own xlings recipe names an old `latest`, so without
-        // this the client could never learn a newer one exists.
-        if (j.contains("client_latest") && j["client_latest"].is_object()) {
-            auto& slot = detail_::client_latest_cache_()[cacheKey];
-            for (auto it = j["client_latest"].begin(); it != j["client_latest"].end(); ++it)
-                if (it.value().is_string()) slot[it.key()] = it.value().get<std::string>();
-        }
-    } catch (...) { log::warn("[index] pointer parse failed"); }
-    return cache;
-}
+                                                                const ArtifactSource* custom);
 
 bool fetch_index_artifact(const std::filesystem::path& destIndexDir,
                           std::string& err,
                           std::string_view subName,
                           const ArtifactSource* custom,
-                          std::string_view pin) {
-    namespace fs = std::filesystem;
-    auto mirrorKey = Config::mirror();
-    std::string key = custom ? custom->key
-                             : (subName.empty() ? std::string("xim") : std::string(subName));
-
-    std::string label = subName.empty()
-        ? std::string("package index")
-        : std::format("sub-index '{}'", subName);
-    log::info("[index] fetching {} (mirror={})...",
-              label, mirrorKey.empty() ? "GLOBAL" : mirrorKey);
-
-    auto& pointers = load_index_pointers(mirrorKey, custom);
-    const IndexManifest* pm = select_manifest(pointers, key, custom != nullptr);
-    if (!pm) {
-        err = std::format("no pointer entry for '{}' ({} entries)", key, pointers.size());
-        return false;
-    }
-    const IndexManifest& manifest = *pm;
-    if (manifest.format_version != 1) {
-        err = std::format("unsupported index manifest format_version {}", manifest.format_version);
-        return false;
-    }
-
-    // #476: route to the newest snapshot this client's version accepts, or to
-    // an explicit pin. On failure the local index tree is left alone -- keeping
-    // the last snapshot that worked beats replacing it with a wrong one.
-    // XLINGS_INDEX_PIN overrides the per-repo pin: an escape hatch for
-    // debugging, and the mechanism `self update` uses to reach a newer client
-    // through an index this version would not otherwise route to.
-    std::string effectivePin{pin};
-    if (const auto* env = std::getenv("XLINGS_INDEX_PIN"); env && *env) {
-        effectivePin = env;
-    }
-    const auto choice = choose_snapshot(manifest, Info::VERSION, effectivePin);
-    if (!choice) { err = choice.error(); return false; }
-    const IndexSnapshot& snapshot = choice->snapshot;
-
-    // Say it when we step back. A client that silently sits on an older index
-    // looks to its user exactly like one on the newest, right up until a
-    // package it expects is missing.
-    if (!choice->isNewest) {
-        log::warn("[index] {}: using {} instead of {}", key,
-                  snapshot.index_version, manifest.index_version);
-        log::warn("[index]   {}", choice->reason);
-        if (auto newer = client_latest_for("xlings", custom);
-            !newer.empty() && version_order::compare(newer, Info::VERSION) > 0) {
-            log::warn("[index]   upgrade to {}: xlings self update", newer);
-        }
-    }
-
-    std::error_code ec;
-    auto tmpRoot = fs::path(destIndexDir.string() + ".artifact." +
-                            std::to_string(platform::get_pid()));
-    fs::remove_all(tmpRoot, ec);
-    fs::create_directories(tmpRoot, ec);
-    if (ec) { err = std::format("create temp dir failed: {}", ec.message()); return false; }
-    struct Cleanup { fs::path p; ~Cleanup(){ std::error_code e; fs::remove_all(p,e);} } cleanup{tmpRoot};
-
-    // Artifact (sha256-pinned by the manifest); release asset, versioned name.
-    auto artifactFile = tmpRoot / snapshot.artifact_name;
-    detail_::BaseOverride forcedStorage;
-    const detail_::BaseOverride* forced = nullptr;
-    if (custom) { forcedStorage = detail_::base_override_for_(*custom); forced = &forcedStorage; }
-    if (auto e = detail_::obtain_file(snapshot.artifact_name,
-                    index_asset_urls(snapshot.artifact_name, mirrorKey,
-                                     snapshot.index_version, custom),
-                    artifactFile, snapshot.artifact_sha256, forced); !e.empty()) {
-        err = std::format("fetch index artifact failed: {}", e);
-        return false;
-    }
-
-    // 3. Extract to a staging dir, sanity-check, atomically swap into place.
-    auto stage = tmpRoot / "stage";
-    auto extracted = extract_archive(artifactFile, stage);
-    if (!extracted) { err = std::format("extract index artifact failed: {}", extracted.error()); return false; }
-    if (!fs::exists(stage / "pkgs", ec)) {
-        err = "extracted index missing pkgs/";
-        return false;
-    }
-
-    // Record the installed version for diagnostics / future ETag-style checks.
-    // This is the version of the snapshot that actually lands, NOT the head of
-    // the pointer -- routing (#476) makes those differ, and both readers care:
-    // a human debugging "where did my package go" reads this file, and
-    // get_repo_head_hash() keys the parsed-index cache on it. Writing the head
-    // here would name a tree that is not on disk, and would change on every
-    // publish for a client that keeps landing on the same old snapshot --
-    // rebuilding that client's cache forever.
-    {
-        std::ofstream v(stage / ".xlings-index-version", std::ios::binary);
-        v << snapshot.index_version;
-    }
-
-    auto backup = fs::path(destIndexDir.string() + ".old." +
-                           std::to_string(platform::get_pid()));
-    fs::remove_all(backup, ec);
-    if (fs::exists(destIndexDir, ec)) {
-        // Preferred path: a single atomic exchange of the live dir and the staged
-        // dir. There is no instant where destIndexDir is missing, so a crash /
-        // SIGKILL mid-swap cannot strand the index (which previously degraded the
-        // official index to a destructive git clone on the next run — see
-        // .agents/docs/2026-06-30-index-artifact-git-regression-analysis.md).
-        if (platform::atomic_swap_paths(destIndexDir, stage)) {
-            // After the exchange, `stage` now holds the OLD tree — drop it.
-            fs::remove_all(stage, ec);
-            log::info("[index] updated from artifact {} ({})",
-                      snapshot.artifact_name,
-                      snapshot.index_version.empty() ? "?" : snapshot.index_version);
-            return true;
-        }
-        // Fallback (non-Linux / kernel without renameat2): manual move-aside.
-        // Narrow the kill-window by keeping the backup recoverable — a leftover
-        // `.old.<pid>` that still holds pkgs/ is restored on the next run by
-        // reconcile_index_temps() before any git fallback can fire.
-        fs::rename(destIndexDir, backup, ec);
-        if (ec) { err = std::format("swap (move old) failed: {}", ec.message()); return false; }
-    }
-    fs::rename(stage, destIndexDir, ec);
-    if (ec) {
-        // Roll back to the old tree if the swap-in failed.
-        std::error_code e2;
-        if (fs::exists(backup, e2)) fs::rename(backup, destIndexDir, e2);
-        err = std::format("swap (move new) failed: {}", ec.message());
-        return false;
-    }
-    fs::remove_all(backup, ec);
-
-    // The SNAPSHOT that landed, not the manifest's head. Reporting the head
-    // here would print `updated from xim-index-new0003` immediately after
-    // "using old0001 instead of new0003" -- and this line is what the release
-    // verification runbook greps to decide which artifact a run actually used
-    // (reference_index_publish_lag).
-    log::info("[index] updated from artifact {} ({})",
-              snapshot.artifact_name,
-              snapshot.index_version.empty() ? "?" : snapshot.index_version);
-    return true;
-}
+                          std::string_view pin);
 
 // Reconcile leftover index temp dirs from crashed / SIGKILL'd runs. Two jobs:
 //   1) RECOVER: if a live index dir is missing or empty but a sibling
@@ -852,58 +266,6 @@ bool fetch_index_artifact(const std::filesystem::path& destIndexDir,
 //      otherwise accumulate without bound (10+ observed in the wild).
 // Dirs still owned by a live process are left untouched (concurrency-safe).
 // See .agents/docs/2026-06-30-index-artifact-git-regression-analysis.md.
-void reconcile_index_temps(const std::filesystem::path& dataDir) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    if (!fs::is_directory(dataDir, ec)) return;
-
-    struct Temp { fs::path path; fs::path base; std::string kind; int pid; };
-    std::vector<Temp> temps;
-    // Compare against std::default_sentinel (not a second directory_iterator):
-    // clang/libc++ only provides operator==(default_sentinel_t), so a two-iterator
-    // range-for fails to compile there. Increment with the error_code overload so
-    // a bad entry never throws out of this best-effort reconciler.
-    for (auto it = fs::directory_iterator(dataDir, ec);
-         it != std::default_sentinel; it.increment(ec)) {
-        if (ec) break;
-        const auto& entry = *it;
-        std::error_code dec;
-        if (!entry.is_directory(dec)) continue;
-        auto name = entry.path().filename().string();
-        for (std::string_view kind : {".artifact.", ".old.", ".tmp."}) {
-            auto pos = name.rfind(kind);
-            if (pos == std::string::npos) continue;
-            auto pidStr = name.substr(pos + kind.size());
-            int pid = 0;
-            auto* begin = pidStr.data();
-            auto* end = begin + pidStr.size();
-            auto [ptr, errc] = std::from_chars(begin, end, pid);
-            if (errc != std::errc{} || ptr != end) break;  // suffix isn't a bare pid
-            temps.push_back({entry.path(), dataDir / name.substr(0, pos),
-                             std::string(kind), pid});
-            break;
-        }
-    }
-
-    for (auto& t : temps) {
-        // Never touch staging owned by an in-flight xlings process.
-        if (t.pid > 0 && platform::is_process_alive(t.pid)) continue;
-
-        bool baseUsable   = fs::exists(t.base / "pkgs", ec);
-        bool orphanUsable = fs::exists(t.path / "pkgs", ec);
-
-        if (t.kind == ".old." && orphanUsable && !baseUsable) {
-            // Interrupted swap: this orphan is the only surviving index copy.
-            fs::remove_all(t.base, ec);          // clear an empty / partial base
-            fs::rename(t.path, t.base, ec);
-            if (!ec)
-                log::warn("[index] recovered interrupted index swap: restored {} from {}",
-                          t.base.filename().string(), t.path.filename().string());
-            continue;
-        }
-        // Spent staging / leaked temp from a dead process — reclaim the space.
-        fs::remove_all(t.path, ec);
-    }
-}
+void reconcile_index_temps(const std::filesystem::path& dataDir);
 
 } // namespace xlings::xim
diff --git a/src/core/xim/install_state.cpp b/src/core/xim/install_state.cpp
new file mode 100644
index 00000000..443dd78d
--- /dev/null
+++ b/src/core/xim/install_state.cpp
@@ -0,0 +1,137 @@
+module xlings.core.xim.install_state;
+
+import std;
+import xlings.core.xim.payload;
+import xlings.core.xvm.owner;
+import xlings.core.xvm.types;
+import xlings.core.xvm.db;
+
+namespace xlings::xim {
+
+int count_ledger_registrations(const xvm::VersionDB& db,
+                               const std::string& xlingsHome,
+                               std::string_view namespaceName,
+                               std::string_view name,
+                               std::string_view version) {
+    const xvm::InstallCoordinate wanted{
+        .ns = std::string(namespaceName),
+        .package = std::string(name),
+        .version = std::string(version),
+    };
+    int count = 0;
+    for (const auto& [target, info] : db) {
+        for (const auto& [versionKey, data] : info.versions) {
+            if (data.path.empty()) continue;
+            const auto expanded = xvm::expand_path(data.path, xlingsHome);
+            if (auto coord = xvm::coordinate_from_payload_path(expanded);
+                coord && *coord == wanted) {
+                ++count;
+            }
+        }
+    }
+    return count;
+}
+
+InstallStateReport installation_state(
+    const LedgerIndex& ledger,
+    std::string_view namespaceName,
+    std::string_view name,
+    std::string_view version,
+    const std::filesystem::path& payloadDir) {
+
+    InstallStateReport report;
+    report.payloadPresent = payload_has_content(payloadDir);
+    report.ledgerPresent = ledger.references(namespaceName, name, version);
+    report.stampedRegistrations = stamped_registration_count(payloadDir);
+
+    // A failure that recorded itself. Checked first and independently of the
+    // payload, because the two shapes a failed install leaves -- nothing at
+    // all, and a half-unpacked directory -- must reach the same verdict.
+    if (stamped_incomplete(payloadDir)) {
+        report.state = InstallState::Incomplete;
+        report.reason = "the previous install did not finish";
+        return report;
+    }
+
+    if (!report.payloadPresent && !report.ledgerPresent) {
+        report.state = InstallState::Absent;
+        return report;
+    }
+
+    if (report.ledgerPresent && !report.payloadPresent) {
+        report.state = InstallState::Incomplete;
+        report.reason =
+            "the records name a payload that is not on disk";
+        return report;
+    }
+
+    if (report.payloadPresent && !report.ledgerPresent
+        && report.stampedRegistrations > 0) {
+        report.state = InstallState::Incomplete;
+        report.reason = std::format(
+            "the install recorded {} registration(s) and the version database "
+            "has none of them", report.stampedRegistrations);
+        return report;
+    }
+
+    report.state = report.payloadPresent
+        ? InstallState::Installed : InstallState::Absent;
+    return report;
+}
+
+bool unverifiable_stamped_payload(const LedgerIndex& ledger,
+                                  std::string_view namespaceName,
+                                  std::string_view name,
+                                  std::string_view version,
+                                  const std::filesystem::path& payloadDir) {
+    if (ledger.references(namespaceName, name, version)) return false;
+    if (!payload_has_content(payloadDir)) return false;
+    return stamped_registration_count(payloadDir) == kRegisteredUnrecorded
+        && std::filesystem::is_regular_file(
+               payloadDir / std::filesystem::path(kPayloadStampFile));
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::xim {
+
+[[nodiscard]] bool InstallStateReport::is_installed() const {
+    return state == InstallState::Installed;
+}
+
+[[nodiscard]] bool InstallStateReport::is_incomplete() const {
+    return state == InstallState::Incomplete;
+}
+
+[[nodiscard]] bool InstallStateReport::should_run_install_hook() const {
+    return state != InstallState::Installed;
+}
+
+LedgerIndex::LedgerIndex(const xvm::VersionDB& db, const std::string& xlingsHome) {
+    for (const auto& [target, info] : db) {
+        for (const auto& [versionKey, data] : info.versions) {
+            if (data.path.empty()) continue;
+            const auto expanded = xvm::expand_path(data.path, xlingsHome);
+            if (auto coord = xvm::coordinate_from_payload_path(expanded)) {
+                coords_.insert(std::move(*coord));
+            }
+        }
+    }
+}
+
+[[nodiscard]] bool LedgerIndex::references(std::string_view namespaceName,
+                                  std::string_view name,
+                                  std::string_view version) const {
+    return coords_.contains(xvm::InstallCoordinate{
+        .ns = std::string(namespaceName),
+        .package = std::string(name),
+        .version = std::string(version),
+    });
+}
+
+[[nodiscard]] std::size_t LedgerIndex::size() const { return coords_.size(); }
+
+} // namespace xlings::xim
diff --git a/src/core/xim/install_state.cppm b/src/core/xim/install_state.cppm
index 74cd0fd7..169946a0 100644
--- a/src/core/xim/install_state.cppm
+++ b/src/core/xim/install_state.cppm
@@ -51,17 +51,11 @@ struct InstallStateReport {
     // Filled for Incomplete only, and phrased for a user rather than a log.
     std::string reason;
 
-    [[nodiscard]] bool is_installed() const {
-        return state == InstallState::Installed;
-    }
-    [[nodiscard]] bool is_incomplete() const {
-        return state == InstallState::Incomplete;
-    }
+    [[nodiscard]] bool is_installed() const;
+    [[nodiscard]] bool is_incomplete() const;
     // What `install` must decide. An incomplete payload is the case the old
     // predicate got wrong: it is exactly when the hook MUST run again.
-    [[nodiscard]] bool should_run_install_hook() const {
-        return state != InstallState::Installed;
-    }
+    [[nodiscard]] bool should_run_install_hook() const;
 };
 
 // Every payload coordinate the version DB references.
@@ -76,29 +70,13 @@ class LedgerIndex {
 public:
     LedgerIndex() = default;
 
-    LedgerIndex(const xvm::VersionDB& db, const std::string& xlingsHome) {
-        for (const auto& [target, info] : db) {
-            for (const auto& [versionKey, data] : info.versions) {
-                if (data.path.empty()) continue;
-                const auto expanded = xvm::expand_path(data.path, xlingsHome);
-                if (auto coord = xvm::coordinate_from_payload_path(expanded)) {
-                    coords_.insert(std::move(*coord));
-                }
-            }
-        }
-    }
+    LedgerIndex(const xvm::VersionDB& db, const std::string& xlingsHome);
 
     [[nodiscard]] bool references(std::string_view namespaceName,
                                   std::string_view name,
-                                  std::string_view version) const {
-        return coords_.contains(xvm::InstallCoordinate{
-            .ns = std::string(namespaceName),
-            .package = std::string(name),
-            .version = std::string(version),
-        });
-    }
+                                  std::string_view version) const;
 
-    [[nodiscard]] std::size_t size() const { return coords_.size(); }
+    [[nodiscard]] std::size_t size() const;
 
 private:
     std::set<xvm::InstallCoordinate> coords_;
@@ -115,25 +93,7 @@ int count_ledger_registrations(const xvm::VersionDB& db,
                                const std::string& xlingsHome,
                                std::string_view namespaceName,
                                std::string_view name,
-                               std::string_view version) {
-    const xvm::InstallCoordinate wanted{
-        .ns = std::string(namespaceName),
-        .package = std::string(name),
-        .version = std::string(version),
-    };
-    int count = 0;
-    for (const auto& [target, info] : db) {
-        for (const auto& [versionKey, data] : info.versions) {
-            if (data.path.empty()) continue;
-            const auto expanded = xvm::expand_path(data.path, xlingsHome);
-            if (auto coord = xvm::coordinate_from_payload_path(expanded);
-                coord && *coord == wanted) {
-                ++count;
-            }
-        }
-    }
-    return count;
-}
+                               std::string_view version);
 
 // The predicate.
 //
@@ -159,47 +119,7 @@ InstallStateReport installation_state(
     std::string_view namespaceName,
     std::string_view name,
     std::string_view version,
-    const std::filesystem::path& payloadDir) {
-
-    InstallStateReport report;
-    report.payloadPresent = payload_has_content(payloadDir);
-    report.ledgerPresent = ledger.references(namespaceName, name, version);
-    report.stampedRegistrations = stamped_registration_count(payloadDir);
-
-    // A failure that recorded itself. Checked first and independently of the
-    // payload, because the two shapes a failed install leaves -- nothing at
-    // all, and a half-unpacked directory -- must reach the same verdict.
-    if (stamped_incomplete(payloadDir)) {
-        report.state = InstallState::Incomplete;
-        report.reason = "the previous install did not finish";
-        return report;
-    }
-
-    if (!report.payloadPresent && !report.ledgerPresent) {
-        report.state = InstallState::Absent;
-        return report;
-    }
-
-    if (report.ledgerPresent && !report.payloadPresent) {
-        report.state = InstallState::Incomplete;
-        report.reason =
-            "the records name a payload that is not on disk";
-        return report;
-    }
-
-    if (report.payloadPresent && !report.ledgerPresent
-        && report.stampedRegistrations > 0) {
-        report.state = InstallState::Incomplete;
-        report.reason = std::format(
-            "the install recorded {} registration(s) and the version database "
-            "has none of them", report.stampedRegistrations);
-        return report;
-    }
-
-    report.state = report.payloadPresent
-        ? InstallState::Installed : InstallState::Absent;
-    return report;
-}
+    const std::filesystem::path& payloadDir);
 
 // The recovery check for payloads installed BEFORE the stamp recorded what it
 // registered. Deliberately separate from `installation_state`: it cannot
@@ -213,12 +133,6 @@ bool unverifiable_stamped_payload(const LedgerIndex& ledger,
                                   std::string_view namespaceName,
                                   std::string_view name,
                                   std::string_view version,
-                                  const std::filesystem::path& payloadDir) {
-    if (ledger.references(namespaceName, name, version)) return false;
-    if (!payload_has_content(payloadDir)) return false;
-    return stamped_registration_count(payloadDir) == kRegisteredUnrecorded
-        && std::filesystem::is_regular_file(
-               payloadDir / std::filesystem::path(kPayloadStampFile));
-}
+                                  const std::filesystem::path& payloadDir);
 
 }  // namespace xlings::xim
diff --git a/src/core/xim/installer.cpp b/src/core/xim/installer.cpp
new file mode 100644
index 00000000..bfd014d1
--- /dev/null
+++ b/src/core/xim/installer.cpp
@@ -0,0 +1,3286 @@
+module xlings.core.xim.installer;
+
+import std;
+import mcpplibs.xpkg;
+import mcpplibs.xpkg.loader;
+import mcpplibs.xpkg.compat;
+import mcpplibs.xpkg.executor;
+import xlings.core.xim.libxpkg.types.type;
+import xlings.core.xim.compatibility;
+import xlings.core.xim.payload;
+import xlings.core.xim.install_state;
+import xlings.core.xim.index;
+import xlings.core.xim.catalog;
+import xlings.core.xim.resolver;
+import xlings.core.xim.downloader;
+import xlings.core.log;
+import xlings.platform;
+import xlings.platform.target;
+import xlings.core.config;
+import xlings.core.semver;
+import xlings.core.entry_binary;
+import xlings.core.elf_same_source;
+import xlings.core.closure_check;
+import xlings.libs.json;
+import xlings.core.common;
+import xlings.core.xself;
+import xlings.core.xvm.types;
+import xlings.core.xvm.db;
+import xlings.core.xvm.bindings;
+import xlings.core.xvm.removal;
+import xlings.core.xvm.registration;
+import xlings.core.xvm.errors;
+import xlings.core.subos.manifest;
+import xlings.core.xvm.commands;
+import xlings.core.xvm.shim;
+import xlings.core.xim.libxpkg.types.script;
+import xlings.core.xim.libxpkg.types.subos;
+import xlings.runtime.cancellation;
+
+namespace xlings::xim {
+
+XpkgSpecSupport xpkg_spec_support(std::string_view spec) {
+    if (spec.empty()) return {.supported = true, .declared = 1};
+    int value = 0;
+    const auto* first = spec.data();
+    const auto* last  = spec.data() + spec.size();
+    auto [ptr, ec] = std::from_chars(first, last, value);
+    if (ec != std::errc{} || ptr != last || value < 1) {
+        return {.supported = false, .declared = 0};
+    }
+    return {.supported = value <= max_supported_xpkg_spec, .declared = value};
+}
+
+std::optional<XpkgResolvedFilesystemEffect>
+resolve_xpkg_filesystem_effect(
+        const xvm::VersionDB& db,
+        const xvm::Workspace& workspace,
+        const XpkgFilesystemEffect& effect) {
+    XpkgResolvedFilesystemEffect resolved{
+        .kind = effect.kind,
+        .target = effect.target,
+        .version = effect.version,
+        .sourceDir = effect.sourceDir,
+    };
+    if (effect.kind == XpkgFilesystemEffectKind::InstallHeaders
+        || effect.kind == XpkgFilesystemEffectKind::RemoveHeaders) {
+        // Headers have no program payload to resolve, but they do have an
+        // owner, and whether that owner is the active version decides
+        // whether these headers belong in the sysroot right now.
+        if (!effect.target.empty()) {
+            auto headerActiveIt = workspace.find(effect.target);
+            resolved.active = headerActiveIt != workspace.end()
+                && headerActiveIt->second == effect.version;
+        } else {
+            // No owner recorded (older plan shape): keep the previous
+            // unconditional behavior rather than silently skipping.
+            resolved.active = true;
+        }
+        return resolved;
+    }
+
+    auto targetIt = db.find(effect.target);
+    if (targetIt == db.end()) return std::nullopt;
+    auto versionIt =
+        targetIt->second.versions.find(effect.version);
+    if (versionIt == targetIt->second.versions.end()) {
+        return std::nullopt;
+    }
+    const auto& data = versionIt->second;
+    const auto kind =
+        data.kind.empty() ? targetIt->second.type : data.kind;
+    // Three kinds, not two. This read `program` or else `lib`, which meant a
+    // FileAsset effect was compared against "lib" and could never match an
+    // entry registered as "files" -- so every declared file asset resolved to
+    // nullopt, the caller logged "validated xvm effect target disappeared or
+    // changed kind", and the FileAsset branch below was dead code. The assets
+    // still landed, because the activation pass places them separately, so
+    // the only visible symptom was a warning on a correct install. It stayed
+    // hidden until a real recipe declared one.
+    const auto expectedKind =
+        effect.kind == XpkgFilesystemEffectKind::ProgramShim
+            ? std::string_view{"program"}
+        : effect.kind == XpkgFilesystemEffectKind::FileAsset
+            ? std::string_view{"files"}
+            : std::string_view{"lib"};
+    if (kind != expectedKind) return std::nullopt;
+
+    resolved.path = data.path;
+    resolved.sourceName = !data.sourceName.empty()
+        ? data.sourceName
+        : (!targetIt->second.filename.empty()
+            ? targetIt->second.filename
+            : effect.target);
+    resolved.destinationName = !data.destinationName.empty()
+        ? data.destinationName
+        : (effect.kind == XpkgFilesystemEffectKind::ProgramShim
+            ? effect.target
+            : resolved.sourceName);
+    auto activeIt = workspace.find(effect.target);
+    resolved.active =
+        activeIt != workspace.end()
+        && activeIt->second == effect.version;
+    return resolved;
+}
+
+std::size_t attach_legacy_header_dir(
+        xvm::VersionDB& db,
+        const std::string& target,
+        const std::string& version,
+        const std::vector<XpkgFilesystemEffect>& effects) {
+    const std::string* sourceDir = nullptr;
+    for (const auto& effect : effects) {
+        // Last one wins, matching how the installer used to assign per op.
+        if (effect.kind == XpkgFilesystemEffectKind::InstallHeaders
+            && !effect.sourceDir.empty()) {
+            sourceDir = &effect.sourceDir;
+        }
+    }
+    if (!sourceDir) return 0;
+
+    auto targetIt = db.find(target);
+    if (targetIt == db.end()) return 0;
+    auto versionIt = targetIt->second.versions.find(version);
+    if (versionIt == targetIt->second.versions.end()) return 0;
+
+    versionIt->second.includedir = *sourceDir;
+    return 1;
+}
+
+std::expected<XpkgRegistrationPlan, XpkgRegistrationError>
+normalize_xpkg_registration_plan(
+        const PlanNode& node,
+        const std::vector<mcpplibs::xpkg::XvmOp>& operations,
+        const std::string& versionNamespace,
+        const std::filesystem::path& dataDir,
+        bool useAfterInstall) {
+    auto normalizeVersion = [&](
+            const std::string& version,
+            std::size_t operationIndex,
+            const std::string& target)
+        -> std::expected<std::string, XpkgRegistrationError> {
+        if (version.empty()) {
+            return std::unexpected(XpkgRegistrationError{
+                .kind = XpkgRegistrationErrorKind::InvalidVersion,
+                .operationIndex = operationIndex,
+                .target = target,
+                .version = version,
+                .message = "xvm registration version is empty",
+            });
+        }
+        const auto separator = version.find(':');
+        if (separator == std::string::npos) {
+            return xvm::make_ns_version(versionNamespace, version);
+        }
+        const auto actualNamespace = version.substr(0, separator);
+        const auto bareVersion = version.substr(separator + 1);
+        if (actualNamespace.empty()
+            || bareVersion.empty()
+            || bareVersion.contains(':')
+            || actualNamespace != versionNamespace) {
+            return std::unexpected(XpkgRegistrationError{
+                .kind = XpkgRegistrationErrorKind::InvalidVersion,
+                .operationIndex = operationIndex,
+                .target = target,
+                .version = version,
+                .message = std::format(
+                    "xvm registration version namespace '{}' "
+                    "does not match expected namespace '{}'",
+                    actualNamespace, versionNamespace),
+            });
+        }
+        return version;
+    };
+    const auto fallbackPath =
+        (node.storeRoot.empty() ? dataDir / "xpkgs" : node.storeRoot)
+        / package_store_name(node.namespaceName, node.name)
+        / node.version;
+    XpkgRegistrationPlan plan{
+        .batch = {
+            .provider = node.canonicalName.empty()
+                ? canonical_package_name(node.namespaceName, node.name)
+                : node.canonicalName,
+            .providerVersion = node.version,
+            // Owner hint for headers that do not name a group. Recipes
+            // conventionally register a target under the package's own name,
+            // so that target identifies which group the package's headers
+            // belong to when several groups exist.
+            .primaryTarget = node.name,
+            .useAfterInstall = useAfterInstall,
+        },
+    };
+
+    for (std::size_t index = 0; index < operations.size(); ++index) {
+        const auto& operation = operations[index];
+        if (operation.op == "headers") {
+            plan.batch.headers.push_back({
+                .sourceDir = operation.includedir,
+            });
+            // Carry the owning target and version so materialization can be
+            // gated on the version actually becoming active. Installing a
+            // version that does not become active used to copy its headers
+            // into the sysroot anyway, leaving the active release's headers
+            // overwritten by an inactive one.
+            plan.effects.push_back({
+                .kind = XpkgFilesystemEffectKind::InstallHeaders,
+                .target = node.name,
+                .version = xvm::make_ns_version(versionNamespace, node.version),
+                .sourceDir = operation.includedir,
+            });
+            continue;
+        }
+        if (operation.op == "remove_headers") {
+            plan.effects.push_back({
+                .kind = XpkgFilesystemEffectKind::RemoveHeaders,
+                .sourceDir = operation.includedir,
+            });
+            continue;
+        }
+        if (operation.op != "add") continue;
+        const auto rawVersion = operation.version.empty()
+            ? node.version
+            : operation.version;
+        const auto kind =
+            operation.type.empty() ? std::string{"program"} : operation.type;
+        // A `files` asset names no artifact to dispatch, so it carries no
+        // source or destination *name* -- what it carries is a src/dst pair,
+        // below. Treating it like a program would invent a sourceName from
+        // the target and then look for an executable that does not exist.
+        const auto namesAnArtifact = kind != "group" && kind != "files";
+        const auto sourceName = namesAnArtifact
+            ? (operation.filename.empty()
+                ? operation.name
+                : operation.filename)
+            : std::string{};
+        xvm::RegistrationNode registrationNode{
+            .target = operation.name,
+            .version = {},
+            .path = operation.bindir.empty()
+                ? fallbackPath.string()
+                : operation.bindir,
+            .kind = kind,
+            .sourceName = sourceName,
+            .destinationName = namesAnArtifact
+                ? (kind == "program" ? operation.name : sourceName)
+                : std::string{},
+            .fileSrc = kind == "files" ? operation.src : std::string{},
+            .fileDst = kind == "files" ? operation.dst : std::string{},
+        };
+        auto exactVersion =
+            normalizeVersion(rawVersion, index, operation.name);
+        if (!exactVersion) {
+            return std::unexpected(std::move(exactVersion.error()));
+        }
+        registrationNode.version = std::move(*exactVersion);
+        // Is there a command behind this name, or is it a pure anchor?
+        //
+        // The registration layer cannot ask -- it never touches the
+        // filesystem -- and nothing else in the record distinguishes the two:
+        // an anchor registered with no bindir still gets the package install
+        // dir as its `path`, still defaults to kind "program", and still has a
+        // sourceName derived from its own target. The payload has run by the
+        // time config() does, so the file either is there or it is not, and
+        // this is the layer that can look.
+        //
+        // Same helper the shim dispatches through, so "registration thinks
+        // there is a program here" and "the shim finds one" cannot disagree.
+        // An alias-mode entry runs something else by definition and is
+        // runnable regardless.
+        // `operation.alias`, not `registrationNode.alias`: the latter is
+        // filled in further down and is still empty here.
+        if (kind == "program" && operation.alias.empty()) {
+            registrationNode.runnable = !xvm::resolve_executable(
+                sourceName.empty() ? operation.name : sourceName,
+                registrationNode.path,
+                Config::paths().homeDir.string()).empty();
+        }
+        // Stored verbatim. The core does not rewrite what a recipe wrote --
+        // it only expands its OWN marker at execution time
+        // (kSubosPlaceholder). A recipe that needs the active subos writes
+        // the marker; one that writes a concrete subos path gets the legacy
+        // treatment (normalize_subos_paths at dispatch) and a doctor finding
+        // telling it so.
+        if (!operation.alias.empty()) {
+            registrationNode.alias.push_back(operation.alias);
+        }
+        for (const auto& [key, value] : operation.envs) {
+            auto [environmentIt, inserted] =
+                registrationNode.envs.emplace(key, value);
+            if (!inserted && environmentIt->second != value) {
+                return std::unexpected(XpkgRegistrationError{
+                    .kind = XpkgRegistrationErrorKind::ConflictingEnvironment,
+                    .operationIndex = index,
+                    .target = operation.name,
+                    .version = key,
+                    .message = std::format(
+                        "xvm registration environment '{}' has "
+                        "conflicting values",
+                        key),
+                });
+            }
+        }
+        if (!operation.binding.empty()) {
+            const auto separator = operation.binding.find('@');
+            if (separator == std::string::npos
+                || separator == 0
+                || separator + 1 == operation.binding.size()
+                || operation.binding.find('@', separator + 1)
+                    != std::string::npos) {
+                return std::unexpected(XpkgRegistrationError{
+                    .kind = XpkgRegistrationErrorKind::InvalidBinding,
+                    .operationIndex = index,
+                    .target = operation.name,
+                    .version = operation.binding,
+                    .message =
+                        "xvm registration binding must be '<root>@<version>'",
+                });
+            }
+            const auto rootTarget =
+                operation.binding.substr(0, separator);
+            auto rootVersion = normalizeVersion(
+                operation.binding.substr(separator + 1),
+                index, rootTarget);
+            if (!rootVersion) {
+                return std::unexpected(std::move(rootVersion.error()));
+            }
+            registrationNode.binding = xvm::RegistrationBinding{
+                .rootTarget = rootTarget,
+                .rootVersion = std::move(*rootVersion),
+            };
+        }
+        if (kind == "program" || kind == "lib" || kind == "files") {
+            plan.effects.push_back({
+                .kind = kind == "program"
+                    ? XpkgFilesystemEffectKind::ProgramShim
+                    : (kind == "lib"
+                        ? XpkgFilesystemEffectKind::Library
+                        : XpkgFilesystemEffectKind::FileAsset),
+                .target = operation.name,
+                .version = registrationNode.version,
+            });
+        }
+        plan.batch.nodes.push_back(std::move(registrationNode));
+    }
+    return plan;
+}
+
+std::expected<xvm::RemovalContext, xvm::RemovalError>
+snapshot_xpkg_removal_context(const xvm::VersionDB& db, const xvm::Workspace& workspace, const std::vector<mcpplibs::xpkg::XvmOp>& operations, const std::string& executingProvider, const std::string& executingProviderVersion, const std::string& preferredTarget, const std::string& preferredVersion) {
+    xvm::RemovalContext legacyContext;
+    std::optional<xvm::RemovalContext> providerContext;
+    std::set<std::pair<std::string, std::string>> seeds;
+
+    auto mergeSeed = [&](const std::string& target,
+                         const std::string& version)
+        -> std::expected<void, xvm::RemovalError> {
+        if (target.empty() || version.empty()
+            || !seeds.emplace(target, version).second) {
+            return {};
+        }
+        auto exactVersion =
+            xvm::resolve_exact_version_key(db, target, version);
+        if (!exactVersion) {
+            return std::unexpected(std::move(exactVersion.error()));
+        }
+        const auto& info = db.at(target);
+        const auto& data = info.versions.at(*exactVersion);
+        const auto hasOutgoingEdge = std::ranges::any_of(
+            info.bindings,
+            [&](const auto& peer) {
+                return peer.second.contains(*exactVersion);
+            });
+        const auto hasIncomingEdge = std::ranges::any_of(
+            db,
+            [&](const auto& peer) {
+                auto edgeIt = peer.second.bindings.find(target);
+                if (edgeIt == peer.second.bindings.end()) return false;
+                return std::ranges::any_of(
+                    edgeIt->second,
+                    [&](const auto& edge) {
+                        return edge.second == *exactVersion;
+                    });
+            });
+        const auto isUnboundLegacySingleton =
+            !data.bindingGroup
+            && !data.bindingMembersDeclared
+            && data.bindingMembers.empty()
+            && !data.bindingHeadersDeclared
+            && data.bindingHeaders.empty()
+            && data.bindingIntegrityIssues.empty()
+            && !hasOutgoingEdge
+            && !hasIncomingEdge;
+        if (isUnboundLegacySingleton) {
+            auto [it, inserted] =
+                legacyContext.members.emplace(target, *exactVersion);
+            if (!inserted && it->second != *exactVersion) {
+                return std::unexpected(xvm::RemovalError{
+                    .kind = xvm::RemovalErrorKind::SelectionInvalid,
+                    .target = target,
+                    .version = *exactVersion,
+                    .message =
+                        "legacy removal selections conflict on target version",
+                });
+            }
+            legacyContext.hasSelection = true;
+            return {};
+        }
+        auto selection =
+            xvm::snapshot_removal_context(db, target, *exactVersion);
+        if (!selection) {
+            return std::unexpected(std::move(selection.error()));
+        }
+        if (!selection->provider.empty()) {
+            if (!executingProvider.empty()
+                && selection->provider != executingProvider) {
+                return std::unexpected(xvm::RemovalError{
+                    .kind = xvm::RemovalErrorKind::ProviderMismatch,
+                    .target = target,
+                    .version = version,
+                    .message = std::format(
+                        "selected version is owned by provider '{}', not '{}'",
+                        selection->provider, executingProvider),
+                });
+            }
+            if (!providerContext) {
+                providerContext = std::move(*selection);
+            }
+            return {};
+        }
+        if (providerContext) return {};
+
+        for (const auto& [memberTarget, memberVersion] :
+             selection->members) {
+            auto [it, inserted] =
+                legacyContext.members.emplace(memberTarget, memberVersion);
+            if (!inserted && it->second != memberVersion) {
+                return std::unexpected(xvm::RemovalError{
+                    .kind = xvm::RemovalErrorKind::SelectionInvalid,
+                    .target = memberTarget,
+                    .version = memberVersion,
+                    .message =
+                        "legacy removal selections conflict on target version",
+                });
+            }
+        }
+        legacyContext.hasSelection = true;
+        return {};
+    };
+
+    if (!preferredTarget.empty() && db.contains(preferredTarget)) {
+        auto merged = mergeSeed(preferredTarget, preferredVersion);
+        if (!merged) return std::unexpected(std::move(merged.error()));
+    }
+
+    for (const auto& operation : operations) {
+        if (operation.op != "remove") continue;
+        std::string version = operation.version;
+        if (version.empty()) {
+            auto activeIt = workspace.find(operation.name);
+            if (activeIt != workspace.end()) {
+                version = activeIt->second;
+            }
+        }
+        if (version.empty() || !db.contains(operation.name)) continue;
+        auto merged = mergeSeed(operation.name, version);
+        if (!merged) return std::unexpected(std::move(merged.error()));
+    }
+
+    if (!providerContext
+        && !legacyContext.hasSelection
+        && !executingProvider.empty()
+        && !executingProviderVersion.empty()) {
+        bool foundProviderRelease = false;
+        for (const auto& [target, info] : db) {
+            for (const auto& [version, data] : info.versions) {
+                if (!data.bindingGroup
+                    || data.bindingGroup->provider != executingProvider
+                    || data.bindingGroup->providerVersion
+                        != executingProviderVersion) {
+                    continue;
+                }
+                foundProviderRelease = true;
+                auto merged = mergeSeed(target, version);
+                if (!merged) {
+                    return std::unexpected(std::move(merged.error()));
+                }
+                break;
+            }
+            if (foundProviderRelease) break;
+        }
+    }
+
+    if (providerContext) return std::move(*providerContext);
+    return legacyContext;
+}
+
+std::expected<xvm::RemovalBatchResult, xvm::RemovalError>
+apply_xpkg_removal_operations(xvm::VersionDB& db, xvm::Workspace& workspace, xvm::WorkspaceInstalled& installed, const std::vector<mcpplibs::xpkg::XvmOp>& operations, const xvm::RemovalContext& context, const xvm::RemovalBatchOptions& options) {
+    std::vector<xvm::RemovalOperation> removals;
+    for (const auto& operation : operations) {
+        if (operation.op != "remove" && operation.op != "remove_all") {
+            continue;
+        }
+        removals.push_back({
+            .op = operation.op,
+            .name = operation.name,
+            .version = operation.version,
+        });
+    }
+    return xvm::apply_removal_batch(
+        db, workspace, installed, removals, context, options);
+}
+
+std::expected<XpkgXvmMetadataResult, XpkgXvmMetadataError>
+apply_xpkg_xvm_metadata_batch(xvm::VersionDB& db, xvm::Workspace& workspace, xvm::WorkspaceInstalled& installed, const std::vector<mcpplibs::xpkg::XvmOp>& operations, const xvm::RemovalContext& removalContext, const XpkgRegistrationPlan& registration, const xvm::RemovalBatchOptions& removalOptions) {
+    auto candidateDb = db;
+    auto candidateWorkspace = workspace;
+    auto candidateInstalled = installed;
+
+    auto removal = apply_xpkg_removal_operations(
+        candidateDb,
+        candidateWorkspace,
+        candidateInstalled,
+        operations,
+        removalContext,
+        removalOptions);
+    if (!removal) {
+        return std::unexpected(XpkgXvmMetadataError{
+            std::in_place_type<xvm::RemovalError>,
+            std::move(removal.error()),
+        });
+    }
+
+    std::vector<xvm::RegisteredMember> registered;
+    std::vector<xvm::DetachedLegacyMember> detachedLegacy;
+    if (!registration.batch.nodes.empty()
+        || !registration.batch.headers.empty()) {
+        auto registrationResult = xvm::apply_registration_batch(
+            candidateDb,
+            candidateWorkspace,
+            candidateInstalled,
+            registration.batch,
+            &detachedLegacy);
+        if (!registrationResult) {
+            return std::unexpected(XpkgXvmMetadataError{
+                std::in_place_type<xvm::RegistrationError>,
+                std::move(registrationResult.error()),
+            });
+        }
+        registered = std::move(*registrationResult);
+    }
+
+    db.swap(candidateDb);
+    workspace.swap(candidateWorkspace);
+    installed.swap(candidateInstalled);
+    return XpkgXvmMetadataResult{
+        .removal = std::move(*removal),
+        .registered = std::move(registered),
+        .detachedLegacy = std::move(detachedLegacy),
+        .effects = registration.effects,
+    };
+}
+
+void cleanup_removed_xvm_library_artifacts(
+        const std::filesystem::path& libDir,
+        const xvm::VersionDB& dbBeforeRemoval,
+        const xvm::VersionDB& currentDb,
+        const xvm::RemovalBatchResult& removalResult) {
+    auto destinationName = [](
+            const std::string& target,
+            const xvm::VInfo& info,
+            const xvm::VData& data) {
+        if (!data.destinationName.empty()) {
+            return data.destinationName;
+        }
+        if (!info.filename.empty()) return info.filename;
+        return target;
+    };
+
+    std::set<std::string> destinations;
+    for (const auto& removed : removalResult.removed) {
+        auto targetIt = dbBeforeRemoval.find(removed.target);
+        if (targetIt == dbBeforeRemoval.end()) continue;
+        auto versionIt =
+            targetIt->second.versions.find(removed.version);
+        if (versionIt == targetIt->second.versions.end()) continue;
+        const auto& data = versionIt->second;
+        const auto kind = data.kind.empty()
+            ? targetIt->second.type
+            : data.kind;
+        if (kind != "lib") continue;
+        destinations.insert(destinationName(
+            removed.target, targetIt->second, data));
+    }
+
+    for (const auto& name : destinations) {
+        const auto hasSurvivingOwner = std::ranges::any_of(
+            currentDb,
+            [&](const auto& targetEntry) {
+                return std::ranges::any_of(
+                    targetEntry.second.versions,
+                    [&](const auto& versionEntry) {
+                        const auto& data = versionEntry.second;
+                        const auto kind = data.kind.empty()
+                            ? targetEntry.second.type
+                            : data.kind;
+                        return kind == "lib"
+                            && destinationName(
+                                targetEntry.first,
+                                targetEntry.second,
+                                data) == name;
+                    });
+            });
+        if (hasSurvivingOwner) continue;
+
+        const auto destination = libDir / name;
+        std::error_code ec;
+        if (std::filesystem::exists(destination, ec)
+            || std::filesystem::is_symlink(destination, ec)) {
+            ec.clear();
+            std::filesystem::remove(destination, ec);
+        }
+    }
+}
+
+void cleanup_removed_xvm_program_artifacts(
+        const std::filesystem::path& binDir,
+        const xvm::VersionDB& dbBeforeRemoval,
+        const xvm::VersionDB& currentDb,
+        const xvm::WorkspaceInstalled& installed,
+        const xvm::RemovalBatchResult& removalResult) {
+    std::set<std::string> removedPrograms;
+    for (const auto& removed : removalResult.removed) {
+        auto targetIt = dbBeforeRemoval.find(removed.target);
+        if (targetIt == dbBeforeRemoval.end()) continue;
+        auto versionIt =
+            targetIt->second.versions.find(removed.version);
+        if (versionIt == targetIt->second.versions.end()) continue;
+        const auto kind = versionIt->second.kind.empty()
+            ? targetIt->second.type
+            : versionIt->second.kind;
+        if (kind == "program") {
+            removedPrograms.insert(removed.target);
+        }
+    }
+
+    for (const auto& target : removedPrograms) {
+        if (xvm::has_usable_workspace_version(
+                currentDb, installed, target)) {
+            continue;
+        }
+#ifdef _WIN32
+        constexpr std::string_view shimExtension = ".exe";
+#else
+        constexpr std::string_view shimExtension = "";
+#endif
+        std::string shimName = target;
+        if (!shimExtension.empty()
+            && !shimName.ends_with(shimExtension)) {
+            shimName += shimExtension;
+        }
+        const auto shimPath = binDir / shimName;
+        std::error_code ec;
+        if (!std::filesystem::exists(shimPath, ec)
+            && !std::filesystem::is_symlink(shimPath, ec)) {
+            continue;
+        }
+        ec.clear();
+        std::filesystem::remove(shimPath, ec);
+        if (ec) {
+            log::warn("could not remove shim {}: {}; will be replaced "
+                      "on next install/use",
+                      shimPath.string(), ec.message());
+        }
+    }
+}
+
+bool evict_invalid_archive_cache_(
+        const std::filesystem::path& archive,
+        const ExtractError& error) {
+    if (error.kind != ExtractErrorKind::InvalidInputArchive) return false;
+    std::error_code ec;
+    bool removed = std::filesystem::remove(archive, ec);
+    auto sidecar = archive;
+    sidecar += ".meta";
+    ec.clear();
+    std::filesystem::remove(sidecar, ec);
+    return removed;
+}
+
+namespace detail_ {
+
+std::string format_hook_failure(
+        std::string_view hookName,
+        const mcpplibs::xpkg::HookResult& result) {
+    auto trim = [](std::string_view text) {
+        while (!text.empty()
+               && std::isspace(static_cast<unsigned char>(text.front()))) {
+            text.remove_prefix(1);
+        }
+        while (!text.empty()
+               && std::isspace(static_cast<unsigned char>(text.back()))) {
+            text.remove_suffix(1);
+        }
+        return text;
+    };
+
+    auto error = trim(result.error);
+    auto output = trim(result.output);
+    std::string message = std::format("{} hook failed", hookName);
+    if (!error.empty()) {
+        message += ": ";
+        message.append(error);
+    }
+    if (!output.empty() && output != error) {
+        message.push_back('\n');
+        message.append(result.output);
+    }
+    return message;
+}
+
+bool dep_version_matches_(std::string_view nodeVersion,
+                          std::string_view depVersion) {
+    if (depVersion.empty()) return true;
+    if (nodeVersion == depVersion) return true;
+    return semver::satisfies_expr(nodeVersion, depVersion);
+}
+
+std::filesystem::path
+configure_xpkg_execution_artifact_paths_(
+        mcpplibs::xpkg::ExecutionContext& context) {
+    auto subosDir = Config::xvm_artifact_subos_dir();
+    context.bin_dir = subosDir / "bin";
+    context.subos_sysrootdir = subosDir.string();
+    return subosDir;
+}
+
+void configure_dependency_store_roots_(
+        mcpplibs::xpkg::ExecutionContext& context,
+        const std::filesystem::path& selectedStore) {
+    auto append = [&](std::filesystem::path root) {
+        if (root.empty()) return;
+        root = root.lexically_normal();
+        if (std::ranges::find(context.dependency_store_roots, root)
+            == context.dependency_store_roots.end()) {
+            context.dependency_store_roots.push_back(std::move(root));
+        }
+    };
+
+    append(selectedStore);
+    auto projectDataDir = Config::project_data_dir();
+    if (!projectDataDir.empty()) append(projectDataDir / "xpkgs");
+    append(Config::global_data_dir() / "xpkgs");
+}
+
+std::string pkgindex_root_for_(const std::filesystem::path& pkgFile, bool* outHasLibs) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+
+    auto derived = pkgFile.parent_path().parent_path().parent_path();
+    if (fs::is_directory(derived / "libs", ec)) {
+        if (outHasLibs) *outHasLibs = true;
+        return derived.string();
+    }
+
+    // Only the primary index. Not "any index that happens to have libs": picking
+    // between several would be a guess about which ecosystem a recipe belongs to,
+    // and `xim.pkgindex.*` is one shared namespace by construction.
+    auto primary = Config::global_data_dir() / "xim-pkgindex";
+    if (fs::is_directory(primary / "libs", ec)) {
+        log::debug("pkgindex modules: {} has no libs/, using {}",
+                   derived.string(), primary.string());
+        if (outHasLibs) *outHasLibs = true;
+        return primary.string();
+    }
+
+    if (outHasLibs) *outHasLibs = false;
+    return derived.string();
+}
+
+bool executing_provider_owns_no_version(
+        const xvm::VersionDB& db,
+        std::string_view target,
+        std::string_view executingProvider) {
+    if (executingProvider.empty()) return false;
+    auto it = db.find(std::string(target));
+    if (it == db.end()) return true;
+    for (const auto& [_, data] : it->second.versions) {
+        if (!data.bindingGroup || data.bindingGroup->provider.empty()) continue;
+        if (data.bindingGroup->provider == executingProvider) return false;
+    }
+    return true;
+}
+
+std::string effective_store_name_(std::string_view namespaceName, std::string_view name) {
+    return package_store_name(namespaceName, name);
+}
+
+std::string effective_store_name_(const PlanNode& node) {
+    return effective_store_name_(node.namespaceName, node.name);
+}
+
+std::string effective_store_name_(const PackageMatch& match) {
+    return effective_store_name_(match.namespaceName, match.name);
+}
+
+std::string version_namespace_(std::string_view namespaceName) {
+    const auto& globalRepos = Config::global_index_repos();
+    const bool isPrimary = !globalRepos.empty()
+        && namespaceName == globalRepos.front().name;
+    if (isPrimary || namespaceName.empty()) return {};
+    return std::string(namespaceName);
+}
+
+std::string plan_key_(const PlanNode& node) {
+    auto name = node.canonicalName.empty()
+        ? canonical_package_name(node.namespaceName, node.name)
+        : node.canonicalName;
+    if (node.version.empty()) return name;
+    return name + "@" + node.version;
+}
+
+std::filesystem::path data_root_for_(const std::filesystem::path& targetRoot) {
+    if (targetRoot.filename() == "xpkgs") return targetRoot.parent_path();
+    return targetRoot;
+}
+
+std::filesystem::path runtime_dir_(const PlanNode& node,
+                                   const std::filesystem::path& fallbackDataDir) {
+    auto targetRoot = node.storeRoot.empty() ? (fallbackDataDir / "xpkgs") : node.storeRoot;
+    auto dataRoot = data_root_for_(targetRoot);
+    return dataRoot / "runtimedir";
+}
+
+std::filesystem::path xpkg_snapshot_file_(const std::filesystem::path& installDir) {
+    return installDir / ".xpkg.lua";
+}
+
+std::expected<void, std::string>
+save_xpkg_snapshot_(const std::filesystem::path& sourcePkgFile,
+                    const std::filesystem::path& installDir) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+
+    if (sourcePkgFile.empty()
+        || !fs::exists(sourcePkgFile, ec)
+        || !fs::is_regular_file(sourcePkgFile, ec)) {
+        return std::unexpected(
+            std::format("xpkg snapshot source not found: {}", sourcePkgFile.string()));
+    }
+
+    fs::create_directories(installDir, ec);
+    if (ec) {
+        return std::unexpected(
+            std::format("failed to create install dir for xpkg snapshot: {}", ec.message()));
+    }
+
+    auto snapshotFile = xpkg_snapshot_file_(installDir);
+    ec.clear();
+    if (fs::exists(snapshotFile, ec)) {
+        ec.clear();
+        if (fs::equivalent(sourcePkgFile, snapshotFile, ec) && !ec) return {};
+    }
+
+    ec.clear();
+    fs::copy_file(sourcePkgFile, snapshotFile, fs::copy_options::overwrite_existing, ec);
+    if (ec) {
+        return std::unexpected(
+            std::format("failed to save xpkg snapshot {}: {}",
+                        snapshotFile.string(), ec.message()));
+    }
+    return {};
+}
+
+std::filesystem::path uninstall_xpkg_file_(const std::filesystem::path& indexPkgFile,
+                                           const std::filesystem::path& installDir) {
+    std::error_code ec;
+    auto snapshotFile = xpkg_snapshot_file_(installDir);
+    if (std::filesystem::exists(snapshotFile, ec)) {
+        return snapshotFile;
+    }
+    return indexPkgFile;
+}
+
+bool is_archive_(const std::filesystem::path& path) {
+    auto filename = path.filename().string();
+    return filename.ends_with(".tar.gz")
+        || filename.ends_with(".tar.xz")
+        || filename.ends_with(".tar.bz2")
+        || filename.ends_with(".tgz")
+        || filename.ends_with(".zip");
+}
+
+std::string detect_arch_() {
+    return std::string(xlings::platform::build_arch());
+}
+
+std::string default_res_server_() {
+    auto server = Config::resource_server();
+    if (!server.empty()) return server;
+    return "https://github.com/xlings-res";
+}
+
+std::string build_xlings_res_url_with_server_(std::string_view server,
+                                              std::string_view pkgName,
+                                              std::string_view version,
+                                              std::string_view platform) {
+    auto ext = std::string(platform) == "windows" ? "zip" : "tar.gz";
+    return std::format("{}/{}/releases/download/{}/{}-{}-{}-{}.{}",
+                       server,
+                       pkgName,
+                       version,
+                       pkgName,
+                       version,
+                       platform,
+                       detect_arch_(),
+                       ext);
+}
+
+std::string build_xlings_res_url_(std::string_view pkgName,
+                                  std::string_view version,
+                                  std::string_view platform) {
+    return build_xlings_res_url_with_server_(default_res_server_(), pkgName, version, platform);
+}
+
+std::vector<std::string> build_xlings_res_fallback_urls_(std::string_view pkgName,
+                                                         std::string_view version,
+                                                         std::string_view platform) {
+    auto selected = default_res_server_();
+    auto candidates = Config::resource_servers_with_cross_region();
+    std::vector<std::string> fallbacks;
+    for (auto& server : candidates) {
+        if (server != selected) {
+            fallbacks.push_back(
+                build_xlings_res_url_with_server_(server, pkgName, version, platform));
+        }
+    }
+    return fallbacks;
+}
+
+std::expected<DownloadResource_, std::string> resolve_download_resource_(
+        const mcpplibs::xpkg::PlatformMatrix& matrix,
+        std::string_view name,
+        std::string_view requestedVersion,
+        std::string_view platform,
+        std::string_view arch,
+        std::string_view preferredMirror) {
+    auto resolved = mcpplibs::xpkg::resolve_resource(matrix, {
+        .name = std::string(name),
+        .version = std::string(requestedVersion),
+        .platform = std::string(platform),
+        .arch = std::string(arch),
+    });
+    if (!resolved) return std::unexpected(resolved.error());
+
+    DownloadResource_ result {
+        .version = resolved->version,
+        .url = resolved->url,
+        .sha256 = resolved->sha256,
+        .mirrors = resolved->mirrors,
+        .useResFallbacks = resolved->kind
+            == mcpplibs::xpkg::SourceKind::XlingsRes,
+    };
+    if (result.useResFallbacks) {
+        result.url = build_xlings_res_url_(name, result.version, platform);
+    }
+
+    auto preferred = preferredMirror.empty()
+        ? std::string_view{"GLOBAL"}
+        : preferredMirror;
+    if (auto it = result.mirrors.find(std::string(preferred));
+            it != result.mirrors.end()) {
+        result.url = it->second;
+    }
+    if (result.url.empty())
+        return std::unexpected("resolved resource URL is empty");
+    return result;
+}
+
+bool has_directory_entries_(const std::filesystem::path& dir) {
+    std::error_code ec;
+    if (!std::filesystem::exists(dir, ec) || !std::filesystem::is_directory(dir, ec)) return false;
+    return std::filesystem::directory_iterator(dir, ec) != std::default_sentinel;
+}
+
+bool stage_extracted_payload_(const std::filesystem::path& extractRoot,
+                              const std::filesystem::path& installDir) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    if (!fs::exists(extractRoot, ec) || !fs::is_directory(extractRoot, ec)) return false;
+
+    std::vector<fs::path> entries;
+    for (fs::directory_iterator it(extractRoot, ec);
+         !ec && it != std::default_sentinel; it.increment(ec)) {
+        entries.push_back(it->path());
+    }
+    if (ec || entries.empty()) return false;
+
+    fs::path payloadRoot = extractRoot;
+    if (entries.size() == 1 && fs::is_directory(entries.front(), ec) && !ec) {
+        payloadRoot = entries.front();
+    }
+
+    if (fs::exists(installDir, ec)) {
+        if (fs::is_empty(installDir, ec)) {
+            ec.clear();
+            fs::remove_all(installDir, ec);
+            if (ec) return false;
+        } else {
+            return true;
+        }
+    }
+
+    fs::create_directories(installDir.parent_path(), ec);
+    if (ec) return false;
+
+    if (payloadRoot != extractRoot) {
+        fs::rename(payloadRoot, installDir, ec);
+        if (!ec) return true;
+        ec.clear();
+    }
+
+    fs::create_directories(installDir, ec);
+    if (ec) return false;
+
+    auto move_entry = [&](const fs::path& source) -> bool {
+        auto dest = installDir / source.filename();
+        fs::rename(source, dest, ec);
+        if (!ec) return true;
+        ec.clear();
+        fs::copy(source, dest,
+                 fs::copy_options::recursive | fs::copy_options::overwrite_existing,
+                 ec);
+        if (ec) return false;
+        ec.clear();
+        fs::remove_all(source, ec);
+        return !ec;
+    };
+
+    if (payloadRoot == extractRoot) {
+        for (auto& entry : entries) {
+            if (!move_entry(entry)) return false;
+        }
+        return true;
+    }
+
+    std::vector<fs::path> payloadEntries;
+    for (fs::directory_iterator it(payloadRoot, ec);
+         !ec && it != std::default_sentinel; it.increment(ec)) {
+        payloadEntries.push_back(it->path());
+    }
+    if (ec) return false;
+    for (auto& entry : payloadEntries) {
+        if (!move_entry(entry)) return false;
+    }
+    return true;
+}
+
+bool normalize_file_install_(const std::filesystem::path& installPath) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    if (!fs::exists(installPath, ec) || !fs::is_regular_file(installPath, ec)) return true;
+
+    auto parent = installPath.parent_path();
+    auto fileName = installPath.filename();
+    auto tempFile = parent / (fileName.string() + ".xlings.tmp");
+
+    fs::rename(installPath, tempFile, ec);
+    if (ec) return false;
+
+    fs::create_directories(installPath, ec);
+    if (ec) {
+        ec.clear();
+        fs::rename(tempFile, installPath, ec);
+        return false;
+    }
+
+    fs::rename(tempFile, installPath / fileName, ec);
+    if (!ec) return true;
+
+    ec.clear();
+    fs::copy_file(tempFile, installPath / fileName, fs::copy_options::overwrite_existing, ec);
+    if (ec) return false;
+    ec.clear();
+    fs::remove(tempFile, ec);
+    return !ec;
+}
+
+std::filesystem::path current_workspace_config_path_() {
+    if (Config::has_project_config()) {
+        if (Config::project_subos_mode() == ProjectSubosMode::Named) {
+            return Config::project_dir() / ".xlings" / "subos" / Config::project_subos_name() / ".xlings.json";
+        }
+        if (Config::project_subos_mode() == ProjectSubosMode::Anonymous) {
+            return Config::project_state_path();
+        }
+        return Config::project_state_path();
+    }
+    return Config::paths().homeDir / "subos" / Config::paths().activeSubos / ".xlings.json";
+}
+
+xvm::SubosWorkspace load_workspace_file_(const std::filesystem::path& path) {
+    std::error_code ec;
+    if (!std::filesystem::exists(path, ec)) return {};
+    try {
+        auto content = platform::read_file_to_string(path.string());
+        auto json = nlohmann::json::parse(content, nullptr, false);
+        if (json.is_discarded() || !json.is_object()) return {};
+        if (!json.contains("workspace") || !json["workspace"].is_object()) return {};
+        return xvm::subos_workspace_from_json(json["workspace"]);
+    } catch (...) {
+        return {};
+    }
+}
+
+std::vector<std::filesystem::path> workspace_config_paths_for_scope_(PackageScope scope) {
+    namespace fs = std::filesystem;
+    (void)scope;
+    std::vector<fs::path> paths;
+    auto push = [&](fs::path p) {
+        if (p.empty()) return;
+        if (std::ranges::find(paths, p) != paths.end()) return;
+        paths.push_back(std::move(p));
+    };
+
+    if (Config::has_project_config()) {
+        auto projectRoot = Config::project_dir();
+        if (!projectRoot.empty()) {
+            push(Config::project_manifest_path());
+            push(Config::project_state_path());
+            auto subosRoot = projectRoot / ".xlings" / "subos";
+            std::error_code ec;
+            if (fs::exists(subosRoot, ec) && fs::is_directory(subosRoot, ec)) {
+                for (auto& entry : platform::dir_entries(subosRoot)) {
+                    if (entry.is_directory()) {
+                        push(entry.path() / ".xlings.json");
+                    }
+                }
+            }
+        }
+    }
+
+    auto subosRoot = Config::paths().homeDir / "subos";
+    std::error_code ec;
+    if (fs::exists(subosRoot, ec) && fs::is_directory(subosRoot, ec)) {
+        for (auto& entry : platform::dir_entries(subosRoot)) {
+            if (entry.is_directory()) {
+                auto name = entry.path().filename().string();
+                if (name != "current") {
+                    push(entry.path() / ".xlings.json");
+                }
+            }
+        }
+    }
+    return paths;
+}
+
+bool is_version_referenced_anywhere_(PackageScope scope, const std::string& target, const std::string& version, const std::filesystem::path& excludePath) {
+    std::error_code ec;
+    auto excludeCanonical = excludePath.empty() ? std::filesystem::path{} : std::filesystem::weakly_canonical(excludePath, ec);
+    for (auto& configPath : workspace_config_paths_for_scope_(scope)) {
+        auto canonical = std::filesystem::weakly_canonical(configPath, ec);
+        if (!excludeCanonical.empty() && !ec && canonical == excludeCanonical) {
+            continue;
+        }
+        // 0.4.19+: a payload is "referenced" by a subos if EITHER its
+        // active version equals `version` OR `version` appears in that
+        // subos's installed[] set. Pre-0.4.19 the active-only check was
+        // sufficient because installed[] didn't exist; with C2 schema a
+        // user can `xlings remove` the active version while still having
+        // other installed versions, and a payload that only appears in
+        // some other subos's installed[] (but not its active) must still
+        // pin its xpkgs/ directory against GC.
+        //
+        // Stored values are namespaced (`ns:1.0` for non-primary repos,
+        // bare for primary). New removal callers pass the exact stored key;
+        // retain bare matching here for legacy workspace files.
+        auto matches = [&](std::string_view stored) {
+            return stored == version
+                || xvm::strip_namespace(std::string(stored)) == version;
+        };
+        auto sws = load_workspace_file_(configPath);
+        if (auto it = sws.active.find(target);
+            it != sws.active.end() && matches(it->second)) return true;
+        if (auto it = sws.installed.find(target); it != sws.installed.end()) {
+            for (auto& v : it->second) {
+                if (matches(v)) return true;
+            }
+        }
+    }
+    return false;
+}
+
+void remove_target_shims_(const std::string& target, const std::string& version) {
+    namespace fs = std::filesystem;
+    auto db = Config::versions();
+    auto* vinfo = xvm::get_vinfo(db, target);
+    auto& binDir = Config::paths().binDir;
+    std::error_code ec;
+
+    // A program's shim is a generic dispatcher to the bootstrap; the actual
+    // version it routes to is the workspace pointer (read at runtime). So
+    // the shim is only stale when **the current subos** has dropped its
+    // last version of the name. With surviving versions still in this
+    // subos's installed[], the shim must stay — auto-fallback in
+    // detach_current_subos_ updates `active` to the highest remaining
+    // version and the shim resolves through that.
+    //
+    // 0.4.19+: this check is now scoped to the **current subos's
+    // installed[]**, not the global versions DB. Pre-0.4.19 the gate
+    // was `is_last_version_for(global)`, which under-removed: subos A
+    // could drain its installed[] for a target while subos B still had
+    // some other version of it, leaving a stale shim in A's bin/. With
+    // C2 schema each subos's bin/ is independent — so is each subos's
+    // shim-lifetime decision.
+    //
+    // Caller contract: detach_current_subos_ has already pruned
+    // `version` from this subos's installed[] before calling us. So
+    // checking "is the post-removal installed[] empty?" gives the
+    // correct answer.
+    const auto& wsi = Config::workspace_installed();
+    auto subos_has_any_version_of = [&](const std::string& name) {
+        auto it = wsi.find(name);
+        return it != wsi.end() && !it->second.empty();
+    };
+
+    auto mainName = (vinfo && !vinfo->filename.empty()) ? vinfo->filename : target;
+    if (!subos_has_any_version_of(target)) {
+        auto mainShim = binDir / mainName;
+        if (fs::exists(mainShim, ec) || fs::is_symlink(mainShim, ec)) {
+            ec.clear();
+            fs::remove(mainShim, ec);
+        }
+    }
+
+    if (!vinfo) return;
+    for (auto& [bindingName, vermap] : vinfo->bindings) {
+        auto vit = vermap.find(version);
+        if (vit == vermap.end()) continue;
+        if (subos_has_any_version_of(bindingName)) continue;  // still in use here
+        auto bindPath = binDir / bindingName;
+        ec.clear();
+        if (fs::exists(bindPath, ec) || fs::is_symlink(bindPath, ec)) {
+            ec.clear();
+            fs::remove(bindPath, ec);
+        }
+    }
+}
+
+void detach_current_subos_(const std::string& target, const std::string& version, bool persist) {
+    auto& ws = Config::workspace_mut();
+    auto& wsi = Config::workspace_installed_mut();
+
+    auto matches = [&](std::string_view stored) {
+        return stored == version;
+    };
+
+    // Step 1 (0.4.19+): always drop `version` from this subos's
+    // installed[] set, even when it isn't the currently active version.
+    // The set is the per-subos opt-in list; an explicit `xlings remove
+    // foo@X` always means "this subos no longer wants X".
+    bool installedChanged = false;
+    if (auto it = wsi.find(target); it != wsi.end()) {
+        auto& list = it->second;
+        auto pred = [&](const std::string& v) { return matches(v); };
+        auto erased = std::remove_if(list.begin(), list.end(), pred);
+        if (erased != list.end()) {
+            list.erase(erased, list.end());
+            installedChanged = true;
+            if (list.empty()) wsi.erase(it);
+        }
+    }
+
+    // Step 2: if `version` was the active pointer, do the actual subos
+    // teardown (remove headers / libs / shims) and then either fall
+    // back to another installed version or clear the pointer entirely.
+    auto wit = ws.find(target);
+    bool wasActive = wit != ws.end() && matches(wit->second);
+
+    if (wasActive) {
+        auto db = Config::versions();
+        auto sysroot_include = Config::paths().subosDir / "usr" / "include";
+        auto sysroot_lib = Config::paths().libDir;
+        // The whole release's headers, not just whatever single directory
+        // landed in this entry's `includedir`: a release declaring more than
+        // one header directory would otherwise leave all but the last behind
+        // in the sysroot, pointing into a payload that is being deleted.
+        for (const auto& asset :
+                 xvm::group_header_assets(db, target, version)) {
+            xvm::remove_headers(asset, sysroot_include);
+        }
+        if (const auto placement =
+                xvm::library_placement(db, target, version);
+            !placement.empty()) {
+            xvm::remove_library(placement.name, sysroot_lib);
+        }
+        if (const auto file = xvm::file_placement(db, target, version);
+            !file.empty()) {
+            xvm::remove_asset(Config::paths().subosDir / file.destination);
+        }
+        remove_target_shims_(target, version);
+
+        // Auto-fallback: when the user removes the active version but
+        // still has other versions installed in this subos, switch
+        // active to the highest remaining (installed[] is stored
+        // sorted ascending by subos_workspace_to_json — `back()` is
+        // the lexicographically-highest, which approximates "newest"
+        // for typical semver-ish version strings).
+        //
+        // The shim for the fallback version already exists from its
+        // earlier install — only the active pointer needs updating;
+        // headers/libs are NOT auto-relinked (lazy: next call to
+        // `xlings use` would do that explicitly). This avoids a
+        // surprise sysroot reshuffle on every remove.
+        if (auto sit = wsi.find(target); sit != wsi.end() && !sit->second.empty()) {
+            wit->second = sit->second.back();
+        } else {
+            ws.erase(wit);
+        }
+    }
+
+    if (persist && (wasActive || installedChanged)) {
+        Config::save_workspace();
+    }
+}
+
+bool apply_subos_env_ops_(const std::vector<mcpplibs::xpkg::XvmOp>& operations,
+                          const PlanNode& node) {
+    namespace mf = xlings::subos::manifest;
+
+    std::vector<const mcpplibs::xpkg::XvmOp*> declarations;
+    for (const auto& op : operations)
+        if (op.op == "subos_env") declarations.push_back(&op);
+    if (declarations.empty()) return true;
+
+    const auto canonical = node.canonicalName.empty()
+        ? canonical_package_name(node.namespaceName, node.name)
+        : node.canonicalName;
+
+    const auto subosDir = Config::xvm_artifact_subos_dir();
+    auto docPath = mf::config_path(subosDir);
+    auto doc = mf::read_document(subosDir);
+    if (!doc) {
+        // Absent is recoverable (an old subos predates the block); unreadable
+        // is not, and must not be papered over by starting from {} -- that
+        // would discard a workspace we never managed to parse.
+        std::error_code ec;
+        if (std::filesystem::exists(docPath, ec)) {
+            log::error("[xim] {} is not readable JSON; refusing to record "
+                       "subos env declarations for {}@{}",
+                       docPath.string(), canonical, node.version);
+            return false;
+        }
+        nlohmann::json fresh;
+        fresh["workspace"] = nlohmann::json::object();
+        fresh[std::string(mf::BLOCK)] = mf::make_block(
+            mf::DEFAULT_RUNTIME, std::format("xlings {}", Info::VERSION),
+            platform::host_glibc_version());
+        doc = std::move(fresh);
+    }
+    if (!doc->contains(std::string(mf::BLOCK))
+        || !doc->at(std::string(mf::BLOCK)).is_object()) {
+        (*doc)[std::string(mf::BLOCK)] = mf::make_block(
+            mf::DEFAULT_RUNTIME, std::format("xlings {}", Info::VERSION),
+            platform::host_glibc_version());
+    }
+
+    // C1 -- the subos layer's "exactly one", for the case where nothing else
+    // can supply it.
+    //
+    // The store keeps many versions by design; each consumer freezes one into
+    // its own RPATH; the subos in between holds exactly one. Nothing enforced
+    // that, so installing a second version appended a second provider section
+    // and BOTH contributed. Measured: mesa@25.0.7 and mesa@25.0.7.1 both bound
+    // in one subos, both on __EGL_VENDOR_LIBRARY_DIRS, EGL enumerating the
+    // device twice, doctor silent. The two records agreed -- on an answer the
+    // model forbids.
+    //
+    // The live version is normally decided by xvm and read back at activation
+    // (manifest::select_effective), so a package WITH an active version needs
+    // nothing here: installing a second version leaves the first live until
+    // `xlings use` says otherwise, which is what install and use have meant
+    // since 2026.7.31. Superseding here as well would make install a second
+    // selector -- another answerer to a question that has one, which is the
+    // defect, not the fix.
+    //
+    // What is left is the case where xvm has no answer at all. Measured: a bare
+    // `xvm.add(name)` DOES record an active version, so an ordinary install
+    // never reaches this branch -- it covers a manifest whose workspace record
+    // was lost while its declarations survived (a payload pruned out from under
+    // it, a subos config copied between homes, a hand edit). There every
+    // provider contributes, so a second version really does double the
+    // environment, and the only moment anything can choose is now, while a
+    // human is naming a version. So: supersede only when nothing else can.
+    //
+    // Before the ownership checks below, deliberately: those return false on a
+    // malformed declaration, and unbinding first would leave the subos holding
+    // neither version.
+    std::vector<std::string> superseded;
+    {
+        const auto active = mf::active_versions(*doc);
+        std::set<std::string> ownNames;
+        for (const auto* op : declarations) {
+            if (!mf::is_binding(op->binding)) continue;
+            ownNames.insert(std::string(mf::binding_name(op->binding)));
+        }
+        for (const auto& name : ownNames) {
+            if (active.contains(name)) continue;   // xvm decides, not install
+            for (const auto& existing : mf::providers_named(*doc, name)) {
+                const bool sameBinding = std::ranges::any_of(
+                    declarations, [&](const auto* op) {
+                        return op->binding == existing;
+                    });
+                if (sameBinding) continue;     // re-install of the same version
+                superseded.push_back(existing);
+            }
+        }
+    }
+
+    bool changed = false;
+    // Collected per binding first, so each section can be written as a whole.
+    // std::map, not unordered: the write order of sections shows up in the file
+    // a user reads and in diffs of it.
+    std::map<std::string, std::vector<mf::EnvDecl>> perBinding;
+    for (const auto* op : declarations) {
+        if (!mf::is_binding(op->binding)) {
+            log::error("[xim] {}@{} declared env '{}' with binding '{}' "
+                       "(expected <name>@<version>); nothing recorded",
+                       canonical, node.version, op->var, op->binding);
+            return false;
+        }
+        const auto owner = mf::binding_name(op->binding);
+        if (owner != node.name && owner != canonical) {
+            log::error("[xim] {}@{} declared env '{}' for '{}', which it does "
+                       "not own; nothing recorded",
+                       canonical, node.version, op->var, op->binding);
+            return false;
+        }
+        // B5 / B3: a declaration that can put our code into someone else's
+        // process is a privileged operation, and install is the only moment a
+        // human is watching. Reported, not refused -- nvidia-gl-host-link
+        // legitimately needs one today, and refusing would leave the user with
+        // no GPU and no way forward. What must not happen is that it lands
+        // silently: the last one did, and `xlings subos use` returned a
+        // /bin/bash that died of SIGSEGV before printing a character.
+        //
+        // Default-deny by variable name (manifest::names_only_data), so a
+        // variable nobody has classified reads as privileged. See AD-3.
+        if (mf::is_privileged_env(op->var, op->value)) {
+            log::warn("[xim] {}@{} declares {} = {}", canonical, node.version,
+                      op->var, op->value);
+            log::warn("      This variable can load code from our payload into "
+                      "processes we do not own, including host binaries running "
+                      "under the host loader. Prefer RPATH on the consumer; use "
+                      "this only where RPATH cannot reach (a library that opens "
+                      "its plugins itself), and say why in the recipe.");
+        }
+        perBinding[op->binding].push_back(
+            {.var = op->var, .op = op->mode, .value = op->value});
+    }
+
+    // Written as a REPLACEMENT of each binding's section, not a union with it.
+    //
+    // `add_env` is idempotent per (var, op, value) triple, which keeps a re-run
+    // of the same declarations steady and silently accumulates a second
+    // generation when the recipe's declarations CHANGE. Measured while moving
+    // mesa's discovery paths from `${pkgdir}` to `${subosdir}`: the section held
+    // both, so LIBGL_DRIVERS_PATH resolved to the new subos directory followed
+    // by a stale payload path and __EGL_VENDOR_LIBRARY_DIRS listed one directory
+    // twice -- with nothing reporting it, and the stale entry becoming a dead
+    // directory as soon as that payload is collected.
+    //
+    // Only bindings that declared something THIS run are touched. A binding
+    // belonging to another package keeps its section; that is the same
+    // ownership-by-binding rule that lets uninstall need no recipe cleanup.
+    //
+    // A package that stops declaring env entirely is NOT handled here and must
+    // not be: `declarations` is empty then, this function returns before the
+    // ownership checks, and the stale section is removed by uninstall or by
+    // `superseded` above. Clearing on an empty batch would delete a live
+    // section every time an unrelated dependent's install re-ran a hook that
+    // happens to declare nothing.
+    for (const auto& [binding, decls] : perBinding) {
+        changed |= mf::set_env_section(*doc, binding, decls);
+    }
+
+    // Only now that every declaration passed. Reported at info level, not
+    // debug: a version silently leaving a subos is exactly the kind of state
+    // change users later cannot account for.
+    for (const auto& binding : superseded) {
+        if (!mf::remove_provider(*doc, binding)) continue;
+        changed = true;
+        log::info("[xim] subos '{}' now holds {}@{}; unbound {} (it declares no "
+                  "xvm version, so nothing else could say which is live)",
+                  Config::paths().activeSubos.empty()
+                      ? std::string{"default"} : Config::paths().activeSubos,
+                  canonical, node.version, binding);
+        log::info("      Its payload is untouched -- the store keeps every "
+                  "installed version. To keep both active, use separate subos.");
+    }
+
+    if (!changed) return true;
+
+    if (auto findings = mf::validate_block(*doc); !findings.empty()) {
+        log::error("[xim] recording env declarations for {}@{} would leave an "
+                   "invalid subos manifest: {}", canonical, node.version,
+                   mf::describe(findings.front().kind));
+        return false;
+    }
+
+    try {
+        platform::write_string_to_file(docPath.string(), doc->dump(2));
+    } catch (const std::exception& e) {
+        log::error("[xim] failed to write {}: {}", docPath.string(), e.what());
+        return false;
+    }
+    log::debug("[xim] recorded {} subos env declaration(s) for {}@{}",
+               declarations.size(), canonical, node.version);
+    return true;
+}
+
+bool process_xvm_operations_(const PlanNode& node,
+                             const std::filesystem::path& dataDir,
+                             mcpplibs::xpkg::PackageExecutor& executor,
+                             bool useAfterInstall) {
+    auto xvm_ops = executor.xvm_operations();
+
+    // Before the early return below. A package that declares only env and
+    // registers nothing with xvm has an empty registration batch, and would
+    // otherwise install cleanly with its declarations dropped on the floor --
+    // the exact shape where "nothing happened" and "it worked" look alike.
+    if (!apply_subos_env_ops_(xvm_ops, node)) return false;
+
+    auto& paths = Config::paths();
+    auto& scopedDb = Config::versions_mut();
+    auto& scopedWorkspace = Config::workspace_mut();
+    auto& scopedInstalled = Config::workspace_installed_mut();
+    const auto artifactSubosDir =
+        Config::xvm_artifact_subos_dir();
+    const auto artifactBinDir = artifactSubosDir / "bin";
+    const auto sysroot_lib = artifactSubosDir / "lib";
+    const auto sysroot_include =
+        artifactSubosDir / "usr" / "include";
+
+    // Locate xlings binary for shim creation
+#ifdef _WIN32
+    auto xlings_bin = paths.homeDir / "bin" / "xlings.exe";
+    constexpr std::string_view shim_ext = ".exe";
+#else
+    auto xlings_bin = paths.homeDir / "bin" / "xlings";
+    constexpr std::string_view shim_ext = "";
+#endif
+    if (!std::filesystem::exists(xlings_bin))
+        xlings_bin = paths.homeDir / "xlings";
+
+    // Primary repo versions retain their historical bare keys. Other repos
+    // retain their namespace so install and exact removal resolve identically.
+    const auto versionNamespace = version_namespace_(node.namespaceName);
+
+    auto registration = normalize_xpkg_registration_plan(
+        node, xvm_ops, versionNamespace, dataDir, useAfterInstall);
+    if (!registration) {
+        log::warn(
+            "xvm registration normalization failed for {}@{}: {} "
+            "(operation={}, target='{}', version='{}')",
+            node.canonicalName.empty()
+                ? canonical_package_name(node.namespaceName, node.name)
+                : node.canonicalName,
+            node.version,
+            registration.error().message,
+            registration.error().operationIndex,
+            registration.error().target,
+            registration.error().version);
+        return false;
+    }
+    const bool hasRemoval = std::ranges::any_of(
+        xvm_ops,
+        [](const auto& operation) {
+            return operation.op == "remove"
+                || operation.op == "remove_all";
+        });
+    if (!hasRemoval
+        && registration->batch.nodes.empty()
+        && registration->batch.headers.empty()
+        && registration->effects.empty()) {
+        return true;
+    }
+
+    xvm::RemovalContext removalContext;
+    if (hasRemoval) {
+        auto snapshot = snapshot_xpkg_removal_context(
+            scopedDb, scopedWorkspace, xvm_ops,
+            registration->batch.provider,
+            registration->batch.providerVersion);
+        if (!snapshot) {
+            // Selection runs before any mutation, so nothing has moved yet.
+            log::error("{}", xvm::render(
+                xvm::describe(
+                    snapshot.error(),
+                    std::format("{}@{}",
+                                registration->batch.provider,
+                                registration->batch.providerVersion)),
+                /*nothingChanged=*/true));
+            return false;
+        }
+        removalContext = std::move(*snapshot);
+    }
+
+    const auto dbBeforeRemoval = scopedDb;
+    const auto workspaceBeforeRemoval = scopedWorkspace;
+    auto metadata = apply_xpkg_xvm_metadata_batch(
+        scopedDb,
+        scopedWorkspace,
+        scopedInstalled,
+        xvm_ops,
+        removalContext,
+        *registration);
+    if (!metadata) {
+        const auto owner = std::format("{}@{}",
+                                       registration->batch.provider,
+                                       registration->batch.providerVersion);
+        // apply_xpkg_xvm_metadata_batch works on copies and only swaps them
+        // in on success, so a failure here has left the stored state alone.
+        if (std::holds_alternative<xvm::RemovalError>(
+                metadata.error())) {
+            log::error("{}", xvm::render(
+                xvm::describe(
+                    std::get<xvm::RemovalError>(metadata.error()), owner),
+                /*nothingChanged=*/true));
+        } else {
+            log::error("{}", xvm::render(
+                xvm::describe(
+                    std::get<xvm::RegistrationError>(metadata.error()), owner),
+                /*nothingChanged=*/true));
+        }
+        return false;
+    }
+
+    cleanup_removed_xvm_library_artifacts(
+        sysroot_lib,
+        dbBeforeRemoval,
+        scopedDb,
+        metadata->removal);
+
+    // Removal takes the removed release's headers out of the sysroot. When
+    // it then falls back to a surviving release, nothing put that release's
+    // headers back -- the sysroot ended up with none at all, and `xlings use`
+    // could not repair it because switching to an already-active version is
+    // a no-op. Re-materialize whatever the fallback made active.
+    for (const auto& [target, version] : scopedWorkspace) {
+        auto beforeIt = workspaceBeforeRemoval.find(target);
+        if (beforeIt != workspaceBeforeRemoval.end()
+            && beforeIt->second == version) {
+            continue;  // unchanged
+        }
+        auto infoIt = scopedDb.find(target);
+        if (infoIt == scopedDb.end()) continue;
+        auto dataIt = infoIt->second.versions.find(version);
+        if (dataIt == infoIt->second.versions.end()) continue;
+        for (const auto& asset :
+                 xvm::group_header_assets(scopedDb, target, version)) {
+            xvm::install_headers(asset, sysroot_include);
+        }
+        if (const auto placement =
+                xvm::library_placement(scopedDb, target, version);
+            !placement.empty()) {
+            xvm::place_library(placement.source, placement.name, sysroot_lib);
+        }
+        if (const auto file = xvm::file_placement(scopedDb, target, version);
+            !file.empty()) {
+            xvm::place_asset(file.source,
+                             Config::paths().subosDir / file.destination);
+        }
+    }
+
+    // Written after the batch, not inside it: the batch owns the group model
+    // and must not be taught a legacy field. This runs against the committed
+    // scopedDb, so a package whose own name is not a registered target simply
+    // gets no marker rather than a phantom entry.
+    if (const auto headerVersion =
+            xvm::make_ns_version(versionNamespace, node.version);
+        attach_legacy_header_dir(
+            scopedDb, node.name, headerVersion, metadata->effects) == 0) {
+        const bool declaresHeaders = std::ranges::any_of(
+            metadata->effects, [](const XpkgFilesystemEffect& effect) {
+                return effect.kind == XpkgFilesystemEffectKind::InstallHeaders;
+            });
+        if (declaresHeaders) {
+            log::debug(
+                "[xim] headers declared but '{}@{}' is not a registered "
+                "target; `xlings use` will not swap them",
+                node.name, headerVersion);
+        }
+    }
+
+    for (const auto& effect : metadata->effects) {
+        auto resolved = resolve_xpkg_filesystem_effect(
+            scopedDb, scopedWorkspace, effect);
+        if (!resolved) {
+            log::warn(
+                "validated xvm effect target disappeared or changed kind: "
+                "{}@{}",
+                effect.target, effect.version);
+            continue;
+        }
+        if (resolved->kind
+            == XpkgFilesystemEffectKind::InstallHeaders) {
+            if (!resolved->active) {
+                // Installing a non-active version must not disturb the
+                // sysroot: `xlings use` is what moves headers, and it cannot
+                // undo this because switching to an already-active version
+                // is a no-op.
+                log::debug("[xim] headers for {}@{} not installed: not the "
+                           "active version", resolved->target, resolved->version);
+                continue;
+            }
+            xvm::install_headers(
+                resolved->sourceDir, sysroot_include);
+            continue;
+        }
+        if (resolved->kind
+            == XpkgFilesystemEffectKind::RemoveHeaders) {
+            xvm::remove_headers(
+                resolved->sourceDir, sysroot_include);
+            continue;
+        }
+        if (resolved->kind
+            == XpkgFilesystemEffectKind::ProgramShim) {
+            // A shim is only meaningful for a name that has an active
+            // version -- that is what shim_dispatch resolves against, and
+            // without one the file can only ever print "no active version
+            // of 'X' in current subos". Writing it anyway is what produced
+            // doctor's `orphan shim`, an error the user could not fix:
+            // `--fix` deleted the file and the next install recreated it.
+            //
+            // Registration deliberately withholds activation from a release
+            // whose group already has an active member (see
+            // registration.cppm, `activateGroup`), so every name that is new
+            // in that release lands here. The sibling effects below already
+            // guard on activation; this one did not.
+            //
+            // The question is about the NAME, not this version: a second
+            // version of an active program must not delete or skip the shim
+            // its active sibling needs. And a name activated later still
+            // gets its file -- `cmd_use` creates shims for every member of
+            // the release it switches to (xvm/commands.cppm).
+            const auto activeIt = scopedWorkspace.find(resolved->target);
+            const bool nameHasActiveVersion =
+                activeIt != scopedWorkspace.end()
+                && !activeIt->second.empty();
+            if (!nameHasActiveVersion) {
+                log::debug(
+                    "[xim] shim for {}@{} not created: no active version of "
+                    "'{}' in this subos",
+                    resolved->target, effect.version, resolved->target);
+                continue;
+            }
+            if (std::filesystem::exists(xlings_bin)) {
+                std::string shimName = resolved->target;
+                if (!shim_ext.empty() && !shimName.ends_with(shim_ext)) {
+                    shimName += shim_ext;
+                }
+                std::filesystem::create_directories(artifactBinDir);
+                xself::create_shim(
+                    xlings_bin, artifactBinDir / shimName);
+                if (artifactBinDir
+                    != Config::global_subos_bin_dir()) {
+                    common::mirror_shim_to_global_bin(
+                        xlings_bin, shimName);
+                }
+            }
+
+            if (resolved->active
+                && xvm::is_xlings_binary(resolved->target)
+                && std::filesystem::exists(xlings_bin)
+                && !resolved->path.empty()
+                && !resolved->sourceName.empty()) {
+                auto activeName = resolved->sourceName;
+                if (!shim_ext.empty()
+                    && !activeName.ends_with(shim_ext)) {
+                    activeName += shim_ext;
+                }
+                const auto activeBin =
+                    std::filesystem::path(resolved->path)
+                    / activeName;
+                if (std::filesystem::exists(activeBin)) {
+                    // The same writer `xlings use xlings <v>` goes through.
+                    // Two independent replacements of the one file every shim
+                    // dispatches through is how a home ends up running a
+                    // client nobody chose -- see entry_binary.cppm.
+                    entry_binary::replace_with(
+                        activeBin, xlings_bin,
+                        std::format("{}@{}", resolved->target, effect.version),
+                        effect.version);
+                }
+                xself::compat::v0_4_8::cleanup_legacy_alias_shims(
+                    artifactBinDir, xlings_bin);
+            }
+            continue;
+        }
+        if (resolved->kind == XpkgFilesystemEffectKind::FileAsset) {
+            if (!resolved->active) {
+                log::debug("[xim] file asset {}@{} not placed: not the "
+                           "active version", resolved->target,
+                           resolved->version);
+                continue;
+            }
+            if (const auto file = xvm::file_placement(
+                    scopedDb, resolved->target, resolved->version);
+                !file.empty()) {
+                xvm::place_asset(file.source,
+                                 artifactSubosDir / file.destination);
+            } else {
+                log::warn("[xim] file asset {}@{} declares no usable "
+                          "destination; nothing placed",
+                          resolved->target, resolved->version);
+            }
+            continue;
+        }
+        if (resolved->kind != XpkgFilesystemEffectKind::Library
+            || resolved->path.empty()) {
+            continue;
+        }
+        if (!resolved->active) {
+            // Installing a version that does not become active must not
+            // disturb the sysroot. `InstallHeaders` has been gated this way
+            // since 0.4.70; `Library` was not, so installing a second version
+            // of a package overwrote the active version's library while its
+            // headers stayed put -- the sysroot then held a library from one
+            // release beside headers from another, which compiles and fails
+            // at run time. `xlings use` is what moves libraries.
+            log::debug("[xim] library {}@{} not placed: not the active "
+                       "version", resolved->target, resolved->version);
+            continue;
+        }
+
+        const auto source =
+            std::filesystem::path(resolved->path)
+            / resolved->sourceName;
+        const auto destination =
+            sysroot_lib / resolved->destinationName;
+        std::filesystem::create_directories(sysroot_lib);
+        std::error_code ec;
+        if (std::filesystem::exists(destination, ec)
+            || std::filesystem::is_symlink(destination, ec)) {
+            std::filesystem::remove(destination, ec);
+        }
+        ec.clear();
+        if (std::filesystem::exists(source, ec)) {
+            std::filesystem::create_symlink(
+                source, destination, ec);
+        }
+    }
+
+    cleanup_removed_xvm_program_artifacts(
+        artifactBinDir,
+        dbBeforeRemoval,
+        scopedDb,
+        scopedInstalled,
+        metadata->removal);
+
+    // Announce any owner-less entry this install took over.
+    //
+    // Adoption replaces the contents recorded for a name@version that an
+    // older client wrote without ownership (xvm/registration.cppm). It is the
+    // right thing to do — the refusal it replaced left the user with no exit
+    // (#422) — but it is still a payload changing behind a name, so it is
+    // said out loud rather than applied silently.
+    for (const auto& member : metadata->registered) {
+        if (!member.adoptedLegacy) continue;
+        log::warn("[xvm] adopted a pre-ownership registration: {}@{} ('{}' changed)",
+                  member.target, member.version, member.adoptedLegacyField);
+    }
+
+    // Announce anything the batch left behind rather than refused over.
+    //
+    // These are names an older client registered for this same payload on a
+    // platform whose recipe produces them and this one's does not (a Windows
+    // llvm leaves `cl`, `lib`, `link`, `rc`). They keep their record and lose
+    // their edge to this release; `self doctor` reports them and can prune
+    // them. Silence here would make a release quietly shed members.
+    for (const auto& member : metadata->detachedLegacy) {
+        log::warn("[xvm] detached a legacy entry this platform no longer "
+                  "registers: {} (run `xlings self doctor --fix` to clear it)",
+                  xvm::display_coordinate(member.target, member.version));
+    }
+
+    if (!metadata->removal.removed.empty()
+        || !metadata->registered.empty()) {
+        Config::save_versions();
+        Config::save_workspace();
+    }
+    return true;
+}
+
+bool run_config_hook_(const PlanNode& node, const std::filesystem::path& dataDir, mcpplibs::xpkg::PackageExecutor& executor, mcpplibs::xpkg::ExecutionContext& ctx, std::function<void(const InstallStatus&)> onStatus, bool useAfterInstall, std::string* failureMessage) {
+    if (!executor.has_hook(mcpplibs::xpkg::HookType::Config)) return true;
+    if (onStatus) {
+        onStatus({ node.name, InstallPhase::Configuring, 0.8f, "" });
+    }
+    ScopedCurrentDir_ configCwd(ctx.install_dir);
+    auto hookResult = executor.run_hook(mcpplibs::xpkg::HookType::Config, ctx);
+    if (!hookResult.success) {
+        if (failureMessage) {
+            *failureMessage = format_hook_failure("config", hookResult);
+        }
+        return false;
+    }
+    if (!process_xvm_operations_(node, dataDir, executor, useAfterInstall)) {
+        if (failureMessage) *failureMessage = "config hook failed";
+        return false;
+    }
+    return true;
+}
+
+std::vector<std::string> unfulfilled_program_promises_(const InstallPlan& plan) {
+    std::vector<std::string> broken;
+    // By value, per Config::versions()'s contract -- it merges global and
+    // project state into a fresh map, so a reference into the temporary would
+    // dangle at the end of the full expression.
+    const auto db = Config::versions();
+
+    for (const auto& node : plan.nodes) {
+        // Build-only deps are intentionally never registered or shimmed.
+        if (node.kind == DepKind::Build) continue;
+        if (node.programs.empty()) continue;
+
+        const bool anyRegistered = std::ranges::any_of(
+            node.programs,
+            [&](const std::string& prog) { return xvm::has_target(db, prog); });
+        if (anyRegistered) continue;
+
+        std::string names;
+        for (const auto& prog : node.programs) {
+            if (!names.empty()) names += ", ";
+            names += prog;
+        }
+        log::error("{} installed but registered none of the programs it "
+                   "declares: {}", node.name, names);
+        broken.push_back(node.name);
+    }
+    return broken;
+}
+
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::xim::detail_ {
+
+ScopedCurrentDir_::ScopedCurrentDir_(const std::filesystem::path& newDir) {
+    std::error_code ec;
+    oldDir_ = std::filesystem::current_path(ec);
+    if (ec || newDir.empty()) return;
+    std::filesystem::create_directories(newDir, ec);
+    if (ec) return;
+    std::filesystem::current_path(newDir, ec);
+    changed_ = !ec;
+}
+
+ScopedCurrentDir_::~ScopedCurrentDir_() {
+    if (!changed_) return;
+    std::error_code ec;
+    std::filesystem::current_path(oldDir_, ec);
+}
+
+} // namespace xlings::xim::detail_
+
+namespace xlings::xim {
+
+Installer::Installer(IndexManager& index) : index_(&index) {}
+
+Installer::Installer(PackageCatalog& catalog) : catalog_(&catalog) {}
+
+std::filesystem::path Installer::locate_dep_install_dir_(const InstallPlan& plan,
+                            const std::filesystem::path& dataDir,
+                            std::string_view depRef) {
+    auto at = depRef.find('@');
+    auto baseRef = (at == std::string_view::npos) ? depRef
+                                                   : depRef.substr(0, at);
+    auto colon = baseRef.find(':');
+    std::string ns = (colon == std::string_view::npos)
+        ? std::string{}
+        : std::string(baseRef.substr(0, colon));
+    std::string bare = (colon == std::string_view::npos)
+        ? std::string(baseRef)
+        : std::string(baseRef.substr(colon + 1));
+    for (auto& n : plan.nodes) {
+        bool match = (n.name == bare)
+                   || (n.canonicalName == baseRef)
+                   || (n.rawName == depRef);
+        if (!ns.empty()) match = match && (n.namespaceName == ns);
+        if (!match) continue;
+        auto root = n.storeRoot.empty() ? (dataDir / "xpkgs") : n.storeRoot;
+        return root / detail_::effective_store_name_(n) / n.version;
+    }
+    return {};
+}
+
+std::expected<void, std::string> Installer::execute(const InstallPlan& plan, const DownloaderConfig& dlConfig, std::function<void(const InstallStatus&)> onStatus, InstallRequestHandler onInstallRequests, DownloadProgressRenderer onRender, CancellationToken* cancel, bool useAfterInstall) {
+
+    if (plan.has_errors()) {
+        return std::unexpected(
+            std::format("plan has errors: {}", plan.errors[0]));
+    }
+
+    auto dataDir = Config::paths().dataDir;
+    auto platform = detect_platform_();
+
+    // Phase 1: Collect download tasks for non-installed packages
+    log::debug("installer: {} node(s) in plan, dataDir={}", plan.nodes.size(), dataDir.string());
+    std::vector<DownloadTask> dlTasks;
+    std::unordered_set<std::string> plannedDownloads;
+    // Nodes a gate below refused. Phase 2 walks plan.nodes again and is
+    // otherwise unaware of anything decided here, so `continue` alone
+    // only skips the download -- the package still runs install() and
+    // config() and ends up registered. This set is what makes a refusal
+    // mean refused.
+    std::unordered_set<std::string> refusedNodes;
+    for (auto& node : plan.nodes) {
+        if (node.alreadyInstalled) continue;
+
+        const std::string hostArch =
+            mcpplibs::xpkg::normalize_arch(detail_::detect_arch_());
+        auto pkg = mcpplibs::xpkg::load_package(node.pkgFile, {
+            .platform = platform,
+            .arch = hostArch,
+        });
+        if (!pkg) {
+            log::warn("skipping {}: {}", node.name, pkg.error());
+            continue;
+        }
+
+        // Refuse a recipe written against a spec this build does not
+        // implement, rather than falling through to V1 semantics.
+        //
+        // Install only. An already-installed package whose recipe later
+        // moved past us must still be removable -- taking something out
+        // needs no understanding of the spec that put it in.
+        const auto specSupport = xpkg_spec_support(pkg->spec);
+        if (!specSupport.supported) {
+            if (specSupport.declared > 0) {
+                log::error("{}: xpackage spec \"{}\" is newer than this "
+                           "xlings understands (max {})",
+                           node.name, pkg->spec, max_supported_xpkg_spec);
+                log::info("try: xlings self update");
+            } else {
+                log::error("{}: unreadable xpackage spec \"{}\"",
+                           node.name, pkg->spec);
+            }
+            refusedNodes.insert(detail_::plan_key_(node));
+            continue;
+        }
+
+        // Asked of the resource this node is about to download, not of
+        // the package-level `archs` union: a recipe whose macOS entry is a
+        // darwin-arm64 tarball is installable on arm64 no matter what the
+        // union says, and a V1 recipe with an under-declared union must
+        // not be refused on the strength of a field nothing ever enforced.
+        const auto* entry = find_entry(*pkg, platform, node.version);
+        const auto compatibility = check_target_compatibility(
+            *pkg, entry, platform, hostArch);
+        if (!compatibility.supported) {
+            log::error("{}", compatibility_error(node.canonicalName,
+                                                   compatibility));
+            refusedNodes.insert(detail_::plan_key_(node));
+            continue;
+        }
+        if (!compatibility.advisory.empty()) {
+            log::warn("{}", compatibility.advisory);
+        }
+
+        auto resource = detail_::resolve_download_resource_(
+            pkg->xpm, node.name, node.version, platform, hostArch,
+            dlConfig.preferredMirror);
+        if (!resource) {
+            log::warn("skipping {}: {}", node.name, resource.error());
+            continue;
+        }
+
+        DownloadTask task;
+        task.name = detail_::plan_key_(node);
+        task.url = resource->url;
+        task.sha256 = resource->sha256;
+        task.cacheIdentity = std::format(
+            "{}/{}/{}/{}/{}",
+            node.name, resource->version, platform, hostArch,
+            resource->useResFallbacks ? "xlings-res" : resource->url);
+        task.destDir = detail_::runtime_dir_(node, dataDir);
+
+        if (resource->useResFallbacks) {
+            task.fallbackUrls = detail_::build_xlings_res_fallback_urls_(
+                node.name, resource->version, platform);
+        }
+
+        // Add remaining mirrors as fallbacks
+        if (!resource->mirrors.empty()) {
+            for (auto& [key, mirrorUrl] : resource->mirrors) {
+                if (mirrorUrl != resource->url) {
+                    task.fallbackUrls.push_back(mirrorUrl);
+                }
+            }
+        }
+        plannedDownloads.insert(task.name);
+        dlTasks.push_back(std::move(task));
+    }
+
+    std::unordered_map<std::string, DownloadResult> downloadResults;
+
+    // Download all
+    if (!dlTasks.empty()) {
+        log::debug("downloading {} package(s)...", dlTasks.size());
+        auto results = download_all(dlTasks, dlConfig, onRender,
+            [&](std::string_view name, float progress) {
+                if (onStatus) {
+                    InstallStatus status;
+                    status.name = std::string(name);
+                    status.phase = progress >= 0
+                        ? InstallPhase::Downloading
+                        : InstallPhase::Failed;
+                    status.progress = std::max(0.0f, progress);
+                    onStatus(status);
+                }
+            }, cancel);
+
+        for (auto& r : results) {
+            if (!r.success) {
+                log::error("download failed for {}: {}", r.name, r.error);
+            } else {
+                downloadResults[r.name] = r;
+            }
+        }
+    }
+
+    // The host glibc this subos recorded at creation, for rule A of the
+    // closure check below. Read once per plan: the manifest cannot change
+    // mid-install, and unknown (empty) stays unknown.
+    std::optional<std::string> hostGlibcCache;
+    auto host_glibc_recorded = [&]() -> const std::string& {
+        if (!hostGlibcCache) {
+            namespace mf = xlings::subos::manifest;
+            hostGlibcCache.emplace();
+            if (auto doc = mf::read_document(Config::xvm_artifact_subos_dir()))
+                *hostGlibcCache = mf::parse(*doc).host_glibc;
+        }
+        return *hostGlibcCache;
+    };
+
+    // Every payload the ledger references, built once for the whole plan.
+    // Rebuilt per node it would be O(nodes x DB); the plan cannot register
+    // anything before phase 2 starts, so one snapshot is correct for the
+    // skip decision -- and the decision is about what a PREVIOUS run left
+    // behind, which is exactly what this snapshot holds.
+    const auto ledgerIndex = LedgerIndex(
+        Config::versions(), Config::paths().homeDir.string());
+
+    // Phase 2: Install each package in topological order
+    for (auto& node : plan.nodes) {
+        // Refused by a gate in phase 1. Skipping here rather than there
+        // is what keeps the refusal per-package: the rest of the plan
+        // installs normally.
+        if (refusedNodes.contains(detail_::plan_key_(node))) continue;
+        if (cancel && cancel->is_cancelled()) {
+            return std::unexpected(std::string("cancelled"));
+        }
+        if (onStatus) {
+            onStatus({ node.name, InstallPhase::Installing, 0.5f, "" });
+        }
+
+        // Create executor and run hooks
+        auto execResult = mcpplibs::xpkg::create_executor(node.pkgFile);
+        if (!execResult) {
+            log::error("failed to create executor for {}: {}",
+                       node.name, execResult.error());
+            if (onStatus) {
+                onStatus({ node.name, InstallPhase::Failed, 0.0f,
+                           execResult.error() });
+            }
+            continue;
+        }
+
+        auto& executor = *execResult;
+        executor.set_log_level(std::string(log::level_string()));
+
+        // Build execution context
+        mcpplibs::xpkg::ExecutionContext ctx;
+        ctx.pkg_name = node.name;
+        ctx.version = node.version;
+        ctx.platform = platform;
+        auto targetRoot = node.storeRoot.empty() ? (dataDir / "xpkgs") : node.storeRoot;
+        ctx.install_dir = targetRoot / detail_::effective_store_name_(node) / node.version;
+        detail_::configure_xpkg_execution_artifact_paths_(
+            ctx);
+        detail_::configure_dependency_store_roots_(ctx, targetRoot);
+        ctx.xpkg_dir = node.pkgFile.parent_path();
+        ctx.project_data_dir = Config::project_data_dir();
+        // pkgindex_dir: package index repo root (for custom module loading).
+        // pkgFile layout: <pkgindex>/pkgs/<letter>/<name>.lua → 3 levels up.
+        bool pkgindexHasLibs = false;
+        ctx.pkgindex_dir =
+            detail_::pkgindex_root_for_(node.pkgFile, &pkgindexHasLibs);
+        if (!pkgindexHasLibs) {
+            // Loud, because the alternative is a package that installs
+            // "successfully" with none of its sysroot assets declared.
+            log::warn("{}: no pkgindex libs/ found -- every "
+                      "`xim.pkgindex.*` call in this recipe will be a "
+                      "silent no-op (sysroot assets, driver dirs and "
+                      "EGL/Vulkan manifests will NOT be declared)",
+                      node.name);
+        }
+        ctx.deps_list = node.deps;                  // legacy union (compat)
+        ctx.runtime_deps_list = node.runtime_deps;  // split form
+        ctx.build_deps_list   = node.build_deps;
+
+        // self_exports: pre-resolve relative paths to absolute by
+        // joining with this package's own install_dir.
+        if (!node.exports.loader.empty()) {
+            ctx.self_exports.loader = (ctx.install_dir / node.exports.loader).string();
+        }
+        ctx.self_exports.abi = node.exports.abi;
+        for (auto& d : node.exports.libdirs) {
+            ctx.self_exports.libdirs.push_back((ctx.install_dir / d).string());
+        }
+
+        // deps_exports: walk the topo plan to find each runtime dep
+        // node and pull its exports (already populated by resolver).
+        // Resolve relative paths against THAT dep's install_dir, not
+        // ours. Strip @version when matching dep_spec → dep node, so
+        // a runtime_deps entry "xim:glibc@2.39" matches the plan
+        // node whose canonicalName == "xim:glibc" + version "2.39".
+        //
+        // The version half is a RANGE, not a literal. `xim:glibc@>=2.38`
+        // resolves to the node at 2.39, and comparing the two as strings
+        // makes them unequal -- so the dep matched no node, contributed no
+        // exports, and elfpatch's predicate concluded "no loader provider
+        // in deps" and patched nothing at all. The package installs
+        // reporting success and is unusable: its own libraries keep a
+        // build-time RPATH, so anything dlopen'd out of it fails to find
+        // its siblings. Nothing in the output says so.
+        //
+        // Every recipe in the index pinned exactly, which is why this held
+        // for as long as it did. Ranges are the documented syntax, and the
+        // resolver already honours them -- this one comparison did not.
+        for (auto& dep_spec : node.runtime_deps) {
+            std::string dep_base = dep_spec;
+            std::string dep_ver;
+            if (auto at = dep_base.find('@'); at != std::string::npos) {
+                dep_ver = dep_base.substr(at + 1);
+                dep_base.resize(at);
+            }
+            for (auto& depNode : plan.nodes) {
+                bool name_match = (depNode.canonicalName == dep_base
+                                || depNode.name == dep_base
+                                || depNode.rawName == dep_base);
+                if (!name_match
+                    || !detail_::dep_version_matches_(depNode.version,
+                                                      dep_ver)) {
+                    continue;
+                }
+                auto depRoot = depNode.storeRoot.empty()
+                    ? (dataDir / "xpkgs") : depNode.storeRoot;
+                auto depInstallDir = depRoot
+                    / detail_::effective_store_name_(depNode) / depNode.version;
+
+                // Recorded for EVERY runtime dep, declared exports or not.
+                //
+                // This used to `break` here when a dep declared nothing,
+                // throwing away the depInstallDir just computed — and the
+                // consumer then re-derived it from the dep's name, which
+                // is a second answer to a question that has one. With two
+                // versions of a package installed the two answers differ,
+                // and the product is a binary whose interpreter comes from
+                // one payload and whose RUNPATH from another. It faults
+                // before main and blames a GLIBC_PRIVATE symbol.
+                //
+                // Design and the six edge cases the assertion below must
+                // honour:
+                // .agents/docs/2026-08-05-dependency-resolution-single-source.md
+                mcpplibs::xpkg::ResolvedDep r;
+                r.spec        = dep_spec;
+                r.name        = depNode.canonicalName.empty()
+                                    ? depNode.name : depNode.canonicalName;
+                r.version     = depNode.version;
+                r.install_dir = depInstallDir.string();
+                r.source      = dep_ver.empty()            ? "plan-any"
+                              : dep_ver == depNode.version ? "plan-exact"
+                                                           : "plan-range";
+                if (!depNode.exports.libdirs.empty()) {
+                    for (auto& d : depNode.exports.libdirs) {
+                        r.libdirs.push_back((depInstallDir / d).string());
+                    }
+                } else {
+                    // The {lib64, lib} convention, applied HERE and only
+                    // here. It used to be applied by each consumer, which
+                    // is how a convention becomes a second resolver.
+                    for (const auto* sub : {"lib64", "lib"}) {
+                        auto cand = depInstallDir / sub;
+                        if (std::filesystem::is_directory(cand)) {
+                            r.libdirs.push_back(cand.string());
+                            break;
+                        }
+                    }
+                }
+                ctx.resolved_deps[dep_spec] = std::move(r);
+
+                if (depNode.exports.loader.empty() && depNode.exports.libdirs.empty()) {
+                    // Nothing declared: no DepExport entry, by design.
+                    // The resolved record above is what consumers use.
+                    break;
+                }
+                mcpplibs::xpkg::DepExport e;
+                if (!depNode.exports.loader.empty()) {
+                    e.loader = (depInstallDir / depNode.exports.loader).string();
+                }
+                e.abi = depNode.exports.abi;
+                for (auto& d : depNode.exports.libdirs) {
+                    e.libdirs.push_back((depInstallDir / d).string());
+                }
+                ctx.deps_exports[dep_spec] = std::move(e);
+                break;
+            }
+        }
+
+        auto planKey = detail_::plan_key_(node);
+        auto dlIt = downloadResults.find(planKey);
+
+        std::optional<std::filesystem::path> extractedRoot;
+        if (plannedDownloads.contains(planKey) && dlIt == downloadResults.end()) {
+            log::error("download artifact missing for {}", node.name);
+            if (onStatus) {
+                onStatus({ node.name, InstallPhase::Failed, 0.0f, "download artifact missing" });
+            }
+            continue;
+        }
+        // run_dir is the user's working directory (where xlings was invoked),
+        // not the download/runtime directory. Hooks use it for resolving
+        // relative paths and determining project install locations.
+        ctx.run_dir = std::filesystem::current_path();
+
+        if (dlIt != downloadResults.end()) {
+            ctx.install_file = dlIt->second.localFile;
+            if (detail_::is_archive_(dlIt->second.localFile)) {
+                if (onStatus) {
+                    onStatus({ node.name, InstallPhase::Extracting, 0.35f, "" });
+                }
+                // Extract into the same runtime dir as the download
+                auto runtimeDir = dlIt->second.localFile.parent_path();
+                auto extracted = extract_archive_detailed(
+                    dlIt->second.localFile, runtimeDir);
+                if (!extracted) {
+                    auto error = std::move(extracted).error();
+                    if (evict_invalid_archive_cache_(
+                            dlIt->second.localFile, error)) {
+                        log::warn(
+                            "evicted invalid archive cache for {}: {}",
+                            node.name, dlIt->second.localFile.string());
+                    }
+                    log::error("extract failed for {}: {}",
+                               node.name, error.message);
+                    if (onStatus) {
+                        onStatus({
+                            node.name, InstallPhase::Failed, 0.0f,
+                            error.message});
+                    }
+                    continue;
+                }
+                extractedRoot = *extracted;
+            }
+        }
+        // No download artifact: install_file stays empty (type-only packages
+        // like auto-config don't need a payload).  Do NOT fall back to
+        // node.pkgFile — that is the package *definition* file; an install
+        // hook calling os.mv(install_file, install_dir) would move it out
+        // of the package index, destroying the index entry.
+
+        // Ensure install_dir exists so hooks can mv/cp into it
+        {
+            std::error_code ec;
+            std::filesystem::create_directories(ctx.install_dir, ec);
+            // A genuine failure here (commonly EACCES on a root-owned
+            // dir left by a prior `sudo` install) used to be swallowed,
+            // surfacing later as a confusing hook failure. Surface it.
+            if (ec && !std::filesystem::is_directory(ctx.install_dir)) {
+                log::warn("create install dir {} failed: {}",
+                          ctx.install_dir.string(), ec.message());
+            }
+        }
+
+        // A payload that belongs to another platform is not installed,
+        // whatever the records say. Only a PROVABLE mismatch overrides
+        // them: Unknown (scripts, data, a type-only package) keeps the
+        // fast path, so nothing that works today starts reinstalling.
+        const auto payloadVerdict =
+            classify_payload_platform(ctx.install_dir);
+        const bool foreignPayload =
+            payloadVerdict == PayloadPlatform::Foreign;
+        if (foreignPayload) {
+            log::warn("{}: installed payload is not for {} — reinstalling",
+                      node.name, host_platform_tag());
+            log::warn("  payload: {}",
+                      Config::display_path(ctx.install_dir));
+        }
+
+        bool payloadInstalled = node.alreadyInstalled && !foreignPayload;
+
+        // Check if already installed via hook
+        if (foreignPayload) {
+            // The hooks below all answer "is it installed", and every one
+            // of them would say yes about the wrong platform's files.
+        }
+        else if (!payloadInstalled && executor.has_hook(mcpplibs::xpkg::HookType::Installed)) {
+            auto hookResult = executor.check_installed(ctx);
+            if (hookResult.success && !hookResult.version.empty()) {
+                log::debug("{} already installed (version {})",
+                          node.name, hookResult.version);
+                payloadInstalled = true;
+            }
+        }
+        // Default: check xvm version database when no installed hook.
+        //
+        // Trust-but-verify: a DB entry alone isn't enough. If the
+        // payload directory the entry points to is missing or empty
+        // (broken-payload state — payload manually rm'd, partial
+        // uninstall, FS corruption), fall through and let the install
+        // hook re-create the payload.  Without this fall-through,
+        // `xlings install <pkg>@<ver>` reports success without
+        // actually doing anything — the user can never recover from
+        // a broken payload via the obvious command.
+        else if (!payloadInstalled) {
+            auto db = Config::versions();
+            auto resolved = xvm::match_version(db, node.name, node.version);
+            if (!resolved.empty()) {
+                bool payload_ok = true;
+                if (auto* vdata = xvm::get_vdata(db, node.name, resolved);
+                    vdata && !vdata->path.empty()) {
+                    auto expanded = xvm::expand_path(
+                        vdata->path, Config::paths().homeDir.string());
+                    std::error_code ec;
+                    payload_ok = std::filesystem::is_directory(expanded, ec)
+                              && payload_has_content(expanded);
+                }
+                if (payload_ok) {
+                    log::debug("{} already installed in xvm (version {})",
+                              node.name, resolved);
+                    payloadInstalled = true;
+                } else {
+                    log::debug("{} registered as {} in xvm but payload "
+                              "missing — re-running install hook",
+                              node.name, resolved);
+                }
+            }
+        }
+
+        // The one that closes #541 ①.
+        //
+        // Everything above answers "is there a payload here". A hook that
+        // failed halfway leaves one, so every check above says yes and the
+        // hook is never re-run: the repair command's own precondition is
+        // satisfied by the wreckage it exists to clear. `installation_state`
+        // asks whether the payload and the records AGREE, and re-runs the
+        // hook when they do not.
+        //
+        // Positive evidence only -- a stamp that predates the `registered`
+        // field yields no verdict, so a home installed by an older client
+        // does not start reinstalling itself. See install_state.cppm.
+        if (payloadInstalled && !foreignPayload) {
+            const auto state = installation_state(
+                ledgerIndex, node.namespaceName, node.name, node.version,
+                ctx.install_dir);
+            if (state.is_incomplete()) {
+                log::warn("[{}@{}] previous install left an incomplete "
+                          "state ({}); running its install hook again",
+                          node.name, node.version, state.reason);
+                payloadInstalled = false;
+            }
+        }
+
+        // Run install hook
+        if (!payloadInstalled && executor.has_hook(mcpplibs::xpkg::HookType::Install)) {
+            log::debug("installing {}...", node.name);
+            log::debug("installer: install_dir={}", ctx.install_dir.string());
+            // Set cwd to the download/runtime directory so hooks can
+            // find downloaded files via relative paths.  ctx.run_dir
+            // (user's original cwd) is exposed via system.rundir().
+            // When there is no download artifact we fall back to the
+            // runtime dir rather than install_dir: hooks commonly start
+            // with os.tryrm(install_dir) to get a clean slate, which
+            // would delete the CWD and cause subsequent getcwd() calls
+            // to fail.
+            auto hookCwd = (dlIt != downloadResults.end())
+                ? dlIt->second.localFile.parent_path()
+                : detail_::runtime_dir_(node, dataDir); // fallback to runtime dir
+            detail_::ScopedCurrentDir_ installCwd(hookCwd);
+
+            // Inject XLINGS_BUILDDEP_<UPPER>_PATH for every build_dep
+            // declared by this node, and prepend their bin/ dirs to
+            // PATH for the duration of the hook. The hook (and any
+            // subprocess it spawns) sees both forms; xpkg-side
+            // pkginfo.build_dep() picks the env path first.
+            std::string oldPath = std::getenv("PATH") ? std::getenv("PATH") : "";
+            std::vector<std::string> setEnvKeys;
+            std::string newPath = oldPath;
+            for (auto& bd : node.build_deps) {
+                auto bdDir = locate_dep_install_dir_(plan, dataDir, bd);
+                if (bdDir.empty()) {
+                    log::debug("[{}] build_dep '{}' not found in plan",
+                               node.name, bd);
+                    continue;
+                }
+                std::string nameOnly = bd;
+                if (auto a = nameOnly.find('@'); a != std::string::npos)
+                    nameOnly.resize(a);
+                if (auto c = nameOnly.find(':'); c != std::string::npos)
+                    nameOnly = nameOnly.substr(c + 1);
+                std::string upper;
+                upper.reserve(nameOnly.size());
+                for (char c : nameOnly) {
+                    upper += std::isalnum(static_cast<unsigned char>(c))
+                        ? static_cast<char>(std::toupper(static_cast<unsigned char>(c)))
+                        : '_';
+                }
+                auto envKey = "XLINGS_BUILDDEP_" + upper + "_PATH";
+                platform::set_env_variable(envKey, bdDir.string());
+                setEnvKeys.push_back(envKey);
+                auto bdBin = (bdDir / "bin").string();
+                if (std::filesystem::exists(bdDir / "bin")) {
+                    newPath = bdBin + std::string(1, platform::PATH_SEPARATOR) + newPath;
+                }
+                log::debug("[{}] build_dep {} -> {} (env {})",
+                           node.name, bd, bdDir.string(), envKey);
+            }
+            if (!setEnvKeys.empty()) {
+                platform::set_env_variable("PATH", newPath);
+            }
+
+            auto hookResult = executor.run_hook(
+                mcpplibs::xpkg::HookType::Install, ctx);
+
+            // Restore env regardless of hook outcome
+            if (!setEnvKeys.empty()) {
+                platform::set_env_variable("PATH", oldPath);
+                for (auto& k : setEnvKeys) {
+                    platform::set_env_variable(k, "");
+                }
+            }
+
+            if (!hookResult.success) {
+                auto message = detail_::format_hook_failure(
+                    "install", hookResult);
+                // Record the failure ON the payload. Without this the next
+                // `xlings install` finds a non-empty directory, concludes
+                // "already installed", skips the hook, and reports success
+                // -- the state #541 ① calls permanently stuck. The payload
+                // is the only place the next run is guaranteed to look.
+                write_payload_failure_marker(
+                    ctx.install_dir, node.version, message);
+                if (onStatus) {
+                    onStatus({ node.name, InstallPhase::Failed, 0.0f,
+                               std::move(message) });
+                }
+                continue;
+            }
+        } else if (!payloadInstalled && node.pkgType == 1 /* Script */) {
+            log::debug("installing script {}...", node.name);
+            if (!script::default_install(node, ctx)) {
+                if (onStatus) {
+                    onStatus({ node.name, InstallPhase::Failed, 0.0f,
+                               "default script install failed" });
+                }
+                continue;
+            }
+        } else if (!payloadInstalled && node.pkgType == 4 /* Subos */) {
+            log::debug("installing subos base {}...", node.name);
+            if (!subos::default_install(node, ctx)) {
+                if (onStatus) {
+                    onStatus({ node.name, InstallPhase::Failed, 0.0f,
+                               "default subos install failed" });
+                }
+                continue;
+            }
+        }
+
+        if (!payloadInstalled && extractedRoot && !detail_::has_directory_entries_(ctx.install_dir)) {
+            if (!detail_::stage_extracted_payload_(*extractedRoot, ctx.install_dir)) {
+                log::error("failed to stage extracted payload for {}", node.name);
+                write_payload_failure_marker(
+                    ctx.install_dir, node.version,
+                    "failed to stage extracted payload");
+                if (onStatus) {
+                    onStatus({ node.name, InstallPhase::Failed, 0.0f,
+                               "failed to stage extracted payload" });
+                }
+                continue;
+            }
+        }
+
+        if (!payloadInstalled && !detail_::normalize_file_install_(ctx.install_dir)) {
+            log::error("failed to normalize file install layout for {}", node.name);
+            write_payload_failure_marker(
+                ctx.install_dir, node.version,
+                "failed to normalize file install layout");
+            if (onStatus) {
+                onStatus({ node.name, InstallPhase::Failed, 0.0f,
+                           "failed to normalize file install layout" });
+            }
+            continue;
+        }
+
+        // Auto-stamp: drop a `.xim-installed` marker in install_dir if
+        // it's still empty after every install path (hook + extracted-
+        // payload fallback + script default). Wrapper packages
+        // (linux-headers, fromsource:* aliases) legitimately leave
+        // install_dir empty because their real payload lives in a
+        // separately-installed dep — without a stamp, xlings's
+        // installed-probe (`is_directory && !is_empty`) reports
+        // "not installed" and re-runs install + config on every
+        // dependent install. Critical: this MUST come after
+        // stage_extracted_payload_ above; otherwise a stamp written
+        // earlier would falsely make install_dir look "non-empty"
+        // and skip the extracted-payload fallback (which exists for
+        // packages whose hook silently no-ops, e.g. patchelf where
+        // the tarball has no top-level dir).
+        if (!payloadInstalled && node.pkgType != 3 /* Config */) {
+            // TODO(config): formalize config packages as repeatable,
+            // no-install procedures in libxpkg/spec. Keep current hook
+            // semantics for now; just avoid xlings-owned markers that
+            // would make an otherwise empty config directory look
+            // installed.
+            executor.apply_install_stamp_if_empty(ctx);
+        }
+
+        // Record which platform produced this payload. Written on every
+        // path that just installed one, and also when the fast path was
+        // taken and the heuristic had to be consulted -- that second case
+        // is the self-heal: a pre-stamp payload is classified once and
+        // never again.
+        // Record which platform produced this payload -- but ONLY after a
+        // path that actually installed one, and only if the files on disk
+        // agree. Stamping unconditionally is worse than not stamping at
+        // all: an install hook that started with os.tryrm(install_dir) and
+        // then had no artifact to unpack (the shape a foreign payload
+        // reaches here in) would leave an empty directory carrying this
+        // platform's stamp, and every later run would believe it.
+        if (!payloadInstalled && node.pkgType != 3 /* Config */
+            && classify_payload_content(ctx.install_dir)
+                   != PayloadPlatform::Foreign) {
+            write_payload_stamp(ctx.install_dir, node.version);
+        }
+
+        // Apply elfpatch auto-patching if the install hook enabled it
+        if (!payloadInstalled) {
+            // Ensure binDir is in PATH so elfpatch can find patchelf
+            auto binDir = ctx.bin_dir.string();
+            auto curPath = std::string(std::getenv("PATH") ? std::getenv("PATH") : "");
+            if (!binDir.empty() && curPath.find(binDir) == std::string::npos) {
+                platform::set_env_variable("PATH",
+                    binDir + std::string(1, platform::PATH_SEPARATOR) + curPath);
+            }
+            auto epResult = executor.apply_elfpatch_auto();
+            if (epResult.success && !epResult.output.empty()) {
+                log::debug("{}: elfpatch auto: {}", node.name, epResult.output);
+            } else if (!epResult.success) {
+                log::debug("{}: elfpatch auto failed: {}", node.name, epResult.error);
+            }
+
+            // The invariant, checked on what elfpatch actually wrote
+            // rather than on what it was asked to write.
+            //
+            // Everything above is supposed to make a violation
+            // unconstructible. This is the layer that does not take that
+            // on trust — and it is cheap, a string compare per ELF. What
+            // it replaces is a segmentation fault in the user's terminal
+            // days later, reported as an undefined GLIBC_PRIVATE symbol
+            // that names neither a package nor a version.
+            // The decision, kept as data next to what it produced.
+            //
+            // A log line answers "why is it 2.39 here" only for as long
+            // as someone still has the log and the store has not moved
+            // on. Anything that has to be reproduced to be inspected is
+            // not traceable — and reproducing THIS means recreating a
+            // store state, which is the thing that varies.
+            if (!ctx.resolved_deps.empty()) {
+                nlohmann::json rec;
+                rec["package"] = std::format("{}@{}", node.name, node.version);
+                rec["deps"] = nlohmann::json::array();
+                // Sorted, so two installs of the same plan produce the
+                // same bytes and a diff between homes means something.
+                std::vector<std::string> specs;
+                for (const auto& [spec, _] : ctx.resolved_deps)
+                    specs.push_back(spec);
+                std::ranges::sort(specs);
+                for (const auto& spec : specs) {
+                    const auto& r = ctx.resolved_deps.at(spec);
+                    rec["deps"].push_back({
+                        {"spec",        r.spec},
+                        {"name",        r.name},
+                        {"version",     r.version},
+                        {"install_dir", r.install_dir},
+                        {"libdirs",     r.libdirs},
+                        {"source",      r.source},
+                    });
+                }
+                std::error_code wec;
+                if (std::filesystem::is_directory(ctx.install_dir, wec)) {
+                    std::ofstream out(ctx.install_dir / ".xlings-resolution.json");
+                    if (out) out << rec.dump(2) << '\n';
+                }
+            }
+
+            if (auto bad = elfcheck::scan_payload(ctx.install_dir);
+                !bad.empty()) {
+                for (const auto& f : bad) {
+                    log::error("{}", elfcheck::describe(f));
+                }
+                log::error("  this is a resolution defect, not a bad "
+                           "payload -- report it with the two paths above");
+                return std::unexpected(std::format(
+                    "{}@{}: loader/libc payload mismatch in {} binary(ies)",
+                    node.name, node.version, bad.size()));
+            }
+        }
+
+        // Process deferred pkgmanager.install()/remove() requests synchronously
+        // before config hook, so config can access sub-dependencies
+        {
+            auto reqs = executor.install_requests();
+            if (!reqs.empty() && onInstallRequests) {
+                for (auto& req : reqs) {
+                    log::debug("[{}] deferred {}: {}", node.name, req.op, req.target);
+                }
+                onInstallRequests(reqs);
+            }
+        }
+
+        if (node.kind == DepKind::Build) {
+            // Build-only deps: payload is on disk and resolvable via
+            // pkginfo.build_dep() / XLINGS_BUILDDEP_*_PATH. We skip
+            // config hook + xvm operations entirely so the dep does
+            // NOT take over a workspace slot or get a PATH shim.
+            log::debug("[{}] kind=Build: skipping config hook / workspace activation",
+                       node.name);
+        } else if (!executor.has_hook(mcpplibs::xpkg::HookType::Config) && node.pkgType == 1 /* Script */) {
+            if (!script::default_config(
+                    node,
+                    dataDir,
+                    detail_::version_namespace_(node.namespaceName))) {
+                if (onStatus) {
+                    onStatus({ node.name, InstallPhase::Failed, 0.0f,
+                               "default script config failed" });
+                }
+                continue;
+            }
+        } else if (!executor.has_hook(mcpplibs::xpkg::HookType::Config) && node.pkgType == 4 /* Subos */) {
+            if (!subos::default_config(
+                    node,
+                    dataDir,
+                    detail_::version_namespace_(node.namespaceName))) {
+                if (onStatus) {
+                    onStatus({ node.name, InstallPhase::Failed, 0.0f,
+                               "default subos config failed" });
+                }
+                continue;
+            }
+        } else {
+            std::string configFailure;
+            if (!detail_::run_config_hook_(
+                    node, dataDir, executor, ctx, onStatus,
+                    useAfterInstall, &configFailure)) {
+                // Same reason as the install hook above, and this one
+                // matters more: config is where registration happens, so
+                // its failure is exactly "payload on disk, ledger empty" --
+                // the state that used to be indistinguishable from a
+                // package that legitimately registers nothing.
+                write_payload_failure_marker(
+                    ctx.install_dir, node.version, configFailure);
+                if (onStatus) {
+                    onStatus({ node.name, InstallPhase::Failed, 0.0f,
+                               std::move(configFailure) });
+                }
+                continue;
+            }
+        }
+
+        if (node.pkgType != 3 /* Config */) {
+            // TODO(config): same soft policy as the install stamp. A
+            // config package with no author-created payload must not
+            // become installed solely because xlings copied metadata into
+            // install_dir. Future libxpkg/spec work should define the
+            // stricter config contract.
+            if (auto snapshot = detail_::save_xpkg_snapshot_(node.pkgFile, ctx.install_dir);
+                !snapshot) {
+                log::error("failed to save xpkg snapshot for {}: {}",
+                           node.name, snapshot.error());
+                if (onStatus) {
+                    onStatus({ node.name, InstallPhase::Failed, 0.0f,
+                               snapshot.error() });
+                }
+                continue;
+            }
+        }
+
+        // C2, execution point 2 (warn-only): the closure predicate the
+        // index CI enforces, evaluated where the payload actually lands.
+        // mcpp#392 happened on a machine no CI ever saw. Fresh installs
+        // only -- a re-mapped payload was scanned when it first arrived,
+        // and re-scanning a 400MB payload on every dependent install
+        // would price the check out of existence.
+        if (!payloadInstalled && node.pkgType != 3 /* Config */) {
+            const auto rep = closurecheck::scan_payload(
+                ctx.install_dir, dataDir / "xpkgs", host_glibc_recorded());
+            for (const auto& m : rep.missing) {
+                log::warn("[{}@{}] {}", node.name, node.version,
+                          closurecheck::describe_missing(m));
+            }
+            if (rep.floor) {
+                log::warn("[{}@{}] {}", node.name, node.version,
+                          closurecheck::describe_floor(*rep.floor));
+            }
+            if (rep.nonTransitive) {
+                log::warn("[{}@{}] {}", node.name, node.version,
+                          closurecheck::describe_non_transitive(
+                              *rep.nonTransitive));
+            }
+        }
+
+        // Re-stamp with what the install actually REGISTERED.
+        //
+        // The stamp above was written before the config hook ran, because
+        // its other job -- recording which platform produced the payload --
+        // has to happen on the install path. The registration count can
+        // only be known here, after the hook and after xvm accepted (or
+        // silently dropped) what it produced.
+        //
+        // This is the observation that makes a finished install checkable.
+        // Without it, "the run reached the end" and "the run did its work"
+        // are the same output, which is how a stack that wired nothing
+        // reported `installed` on a real home.
+        if (node.pkgType != 3 /* Config */) {
+            const auto registered = count_ledger_registrations(
+                Config::versions(), Config::paths().homeDir.string(),
+                node.namespaceName, node.name, node.version);
+            write_payload_stamp(ctx.install_dir, node.version, registered);
+        }
+
+        if (catalog_) {
+            catalog_->mark_installed(PackageMatch{
+                .rawName = node.rawName,
+                .name = node.name,
+                .version = node.version,
+                .namespaceName = node.namespaceName,
+                .canonicalName = node.canonicalName,
+                .repoName = node.repoName,
+                .pkgFile = node.pkgFile,
+                .storeRoot = node.storeRoot,
+                .scope = node.scope,
+                .installed = true,
+            }, true);
+        } else {
+            index_->mark_installed(node.name, true);
+        }
+
+        if (onStatus) {
+            onStatus({ node.name, InstallPhase::Done, 1.0f,
+                       payloadInstalled ? "already installed" : "" });
+        }
+        if (payloadInstalled) {
+            log::debug("{}@{} mapping to current subos", node.name, node.version);
+        } else {
+            log::debug("{}@{} installed successfully", node.name, node.version);
+        }
+    }
+
+    // Every hook returned success; that is not the same as the packages
+    // being usable. Fail the install rather than let a checkmark stand for
+    // a package that registered none of the programs it promised.
+    if (auto broken = detail_::unfulfilled_program_promises_(plan);
+        !broken.empty()) {
+        for (const auto& name : broken) {
+            if (onStatus) {
+                onStatus({ name, InstallPhase::Failed, 0.0f,
+                           "declared programs were not registered" });
+            }
+        }
+        return std::unexpected(std::format(
+            "{} installed but registered none of its declared programs",
+            broken.front()));
+    }
+
+    return {};
+}
+
+std::expected<Installer::UninstallOutcome, std::string> Installer::uninstall(const std::string& name) {
+    auto platform = detect_platform_();
+    auto currentWorkspacePath = detail_::current_workspace_config_path_();
+
+    auto parse_target = [](std::string target) {
+        auto at = target.find('@');
+        if (at == std::string::npos) return std::pair{target, std::string{}};
+        return std::pair{target.substr(0, at), target.substr(at + 1)};
+    };
+
+    auto [targetName, requestedVersion] = parse_target(name);
+    if (requestedVersion.empty()) {
+        requestedVersion = xvm::get_active_version(Config::effective_workspace(), targetName);
+    }
+    std::string resolvedTarget;
+    if (requestedVersion.empty()) {
+        resolvedTarget = targetName;
+    } else {
+        auto [ns, bareVersion] = xvm::parse_ns_version(requestedVersion);
+        if (ns.empty()) {
+            resolvedTarget = targetName + "@" + bareVersion;
+        } else {
+            resolvedTarget = ns + ":" + targetName + "@" + bareVersion;
+        }
+    }
+
+    std::filesystem::path pkgFile;
+    std::filesystem::path installDir;
+    std::optional<PackageMatch> resolvedMatch;
+
+    if (catalog_) {
+        auto match = catalog_->resolve_target(resolvedTarget, platform);
+        if (!match) return std::unexpected(match.error());
+        resolvedMatch = *match;
+        pkgFile = match->pkgFile;
+        installDir = (match->storeRoot.empty() ? (Config::paths().dataDir / "xpkgs") : match->storeRoot)
+            / detail_::effective_store_name_(*match)
+            / match->version;
+    } else {
+        auto* entry = index_->find_entry(name);
+        if (!entry) {
+            return std::unexpected(std::format("package '{}' not found", name));
+        }
+        pkgFile = entry->path;
+        installDir = Config::paths().dataDir / "xpkgs" / name;
+    }
+
+    auto detachTarget = resolvedMatch ? resolvedMatch->name : targetName;
+    auto detachVersion = resolvedMatch ? resolvedMatch->version : requestedVersion;
+    if (resolvedMatch) {
+        detachVersion = xvm::make_ns_version(
+            detail_::version_namespace_(resolvedMatch->namespaceName),
+            resolvedMatch->version);
+    }
+    auto executingProvider = resolvedMatch
+        ? (resolvedMatch->canonicalName.empty()
+            ? canonical_package_name(
+                resolvedMatch->namespaceName,
+                resolvedMatch->name)
+            : resolvedMatch->canonicalName)
+        : targetName;
+    auto executingProviderVersion = resolvedMatch
+        ? resolvedMatch->version
+        : xvm::strip_namespace(detachVersion);
+
+    auto removalSnapshot = snapshot_xpkg_removal_context(
+        Config::versions_mut(), Config::workspace(), {},
+        executingProvider, executingProviderVersion,
+        detachTarget, detachVersion);
+
+    // Removing a package that registered no version is a NO-OP, not a
+    // failure (openxlings/xlings#506).
+    //
+    // The old code failed here with
+    //
+    //   xvm removal selection failed for local:gcc@15.1.0:
+    //   exact removal version is not registered (target='gcc', ...)
+    //
+    // and returned before the recipe's `uninstall()` hook could run -- so the
+    // package could be installed but never removed, and its own cleanup never
+    // executed.
+    //
+    // The asymmetry is the argument: the package registered no version at
+    // INSTALL time and install succeeded. Failing removal over the same fact
+    // punishes a shape the installer already accepted. `type = "config"` and
+    // `type = "script"` recipes are in that state by design.
+    //
+    // Narrow deliberately: only VersionNotFound, and only when the executing
+    // provider owns no version for this target. A mismatched version owned by
+    // this provider still fails loudly; another provider's version neither
+    // blocks this hook nor enters its removal selection.
+    xvm::RemovalContext removalContext;
+    if (removalSnapshot) {
+        removalContext = std::move(*removalSnapshot);
+    } else if (removalSnapshot.error().kind
+                   == xvm::RemovalErrorKind::VersionNotFound
+               && detail_::executing_provider_owns_no_version(
+                      Config::versions_mut(), detachTarget,
+                      executingProvider)) {
+        log::info("{}: registers no xvm version; running its uninstall hook "
+                  "and removing the payload",
+                  executingProvider);
+    } else {
+        return std::unexpected(std::format(
+            "xvm removal selection failed for {}@{}: {} "
+            "(target='{}', version='{}')",
+            executingProvider, executingProviderVersion,
+            removalSnapshot.error().message,
+            removalSnapshot.error().target,
+            removalSnapshot.error().version));
+    }
+    if (auto memberIt = removalContext.members.find(detachTarget);
+        memberIt != removalContext.members.end()) {
+        detachVersion = memberIt->second;
+    }
+
+    auto stillReferenced = !detachVersion.empty()
+        && detail_::is_version_referenced_anywhere_(
+            resolvedMatch ? resolvedMatch->scope : PackageScope::Global,
+            detachTarget,
+            detachVersion,
+            currentWorkspacePath);
+
+    if (stillReferenced) {
+        detail_::detach_current_subos_(detachTarget, detachVersion);
+        log::debug("{}@{} detached from current subos; payload retained",
+                  detachTarget, detachVersion);
+        // Reported, not just logged at debug: this is the branch whose
+        // silence made a no-op look like a removal (#443).
+        return UninstallOutcome{
+            .detachedOnly = true,
+            .target       = detachTarget,
+            .version      = detachVersion,
+        };
+    }
+
+    auto executorPkgFile = detail_::uninstall_xpkg_file_(pkgFile, installDir);
+    if (executorPkgFile != pkgFile) {
+        log::debug("using xpkg snapshot for uninstall: {}", executorPkgFile.string());
+    }
+
+    auto execResult = mcpplibs::xpkg::create_executor(executorPkgFile);
+    if (!execResult) {
+        return std::unexpected(execResult.error());
+    }
+
+    auto& executor = *execResult;
+    executor.set_log_level(std::string(log::level_string()));
+
+    mcpplibs::xpkg::ExecutionContext ctx;
+    ctx.pkg_name = resolvedMatch ? resolvedMatch->name : name;
+    ctx.version = resolvedMatch ? resolvedMatch->version : std::string{};
+    ctx.platform = platform;
+    const auto artifactSubosDir =
+        detail_::configure_xpkg_execution_artifact_paths_(
+            ctx);
+    auto selectedStore = resolvedMatch
+        ? (resolvedMatch->storeRoot.empty()
+            ? Config::paths().dataDir / "xpkgs"
+            : resolvedMatch->storeRoot)
+        : Config::paths().dataDir / "xpkgs";
+    detail_::configure_dependency_store_roots_(ctx, selectedStore);
+    ctx.install_dir = installDir;
+    ctx.xpkg_dir = pkgFile.parent_path();
+    ctx.pkgindex_dir = detail_::pkgindex_root_for_(pkgFile);
+
+    bool useDefaultRemoval = false;
+    if (executor.has_hook(mcpplibs::xpkg::HookType::Uninstall)) {
+        log::debug("uninstalling {}...", name);
+        auto result = executor.run_hook(
+            mcpplibs::xpkg::HookType::Uninstall, ctx);
+        if (!result.success) {
+            return std::unexpected(
+                detail_::format_hook_failure("uninstall", result));
+        }
+    } else {
+        // Check if this is a script-type or subos-type package and run default uninstall
+        bool isScriptType = false;
+        bool isSubosType  = false;
+        if (catalog_ && resolvedMatch) {
+            auto pkg = catalog_->load_package(*resolvedMatch);
+            if (pkg) {
+                isScriptType = (pkg->type == mcpplibs::xpkg::PackageType::Script);
+                isSubosType  = (pkg->type == mcpplibs::xpkg::PackageType::Subos);
+            }
+        } else if (index_) {
+            auto* entry = index_->find_entry(targetName);
+            if (entry) {
+                isScriptType = (entry->type == mcpplibs::xpkg::PackageType::Script);
+                isSubosType  = (entry->type == mcpplibs::xpkg::PackageType::Subos);
+            }
+        }
+        useDefaultRemoval = isScriptType || isSubosType;
+    }
+
+    // Process xvm operations collected by uninstall hook
+    auto xvm_ops = executor.xvm_operations();
+    if (useDefaultRemoval) {
+        xvm_ops.push_back({
+            .op = "remove",
+            .name = detachTarget,
+            .version = detachVersion,
+        });
+    }
+    auto sysroot_include =
+        artifactSubosDir / "usr" / "include";
+
+    const auto dbBeforeRemoval = Config::versions_mut();
+    auto removalResult = apply_xpkg_removal_operations(
+        Config::versions_mut(),
+        Config::workspace_mut(),
+        Config::workspace_installed_mut(),
+        xvm_ops,
+        removalContext,
+        xvm::RemovalBatchOptions{
+            .purgeSelection = true,
+        });
+    if (!removalResult) {
+        return std::unexpected(std::format(
+            "xvm removal batch failed for {}@{}: {} "
+            "(target='{}', version='{}')",
+            executingProvider, executingProviderVersion,
+            removalResult.error().message,
+            removalResult.error().target,
+            removalResult.error().version));
+    }
+
+    // Drop this package's subos env section. Keyed by binding, so it takes
+    // exactly what the package added and leaves every other provider's
+    // alone -- the recipe's uninstall() writes nothing for this.
+    //
+    // Matched by package *name* rather than the exact binding: the removal
+    // above resolves versions through namespaces and group members, so the
+    // binding recorded at install time is not reliably reconstructible
+    // here. A home that installed two versions of the same package can
+    // hold a section for each, and leaving the other one behind would
+    // point a driver search at a payload that is being deleted.
+    {
+        namespace mf = xlings::subos::manifest;
+        if (auto doc = mf::read_document(artifactSubosDir)) {
+            bool changed = false;
+            for (const auto& binding :
+                     mf::providers_named(*doc, executingProvider)) {
+                changed |= mf::remove_provider(*doc, binding);
+            }
+            // providers_named matches the bare name; a namespaced install
+            // records the canonical one, so ask again under it.
+            if (executingProvider != detachTarget) {
+                for (const auto& binding :
+                         mf::providers_named(*doc, detachTarget)) {
+                    changed |= mf::remove_provider(*doc, binding);
+                }
+            }
+            if (changed) {
+                try {
+                    platform::write_string_to_file(
+                        mf::config_path(artifactSubosDir).string(),
+                        doc->dump(2));
+                } catch (const std::exception& e) {
+                    // Not fatal to the uninstall -- the payload is already
+                    // going -- but it must be said. A stale section points
+                    // at a directory that no longer exists, which doctor
+                    // D2/D3 will report.
+                    log::warn("[xim] could not clear subos env "
+                              "declarations for {}: {}",
+                              executingProvider, e.what());
+                }
+            }
+        }
+    }
+
+    for (const auto& op : xvm_ops) {
+        if (op.op == "remove_headers") {
+            xvm::remove_headers(op.includedir, sysroot_include);
+        }
+    }
+
+    bool detachedByBatch = false;
+    for (const auto& removed : removalResult->removed) {
+        if (removed.target == detachTarget
+            && removed.version == detachVersion) {
+            detachedByBatch = true;
+        }
+    }
+    cleanup_removed_xvm_library_artifacts(
+        artifactSubosDir / "lib",
+        dbBeforeRemoval,
+        Config::versions_mut(),
+        *removalResult);
+    cleanup_removed_xvm_program_artifacts(
+        artifactSubosDir / "bin",
+        dbBeforeRemoval,
+        Config::versions_mut(),
+        Config::workspace_installed(),
+        *removalResult);
+    if (!detachedByBatch && !detachVersion.empty()) {
+        detail_::detach_current_subos_(
+            detachTarget, detachVersion, false);
+    }
+
+    Config::save_versions();
+    Config::save_workspace();
+
+    if (catalog_) {
+        catalog_->mark_installed(*resolvedMatch, false);
+    } else {
+        index_->mark_installed(name, false);
+    }
+    std::error_code ec;
+    std::filesystem::remove_all(installDir, ec);
+    if (ec) {
+        log::warn("failed to remove payload dir {}: {}", installDir.string(), ec.message());
+    }
+
+    // installDir is the version directory (e.g. .../xim-x-node/22.17.1).
+    // Its parent is the per-package directory (.../xim-x-node) which
+    // holds one subdirectory per installed version of the same package.
+    // After we delete the version we just uninstalled, the package
+    // directory may be left as an empty stub if this was its last
+    // version — sweep it.
+    //
+    // Why "list-then-remove" instead of "remove and tolerate ENOTEMPTY":
+    // fs::remove (non-recursive) silently returns false for non-empty
+    // directories, which would conflate the "still has versions, leave
+    // it alone" expected case with real errors (permission denied, IO
+    // failure). It is also a maintenance trap — the next reader can
+    // upgrade it to fs::remove_all and wipe sibling versions. So check
+    // emptiness explicitly first.
+    //
+    // Cross-platform: directory_iterator and fs::remove are part of
+    // std::filesystem and behave identically on Linux/macOS/Windows
+    // for the cases we care about (empty dir → end iterator; remove of
+    // an empty directory → succeeds; non-existent or unreadable parent
+    // → ec set, we skip). One platform-specific edge case worth naming:
+    // file managers occasionally drop hidden metadata into the dir
+    // (.DS_Store on macOS, Thumbs.db on Windows). Those count as
+    // non-empty, so we will leave the package directory alone — that
+    // is the right behavior; never silently delete files we did not
+    // create.
+    auto parent = installDir.parent_path();
+    std::error_code listEc;
+    auto first = std::filesystem::directory_iterator(parent, listEc);
+    if (!listEc && first == std::default_sentinel) {
+        std::error_code rmEc;
+        if (std::filesystem::remove(parent, rmEc)) {
+            log::debug("swept empty package dir: {}", parent.string());
+        } else if (rmEc) {
+            log::warn("failed to sweep empty package dir {}: {}",
+                      parent.string(), rmEc.message());
+        }
+    }
+
+    log::debug("{} uninstalled", resolvedTarget);
+    return UninstallOutcome{
+        .detachedOnly = false,
+        .target       = detachTarget,
+        .version      = detachVersion,
+    };
+}
+
+std::string Installer::detect_platform_() {
+    #if defined(__linux__)
+        return "linux";
+    #elif defined(__APPLE__)
+        return "macosx";
+    #elif defined(_WIN32)
+        return "windows";
+    #else
+        return "unknown";
+    #endif
+}
+
+} // namespace xlings::xim
diff --git a/src/core/xim/installer.cppm b/src/core/xim/installer.cppm
index 4bfb3934..26c1ca82 100644
--- a/src/core/xim/installer.cppm
+++ b/src/core/xim/installer.cppm
@@ -21,8 +21,6 @@ import xlings.core.semver;
 import xlings.core.entry_binary;
 import xlings.core.elf_same_source;
 import xlings.core.closure_check;
-import xlings.libs.json;
-import xlings.core.common;
 import xlings.core.xself;
 import xlings.core.xvm.types;
 import xlings.core.xvm.db;
@@ -112,89 +110,13 @@ struct XpkgSpecSupport {
 // Absent is V1: the field predates being meaningful and "" has always meant
 // V1. Unreadable is refused rather than assumed -- a value we cannot parse
 // (say a future "2.1") is precisely the case where guessing is unsafe.
-XpkgSpecSupport xpkg_spec_support(std::string_view spec) {
-    if (spec.empty()) return {.supported = true, .declared = 1};
-    int value = 0;
-    const auto* first = spec.data();
-    const auto* last  = spec.data() + spec.size();
-    auto [ptr, ec] = std::from_chars(first, last, value);
-    if (ec != std::errc{} || ptr != last || value < 1) {
-        return {.supported = false, .declared = 0};
-    }
-    return {.supported = value <= max_supported_xpkg_spec, .declared = value};
-}
+XpkgSpecSupport xpkg_spec_support(std::string_view spec);
 
 std::optional<XpkgResolvedFilesystemEffect>
 resolve_xpkg_filesystem_effect(
         const xvm::VersionDB& db,
         const xvm::Workspace& workspace,
-        const XpkgFilesystemEffect& effect) {
-    XpkgResolvedFilesystemEffect resolved{
-        .kind = effect.kind,
-        .target = effect.target,
-        .version = effect.version,
-        .sourceDir = effect.sourceDir,
-    };
-    if (effect.kind == XpkgFilesystemEffectKind::InstallHeaders
-        || effect.kind == XpkgFilesystemEffectKind::RemoveHeaders) {
-        // Headers have no program payload to resolve, but they do have an
-        // owner, and whether that owner is the active version decides
-        // whether these headers belong in the sysroot right now.
-        if (!effect.target.empty()) {
-            auto headerActiveIt = workspace.find(effect.target);
-            resolved.active = headerActiveIt != workspace.end()
-                && headerActiveIt->second == effect.version;
-        } else {
-            // No owner recorded (older plan shape): keep the previous
-            // unconditional behavior rather than silently skipping.
-            resolved.active = true;
-        }
-        return resolved;
-    }
-
-    auto targetIt = db.find(effect.target);
-    if (targetIt == db.end()) return std::nullopt;
-    auto versionIt =
-        targetIt->second.versions.find(effect.version);
-    if (versionIt == targetIt->second.versions.end()) {
-        return std::nullopt;
-    }
-    const auto& data = versionIt->second;
-    const auto kind =
-        data.kind.empty() ? targetIt->second.type : data.kind;
-    // Three kinds, not two. This read `program` or else `lib`, which meant a
-    // FileAsset effect was compared against "lib" and could never match an
-    // entry registered as "files" -- so every declared file asset resolved to
-    // nullopt, the caller logged "validated xvm effect target disappeared or
-    // changed kind", and the FileAsset branch below was dead code. The assets
-    // still landed, because the activation pass places them separately, so
-    // the only visible symptom was a warning on a correct install. It stayed
-    // hidden until a real recipe declared one.
-    const auto expectedKind =
-        effect.kind == XpkgFilesystemEffectKind::ProgramShim
-            ? std::string_view{"program"}
-        : effect.kind == XpkgFilesystemEffectKind::FileAsset
-            ? std::string_view{"files"}
-            : std::string_view{"lib"};
-    if (kind != expectedKind) return std::nullopt;
-
-    resolved.path = data.path;
-    resolved.sourceName = !data.sourceName.empty()
-        ? data.sourceName
-        : (!targetIt->second.filename.empty()
-            ? targetIt->second.filename
-            : effect.target);
-    resolved.destinationName = !data.destinationName.empty()
-        ? data.destinationName
-        : (effect.kind == XpkgFilesystemEffectKind::ProgramShim
-            ? effect.target
-            : resolved.sourceName);
-    auto activeIt = workspace.find(effect.target);
-    resolved.active =
-        activeIt != workspace.end()
-        && activeIt->second == effect.version;
-    return resolved;
-}
+        const XpkgFilesystemEffect& effect);
 
 using XpkgXvmMetadataError = std::variant<
     xvm::RemovalError,
@@ -236,25 +158,7 @@ std::size_t attach_legacy_header_dir(
         xvm::VersionDB& db,
         const std::string& target,
         const std::string& version,
-        const std::vector<XpkgFilesystemEffect>& effects) {
-    const std::string* sourceDir = nullptr;
-    for (const auto& effect : effects) {
-        // Last one wins, matching how the installer used to assign per op.
-        if (effect.kind == XpkgFilesystemEffectKind::InstallHeaders
-            && !effect.sourceDir.empty()) {
-            sourceDir = &effect.sourceDir;
-        }
-    }
-    if (!sourceDir) return 0;
-
-    auto targetIt = db.find(target);
-    if (targetIt == db.end()) return 0;
-    auto versionIt = targetIt->second.versions.find(version);
-    if (versionIt == targetIt->second.versions.end()) return 0;
-
-    versionIt->second.includedir = *sourceDir;
-    return 1;
-}
+        const std::vector<XpkgFilesystemEffect>& effects);
 
 std::expected<XpkgRegistrationPlan, XpkgRegistrationError>
 normalize_xpkg_registration_plan(
@@ -262,216 +166,7 @@ normalize_xpkg_registration_plan(
         const std::vector<mcpplibs::xpkg::XvmOp>& operations,
         const std::string& versionNamespace,
         const std::filesystem::path& dataDir,
-        bool useAfterInstall) {
-    auto normalizeVersion = [&](
-            const std::string& version,
-            std::size_t operationIndex,
-            const std::string& target)
-        -> std::expected<std::string, XpkgRegistrationError> {
-        if (version.empty()) {
-            return std::unexpected(XpkgRegistrationError{
-                .kind = XpkgRegistrationErrorKind::InvalidVersion,
-                .operationIndex = operationIndex,
-                .target = target,
-                .version = version,
-                .message = "xvm registration version is empty",
-            });
-        }
-        const auto separator = version.find(':');
-        if (separator == std::string::npos) {
-            return xvm::make_ns_version(versionNamespace, version);
-        }
-        const auto actualNamespace = version.substr(0, separator);
-        const auto bareVersion = version.substr(separator + 1);
-        if (actualNamespace.empty()
-            || bareVersion.empty()
-            || bareVersion.contains(':')
-            || actualNamespace != versionNamespace) {
-            return std::unexpected(XpkgRegistrationError{
-                .kind = XpkgRegistrationErrorKind::InvalidVersion,
-                .operationIndex = operationIndex,
-                .target = target,
-                .version = version,
-                .message = std::format(
-                    "xvm registration version namespace '{}' "
-                    "does not match expected namespace '{}'",
-                    actualNamespace, versionNamespace),
-            });
-        }
-        return version;
-    };
-    const auto fallbackPath =
-        (node.storeRoot.empty() ? dataDir / "xpkgs" : node.storeRoot)
-        / package_store_name(node.namespaceName, node.name)
-        / node.version;
-    XpkgRegistrationPlan plan{
-        .batch = {
-            .provider = node.canonicalName.empty()
-                ? canonical_package_name(node.namespaceName, node.name)
-                : node.canonicalName,
-            .providerVersion = node.version,
-            // Owner hint for headers that do not name a group. Recipes
-            // conventionally register a target under the package's own name,
-            // so that target identifies which group the package's headers
-            // belong to when several groups exist.
-            .primaryTarget = node.name,
-            .useAfterInstall = useAfterInstall,
-        },
-    };
-
-    for (std::size_t index = 0; index < operations.size(); ++index) {
-        const auto& operation = operations[index];
-        if (operation.op == "headers") {
-            plan.batch.headers.push_back({
-                .sourceDir = operation.includedir,
-            });
-            // Carry the owning target and version so materialization can be
-            // gated on the version actually becoming active. Installing a
-            // version that does not become active used to copy its headers
-            // into the sysroot anyway, leaving the active release's headers
-            // overwritten by an inactive one.
-            plan.effects.push_back({
-                .kind = XpkgFilesystemEffectKind::InstallHeaders,
-                .target = node.name,
-                .version = xvm::make_ns_version(versionNamespace, node.version),
-                .sourceDir = operation.includedir,
-            });
-            continue;
-        }
-        if (operation.op == "remove_headers") {
-            plan.effects.push_back({
-                .kind = XpkgFilesystemEffectKind::RemoveHeaders,
-                .sourceDir = operation.includedir,
-            });
-            continue;
-        }
-        if (operation.op != "add") continue;
-        const auto rawVersion = operation.version.empty()
-            ? node.version
-            : operation.version;
-        const auto kind =
-            operation.type.empty() ? std::string{"program"} : operation.type;
-        // A `files` asset names no artifact to dispatch, so it carries no
-        // source or destination *name* -- what it carries is a src/dst pair,
-        // below. Treating it like a program would invent a sourceName from
-        // the target and then look for an executable that does not exist.
-        const auto namesAnArtifact = kind != "group" && kind != "files";
-        const auto sourceName = namesAnArtifact
-            ? (operation.filename.empty()
-                ? operation.name
-                : operation.filename)
-            : std::string{};
-        xvm::RegistrationNode registrationNode{
-            .target = operation.name,
-            .version = {},
-            .path = operation.bindir.empty()
-                ? fallbackPath.string()
-                : operation.bindir,
-            .kind = kind,
-            .sourceName = sourceName,
-            .destinationName = namesAnArtifact
-                ? (kind == "program" ? operation.name : sourceName)
-                : std::string{},
-            .fileSrc = kind == "files" ? operation.src : std::string{},
-            .fileDst = kind == "files" ? operation.dst : std::string{},
-        };
-        auto exactVersion =
-            normalizeVersion(rawVersion, index, operation.name);
-        if (!exactVersion) {
-            return std::unexpected(std::move(exactVersion.error()));
-        }
-        registrationNode.version = std::move(*exactVersion);
-        // Is there a command behind this name, or is it a pure anchor?
-        //
-        // The registration layer cannot ask -- it never touches the
-        // filesystem -- and nothing else in the record distinguishes the two:
-        // an anchor registered with no bindir still gets the package install
-        // dir as its `path`, still defaults to kind "program", and still has a
-        // sourceName derived from its own target. The payload has run by the
-        // time config() does, so the file either is there or it is not, and
-        // this is the layer that can look.
-        //
-        // Same helper the shim dispatches through, so "registration thinks
-        // there is a program here" and "the shim finds one" cannot disagree.
-        // An alias-mode entry runs something else by definition and is
-        // runnable regardless.
-        // `operation.alias`, not `registrationNode.alias`: the latter is
-        // filled in further down and is still empty here.
-        if (kind == "program" && operation.alias.empty()) {
-            registrationNode.runnable = !xvm::resolve_executable(
-                sourceName.empty() ? operation.name : sourceName,
-                registrationNode.path,
-                Config::paths().homeDir.string()).empty();
-        }
-        // Stored verbatim. The core does not rewrite what a recipe wrote --
-        // it only expands its OWN marker at execution time
-        // (kSubosPlaceholder). A recipe that needs the active subos writes
-        // the marker; one that writes a concrete subos path gets the legacy
-        // treatment (normalize_subos_paths at dispatch) and a doctor finding
-        // telling it so.
-        if (!operation.alias.empty()) {
-            registrationNode.alias.push_back(operation.alias);
-        }
-        for (const auto& [key, value] : operation.envs) {
-            auto [environmentIt, inserted] =
-                registrationNode.envs.emplace(key, value);
-            if (!inserted && environmentIt->second != value) {
-                return std::unexpected(XpkgRegistrationError{
-                    .kind = XpkgRegistrationErrorKind::ConflictingEnvironment,
-                    .operationIndex = index,
-                    .target = operation.name,
-                    .version = key,
-                    .message = std::format(
-                        "xvm registration environment '{}' has "
-                        "conflicting values",
-                        key),
-                });
-            }
-        }
-        if (!operation.binding.empty()) {
-            const auto separator = operation.binding.find('@');
-            if (separator == std::string::npos
-                || separator == 0
-                || separator + 1 == operation.binding.size()
-                || operation.binding.find('@', separator + 1)
-                    != std::string::npos) {
-                return std::unexpected(XpkgRegistrationError{
-                    .kind = XpkgRegistrationErrorKind::InvalidBinding,
-                    .operationIndex = index,
-                    .target = operation.name,
-                    .version = operation.binding,
-                    .message =
-                        "xvm registration binding must be '<root>@<version>'",
-                });
-            }
-            const auto rootTarget =
-                operation.binding.substr(0, separator);
-            auto rootVersion = normalizeVersion(
-                operation.binding.substr(separator + 1),
-                index, rootTarget);
-            if (!rootVersion) {
-                return std::unexpected(std::move(rootVersion.error()));
-            }
-            registrationNode.binding = xvm::RegistrationBinding{
-                .rootTarget = rootTarget,
-                .rootVersion = std::move(*rootVersion),
-            };
-        }
-        if (kind == "program" || kind == "lib" || kind == "files") {
-            plan.effects.push_back({
-                .kind = kind == "program"
-                    ? XpkgFilesystemEffectKind::ProgramShim
-                    : (kind == "lib"
-                        ? XpkgFilesystemEffectKind::Library
-                        : XpkgFilesystemEffectKind::FileAsset),
-                .target = operation.name,
-                .version = registrationNode.version,
-            });
-        }
-        plan.batch.nodes.push_back(std::move(registrationNode));
-    }
-    return plan;
-}
+        bool useAfterInstall);
 
 std::expected<xvm::RemovalContext, xvm::RemovalError>
 snapshot_xpkg_removal_context(
@@ -481,153 +176,7 @@ snapshot_xpkg_removal_context(
         const std::string& executingProvider,
         const std::string& executingProviderVersion,
         const std::string& preferredTarget = {},
-        const std::string& preferredVersion = {}) {
-    xvm::RemovalContext legacyContext;
-    std::optional<xvm::RemovalContext> providerContext;
-    std::set<std::pair<std::string, std::string>> seeds;
-
-    auto mergeSeed = [&](const std::string& target,
-                         const std::string& version)
-        -> std::expected<void, xvm::RemovalError> {
-        if (target.empty() || version.empty()
-            || !seeds.emplace(target, version).second) {
-            return {};
-        }
-        auto exactVersion =
-            xvm::resolve_exact_version_key(db, target, version);
-        if (!exactVersion) {
-            return std::unexpected(std::move(exactVersion.error()));
-        }
-        const auto& info = db.at(target);
-        const auto& data = info.versions.at(*exactVersion);
-        const auto hasOutgoingEdge = std::ranges::any_of(
-            info.bindings,
-            [&](const auto& peer) {
-                return peer.second.contains(*exactVersion);
-            });
-        const auto hasIncomingEdge = std::ranges::any_of(
-            db,
-            [&](const auto& peer) {
-                auto edgeIt = peer.second.bindings.find(target);
-                if (edgeIt == peer.second.bindings.end()) return false;
-                return std::ranges::any_of(
-                    edgeIt->second,
-                    [&](const auto& edge) {
-                        return edge.second == *exactVersion;
-                    });
-            });
-        const auto isUnboundLegacySingleton =
-            !data.bindingGroup
-            && !data.bindingMembersDeclared
-            && data.bindingMembers.empty()
-            && !data.bindingHeadersDeclared
-            && data.bindingHeaders.empty()
-            && data.bindingIntegrityIssues.empty()
-            && !hasOutgoingEdge
-            && !hasIncomingEdge;
-        if (isUnboundLegacySingleton) {
-            auto [it, inserted] =
-                legacyContext.members.emplace(target, *exactVersion);
-            if (!inserted && it->second != *exactVersion) {
-                return std::unexpected(xvm::RemovalError{
-                    .kind = xvm::RemovalErrorKind::SelectionInvalid,
-                    .target = target,
-                    .version = *exactVersion,
-                    .message =
-                        "legacy removal selections conflict on target version",
-                });
-            }
-            legacyContext.hasSelection = true;
-            return {};
-        }
-        auto selection =
-            xvm::snapshot_removal_context(db, target, *exactVersion);
-        if (!selection) {
-            return std::unexpected(std::move(selection.error()));
-        }
-        if (!selection->provider.empty()) {
-            if (!executingProvider.empty()
-                && selection->provider != executingProvider) {
-                return std::unexpected(xvm::RemovalError{
-                    .kind = xvm::RemovalErrorKind::ProviderMismatch,
-                    .target = target,
-                    .version = version,
-                    .message = std::format(
-                        "selected version is owned by provider '{}', not '{}'",
-                        selection->provider, executingProvider),
-                });
-            }
-            if (!providerContext) {
-                providerContext = std::move(*selection);
-            }
-            return {};
-        }
-        if (providerContext) return {};
-
-        for (const auto& [memberTarget, memberVersion] :
-             selection->members) {
-            auto [it, inserted] =
-                legacyContext.members.emplace(memberTarget, memberVersion);
-            if (!inserted && it->second != memberVersion) {
-                return std::unexpected(xvm::RemovalError{
-                    .kind = xvm::RemovalErrorKind::SelectionInvalid,
-                    .target = memberTarget,
-                    .version = memberVersion,
-                    .message =
-                        "legacy removal selections conflict on target version",
-                });
-            }
-        }
-        legacyContext.hasSelection = true;
-        return {};
-    };
-
-    if (!preferredTarget.empty() && db.contains(preferredTarget)) {
-        auto merged = mergeSeed(preferredTarget, preferredVersion);
-        if (!merged) return std::unexpected(std::move(merged.error()));
-    }
-
-    for (const auto& operation : operations) {
-        if (operation.op != "remove") continue;
-        std::string version = operation.version;
-        if (version.empty()) {
-            auto activeIt = workspace.find(operation.name);
-            if (activeIt != workspace.end()) {
-                version = activeIt->second;
-            }
-        }
-        if (version.empty() || !db.contains(operation.name)) continue;
-        auto merged = mergeSeed(operation.name, version);
-        if (!merged) return std::unexpected(std::move(merged.error()));
-    }
-
-    if (!providerContext
-        && !legacyContext.hasSelection
-        && !executingProvider.empty()
-        && !executingProviderVersion.empty()) {
-        bool foundProviderRelease = false;
-        for (const auto& [target, info] : db) {
-            for (const auto& [version, data] : info.versions) {
-                if (!data.bindingGroup
-                    || data.bindingGroup->provider != executingProvider
-                    || data.bindingGroup->providerVersion
-                        != executingProviderVersion) {
-                    continue;
-                }
-                foundProviderRelease = true;
-                auto merged = mergeSeed(target, version);
-                if (!merged) {
-                    return std::unexpected(std::move(merged.error()));
-                }
-                break;
-            }
-            if (foundProviderRelease) break;
-        }
-    }
-
-    if (providerContext) return std::move(*providerContext);
-    return legacyContext;
-}
+        const std::string& preferredVersion = {});
 
 std::expected<xvm::RemovalBatchResult, xvm::RemovalError>
 apply_xpkg_removal_operations(
@@ -636,21 +185,7 @@ apply_xpkg_removal_operations(
         xvm::WorkspaceInstalled& installed,
         const std::vector<mcpplibs::xpkg::XvmOp>& operations,
         const xvm::RemovalContext& context,
-        const xvm::RemovalBatchOptions& options = {}) {
-    std::vector<xvm::RemovalOperation> removals;
-    for (const auto& operation : operations) {
-        if (operation.op != "remove" && operation.op != "remove_all") {
-            continue;
-        }
-        removals.push_back({
-            .op = operation.op,
-            .name = operation.name,
-            .version = operation.version,
-        });
-    }
-    return xvm::apply_removal_batch(
-        db, workspace, installed, removals, context, options);
-}
+        const xvm::RemovalBatchOptions& options = {});
 
 std::expected<XpkgXvmMetadataResult, XpkgXvmMetadataError>
 apply_xpkg_xvm_metadata_batch(
@@ -660,212 +195,30 @@ apply_xpkg_xvm_metadata_batch(
         const std::vector<mcpplibs::xpkg::XvmOp>& operations,
         const xvm::RemovalContext& removalContext,
         const XpkgRegistrationPlan& registration,
-        const xvm::RemovalBatchOptions& removalOptions = {}) {
-    auto candidateDb = db;
-    auto candidateWorkspace = workspace;
-    auto candidateInstalled = installed;
-
-    auto removal = apply_xpkg_removal_operations(
-        candidateDb,
-        candidateWorkspace,
-        candidateInstalled,
-        operations,
-        removalContext,
-        removalOptions);
-    if (!removal) {
-        return std::unexpected(XpkgXvmMetadataError{
-            std::in_place_type<xvm::RemovalError>,
-            std::move(removal.error()),
-        });
-    }
-
-    std::vector<xvm::RegisteredMember> registered;
-    std::vector<xvm::DetachedLegacyMember> detachedLegacy;
-    if (!registration.batch.nodes.empty()
-        || !registration.batch.headers.empty()) {
-        auto registrationResult = xvm::apply_registration_batch(
-            candidateDb,
-            candidateWorkspace,
-            candidateInstalled,
-            registration.batch,
-            &detachedLegacy);
-        if (!registrationResult) {
-            return std::unexpected(XpkgXvmMetadataError{
-                std::in_place_type<xvm::RegistrationError>,
-                std::move(registrationResult.error()),
-            });
-        }
-        registered = std::move(*registrationResult);
-    }
-
-    db.swap(candidateDb);
-    workspace.swap(candidateWorkspace);
-    installed.swap(candidateInstalled);
-    return XpkgXvmMetadataResult{
-        .removal = std::move(*removal),
-        .registered = std::move(registered),
-        .detachedLegacy = std::move(detachedLegacy),
-        .effects = registration.effects,
-    };
-}
+        const xvm::RemovalBatchOptions& removalOptions = {});
 
 void cleanup_removed_xvm_library_artifacts(
         const std::filesystem::path& libDir,
         const xvm::VersionDB& dbBeforeRemoval,
         const xvm::VersionDB& currentDb,
-        const xvm::RemovalBatchResult& removalResult) {
-    auto destinationName = [](
-            const std::string& target,
-            const xvm::VInfo& info,
-            const xvm::VData& data) {
-        if (!data.destinationName.empty()) {
-            return data.destinationName;
-        }
-        if (!info.filename.empty()) return info.filename;
-        return target;
-    };
-
-    std::set<std::string> destinations;
-    for (const auto& removed : removalResult.removed) {
-        auto targetIt = dbBeforeRemoval.find(removed.target);
-        if (targetIt == dbBeforeRemoval.end()) continue;
-        auto versionIt =
-            targetIt->second.versions.find(removed.version);
-        if (versionIt == targetIt->second.versions.end()) continue;
-        const auto& data = versionIt->second;
-        const auto kind = data.kind.empty()
-            ? targetIt->second.type
-            : data.kind;
-        if (kind != "lib") continue;
-        destinations.insert(destinationName(
-            removed.target, targetIt->second, data));
-    }
-
-    for (const auto& name : destinations) {
-        const auto hasSurvivingOwner = std::ranges::any_of(
-            currentDb,
-            [&](const auto& targetEntry) {
-                return std::ranges::any_of(
-                    targetEntry.second.versions,
-                    [&](const auto& versionEntry) {
-                        const auto& data = versionEntry.second;
-                        const auto kind = data.kind.empty()
-                            ? targetEntry.second.type
-                            : data.kind;
-                        return kind == "lib"
-                            && destinationName(
-                                targetEntry.first,
-                                targetEntry.second,
-                                data) == name;
-                    });
-            });
-        if (hasSurvivingOwner) continue;
-
-        const auto destination = libDir / name;
-        std::error_code ec;
-        if (std::filesystem::exists(destination, ec)
-            || std::filesystem::is_symlink(destination, ec)) {
-            ec.clear();
-            std::filesystem::remove(destination, ec);
-        }
-    }
-}
+        const xvm::RemovalBatchResult& removalResult);
 
 void cleanup_removed_xvm_program_artifacts(
         const std::filesystem::path& binDir,
         const xvm::VersionDB& dbBeforeRemoval,
         const xvm::VersionDB& currentDb,
         const xvm::WorkspaceInstalled& installed,
-        const xvm::RemovalBatchResult& removalResult) {
-    std::set<std::string> removedPrograms;
-    for (const auto& removed : removalResult.removed) {
-        auto targetIt = dbBeforeRemoval.find(removed.target);
-        if (targetIt == dbBeforeRemoval.end()) continue;
-        auto versionIt =
-            targetIt->second.versions.find(removed.version);
-        if (versionIt == targetIt->second.versions.end()) continue;
-        const auto kind = versionIt->second.kind.empty()
-            ? targetIt->second.type
-            : versionIt->second.kind;
-        if (kind == "program") {
-            removedPrograms.insert(removed.target);
-        }
-    }
-
-    for (const auto& target : removedPrograms) {
-        if (xvm::has_usable_workspace_version(
-                currentDb, installed, target)) {
-            continue;
-        }
-#ifdef _WIN32
-        constexpr std::string_view shimExtension = ".exe";
-#else
-        constexpr std::string_view shimExtension = "";
-#endif
-        std::string shimName = target;
-        if (!shimExtension.empty()
-            && !shimName.ends_with(shimExtension)) {
-            shimName += shimExtension;
-        }
-        const auto shimPath = binDir / shimName;
-        std::error_code ec;
-        if (!std::filesystem::exists(shimPath, ec)
-            && !std::filesystem::is_symlink(shimPath, ec)) {
-            continue;
-        }
-        ec.clear();
-        std::filesystem::remove(shimPath, ec);
-        if (ec) {
-            log::warn("could not remove shim {}: {}; will be replaced "
-                      "on next install/use",
-                      shimPath.string(), ec.message());
-        }
-    }
-}
+        const xvm::RemovalBatchResult& removalResult);
 
 bool evict_invalid_archive_cache_(
         const std::filesystem::path& archive,
-        const ExtractError& error) {
-    if (error.kind != ExtractErrorKind::InvalidInputArchive) return false;
-    std::error_code ec;
-    bool removed = std::filesystem::remove(archive, ec);
-    auto sidecar = archive;
-    sidecar += ".meta";
-    ec.clear();
-    std::filesystem::remove(sidecar, ec);
-    return removed;
-}
+        const ExtractError& error);
 
 namespace detail_ {
 
 std::string format_hook_failure(
         std::string_view hookName,
-        const mcpplibs::xpkg::HookResult& result) {
-    auto trim = [](std::string_view text) {
-        while (!text.empty()
-               && std::isspace(static_cast<unsigned char>(text.front()))) {
-            text.remove_prefix(1);
-        }
-        while (!text.empty()
-               && std::isspace(static_cast<unsigned char>(text.back()))) {
-            text.remove_suffix(1);
-        }
-        return text;
-    };
-
-    auto error = trim(result.error);
-    auto output = trim(result.output);
-    std::string message = std::format("{} hook failed", hookName);
-    if (!error.empty()) {
-        message += ": ";
-        message.append(error);
-    }
-    if (!output.empty() && output != error) {
-        message.push_back('\n');
-        message.append(result.output);
-    }
-    return message;
-}
+        const mcpplibs::xpkg::HookResult& result);
 
 // Does a resolved node's version satisfy the version half of a dep spec?
 //
@@ -879,38 +232,15 @@ std::string format_hook_failure(
 // git hash -- still matches itself when a recipe writes it out exactly, which
 // is what every recipe did before ranges reached this code.
 bool dep_version_matches_(std::string_view nodeVersion,
-                          std::string_view depVersion) {
-    if (depVersion.empty()) return true;
-    if (nodeVersion == depVersion) return true;
-    return semver::satisfies_expr(nodeVersion, depVersion);
-}
+                          std::string_view depVersion);
 
 std::filesystem::path
 configure_xpkg_execution_artifact_paths_(
-        mcpplibs::xpkg::ExecutionContext& context) {
-    auto subosDir = Config::xvm_artifact_subos_dir();
-    context.bin_dir = subosDir / "bin";
-    context.subos_sysrootdir = subosDir.string();
-    return subosDir;
-}
+        mcpplibs::xpkg::ExecutionContext& context);
 
 void configure_dependency_store_roots_(
         mcpplibs::xpkg::ExecutionContext& context,
-        const std::filesystem::path& selectedStore) {
-    auto append = [&](std::filesystem::path root) {
-        if (root.empty()) return;
-        root = root.lexically_normal();
-        if (std::ranges::find(context.dependency_store_roots, root)
-            == context.dependency_store_roots.end()) {
-            context.dependency_store_roots.push_back(std::move(root));
-        }
-    };
-
-    append(selectedStore);
-    auto projectDataDir = Config::project_data_dir();
-    if (!projectDataDir.empty()) append(projectDataDir / "xpkgs");
-    append(Config::global_data_dir() / "xpkgs");
-}
+        const std::filesystem::path& selectedStore);
 
 // The index root a recipe's `xim.pkgindex.*` modules are loaded from.
 //
@@ -941,30 +271,7 @@ void configure_dependency_store_roots_(
 // expect pkgindex modules to resolve at all -- so the one remaining silent case
 // (no index anywhere) can be made loud instead of inferred.
 std::string pkgindex_root_for_(const std::filesystem::path& pkgFile,
-                               bool* outHasLibs = nullptr) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-
-    auto derived = pkgFile.parent_path().parent_path().parent_path();
-    if (fs::is_directory(derived / "libs", ec)) {
-        if (outHasLibs) *outHasLibs = true;
-        return derived.string();
-    }
-
-    // Only the primary index. Not "any index that happens to have libs": picking
-    // between several would be a guess about which ecosystem a recipe belongs to,
-    // and `xim.pkgindex.*` is one shared namespace by construction.
-    auto primary = Config::global_data_dir() / "xim-pkgindex";
-    if (fs::is_directory(primary / "libs", ec)) {
-        log::debug("pkgindex modules: {} has no libs/, using {}",
-                   derived.string(), primary.string());
-        if (outHasLibs) *outHasLibs = true;
-        return primary.string();
-    }
-
-    if (outHasLibs) *outHasLibs = false;
-    return derived.string();
-}
+                               bool* outHasLibs = nullptr);
 
 // Did the provider whose uninstall hook is about to run register any xvm
 // version for this target?
@@ -982,150 +289,49 @@ std::string pkgindex_root_for_(const std::filesystem::path& pkgFile,
 bool executing_provider_owns_no_version(
         const xvm::VersionDB& db,
         std::string_view target,
-        std::string_view executingProvider) {
-    if (executingProvider.empty()) return false;
-    auto it = db.find(std::string(target));
-    if (it == db.end()) return true;
-    for (const auto& [_, data] : it->second.versions) {
-        if (!data.bindingGroup || data.bindingGroup->provider.empty()) continue;
-        if (data.bindingGroup->provider == executingProvider) return false;
-    }
-    return true;
-}
-
-std::string effective_store_name_(std::string_view namespaceName, std::string_view name) {
-    return package_store_name(namespaceName, name);
-}
-
-std::string effective_store_name_(const PlanNode& node) {
-    return effective_store_name_(node.namespaceName, node.name);
-}
-
-std::string effective_store_name_(const PackageMatch& match) {
-    return effective_store_name_(match.namespaceName, match.name);
-}
-
-std::string version_namespace_(std::string_view namespaceName) {
-    const auto& globalRepos = Config::global_index_repos();
-    const bool isPrimary = !globalRepos.empty()
-        && namespaceName == globalRepos.front().name;
-    if (isPrimary || namespaceName.empty()) return {};
-    return std::string(namespaceName);
-}
-
-std::string plan_key_(const PlanNode& node) {
-    auto name = node.canonicalName.empty()
-        ? canonical_package_name(node.namespaceName, node.name)
-        : node.canonicalName;
-    if (node.version.empty()) return name;
-    return name + "@" + node.version;
-}
-
-std::filesystem::path data_root_for_(const std::filesystem::path& targetRoot) {
-    if (targetRoot.filename() == "xpkgs") return targetRoot.parent_path();
-    return targetRoot;
-}
+        std::string_view executingProvider);
+
+std::string effective_store_name_(std::string_view namespaceName, std::string_view name);
+
+std::string effective_store_name_(const PlanNode& node);
+
+std::string effective_store_name_(const PackageMatch& match);
+
+std::string version_namespace_(std::string_view namespaceName);
+
+std::string plan_key_(const PlanNode& node);
+
+std::filesystem::path data_root_for_(const std::filesystem::path& targetRoot);
 
 std::filesystem::path runtime_dir_(const PlanNode& node,
-                                   const std::filesystem::path& fallbackDataDir) {
-    auto targetRoot = node.storeRoot.empty() ? (fallbackDataDir / "xpkgs") : node.storeRoot;
-    auto dataRoot = data_root_for_(targetRoot);
-    return dataRoot / "runtimedir";
-}
+                                   const std::filesystem::path& fallbackDataDir);
 
-std::filesystem::path xpkg_snapshot_file_(const std::filesystem::path& installDir) {
-    return installDir / ".xpkg.lua";
-}
+std::filesystem::path xpkg_snapshot_file_(const std::filesystem::path& installDir);
 
 std::expected<void, std::string>
 save_xpkg_snapshot_(const std::filesystem::path& sourcePkgFile,
-                    const std::filesystem::path& installDir) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-
-    if (sourcePkgFile.empty()
-        || !fs::exists(sourcePkgFile, ec)
-        || !fs::is_regular_file(sourcePkgFile, ec)) {
-        return std::unexpected(
-            std::format("xpkg snapshot source not found: {}", sourcePkgFile.string()));
-    }
-
-    fs::create_directories(installDir, ec);
-    if (ec) {
-        return std::unexpected(
-            std::format("failed to create install dir for xpkg snapshot: {}", ec.message()));
-    }
-
-    auto snapshotFile = xpkg_snapshot_file_(installDir);
-    ec.clear();
-    if (fs::exists(snapshotFile, ec)) {
-        ec.clear();
-        if (fs::equivalent(sourcePkgFile, snapshotFile, ec) && !ec) return {};
-    }
-
-    ec.clear();
-    fs::copy_file(sourcePkgFile, snapshotFile, fs::copy_options::overwrite_existing, ec);
-    if (ec) {
-        return std::unexpected(
-            std::format("failed to save xpkg snapshot {}: {}",
-                        snapshotFile.string(), ec.message()));
-    }
-    return {};
-}
+                    const std::filesystem::path& installDir);
 
 std::filesystem::path uninstall_xpkg_file_(const std::filesystem::path& indexPkgFile,
-                                           const std::filesystem::path& installDir) {
-    std::error_code ec;
-    auto snapshotFile = xpkg_snapshot_file_(installDir);
-    if (std::filesystem::exists(snapshotFile, ec)) {
-        return snapshotFile;
-    }
-    return indexPkgFile;
-}
-
-bool is_archive_(const std::filesystem::path& path) {
-    auto filename = path.filename().string();
-    return filename.ends_with(".tar.gz")
-        || filename.ends_with(".tar.xz")
-        || filename.ends_with(".tar.bz2")
-        || filename.ends_with(".tgz")
-        || filename.ends_with(".zip");
-}
+                                           const std::filesystem::path& installDir);
+
+bool is_archive_(const std::filesystem::path& path);
 
 // The per-OS arch token used in release asset names. One definition, in
 // platform::Target, because every copy of this `#if` chain is a place the
 // build ABI and the machine's architecture can be confused for each other.
-std::string detect_arch_() {
-    return std::string(xlings::platform::build_arch());
-}
+std::string detect_arch_();
 
-std::string default_res_server_() {
-    auto server = Config::resource_server();
-    if (!server.empty()) return server;
-    return "https://github.com/xlings-res";
-}
+std::string default_res_server_();
 
 std::string build_xlings_res_url_with_server_(std::string_view server,
                                               std::string_view pkgName,
                                               std::string_view version,
-                                              std::string_view platform) {
-    auto ext = std::string(platform) == "windows" ? "zip" : "tar.gz";
-    return std::format("{}/{}/releases/download/{}/{}-{}-{}-{}.{}",
-                       server,
-                       pkgName,
-                       version,
-                       pkgName,
-                       version,
-                       platform,
-                       detect_arch_(),
-                       ext);
-}
+                                              std::string_view platform);
 
 std::string build_xlings_res_url_(std::string_view pkgName,
                                   std::string_view version,
-                                  std::string_view platform) {
-    return build_xlings_res_url_with_server_(default_res_server_(), pkgName, version, platform);
-}
+                                  std::string_view platform);
 
 // Build fallback URLs from all candidate resource servers (excluding the
 // selected one).
@@ -1138,18 +344,7 @@ std::string build_xlings_res_url_(std::string_view pkgName,
 // copy one hop away. See Config::all_resource_servers_for_.
 std::vector<std::string> build_xlings_res_fallback_urls_(std::string_view pkgName,
                                                          std::string_view version,
-                                                         std::string_view platform) {
-    auto selected = default_res_server_();
-    auto candidates = Config::resource_servers_with_cross_region();
-    std::vector<std::string> fallbacks;
-    for (auto& server : candidates) {
-        if (server != selected) {
-            fallbacks.push_back(
-                build_xlings_res_url_with_server_(server, pkgName, version, platform));
-        }
-    }
-    return fallbacks;
-}
+                                                         std::string_view platform);
 
 struct DownloadResource_ {
     std::string version;
@@ -1165,196 +360,28 @@ std::expected<DownloadResource_, std::string> resolve_download_resource_(
         std::string_view requestedVersion,
         std::string_view platform,
         std::string_view arch,
-        std::string_view preferredMirror) {
-    auto resolved = mcpplibs::xpkg::resolve_resource(matrix, {
-        .name = std::string(name),
-        .version = std::string(requestedVersion),
-        .platform = std::string(platform),
-        .arch = std::string(arch),
-    });
-    if (!resolved) return std::unexpected(resolved.error());
-
-    DownloadResource_ result {
-        .version = resolved->version,
-        .url = resolved->url,
-        .sha256 = resolved->sha256,
-        .mirrors = resolved->mirrors,
-        .useResFallbacks = resolved->kind
-            == mcpplibs::xpkg::SourceKind::XlingsRes,
-    };
-    if (result.useResFallbacks) {
-        result.url = build_xlings_res_url_(name, result.version, platform);
-    }
-
-    auto preferred = preferredMirror.empty()
-        ? std::string_view{"GLOBAL"}
-        : preferredMirror;
-    if (auto it = result.mirrors.find(std::string(preferred));
-            it != result.mirrors.end()) {
-        result.url = it->second;
-    }
-    if (result.url.empty())
-        return std::unexpected("resolved resource URL is empty");
-    return result;
-}
-
-bool has_directory_entries_(const std::filesystem::path& dir) {
-    std::error_code ec;
-    if (!std::filesystem::exists(dir, ec) || !std::filesystem::is_directory(dir, ec)) return false;
-    return std::filesystem::directory_iterator(dir, ec) != std::default_sentinel;
-}
+        std::string_view preferredMirror);
+
+bool has_directory_entries_(const std::filesystem::path& dir);
 
 bool stage_extracted_payload_(const std::filesystem::path& extractRoot,
-                              const std::filesystem::path& installDir) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    if (!fs::exists(extractRoot, ec) || !fs::is_directory(extractRoot, ec)) return false;
-
-    std::vector<fs::path> entries;
-    for (fs::directory_iterator it(extractRoot, ec);
-         !ec && it != std::default_sentinel; it.increment(ec)) {
-        entries.push_back(it->path());
-    }
-    if (ec || entries.empty()) return false;
-
-    fs::path payloadRoot = extractRoot;
-    if (entries.size() == 1 && fs::is_directory(entries.front(), ec) && !ec) {
-        payloadRoot = entries.front();
-    }
-
-    if (fs::exists(installDir, ec)) {
-        if (fs::is_empty(installDir, ec)) {
-            ec.clear();
-            fs::remove_all(installDir, ec);
-            if (ec) return false;
-        } else {
-            return true;
-        }
-    }
-
-    fs::create_directories(installDir.parent_path(), ec);
-    if (ec) return false;
-
-    if (payloadRoot != extractRoot) {
-        fs::rename(payloadRoot, installDir, ec);
-        if (!ec) return true;
-        ec.clear();
-    }
-
-    fs::create_directories(installDir, ec);
-    if (ec) return false;
-
-    auto move_entry = [&](const fs::path& source) -> bool {
-        auto dest = installDir / source.filename();
-        fs::rename(source, dest, ec);
-        if (!ec) return true;
-        ec.clear();
-        fs::copy(source, dest,
-                 fs::copy_options::recursive | fs::copy_options::overwrite_existing,
-                 ec);
-        if (ec) return false;
-        ec.clear();
-        fs::remove_all(source, ec);
-        return !ec;
-    };
+                              const std::filesystem::path& installDir);
 
-    if (payloadRoot == extractRoot) {
-        for (auto& entry : entries) {
-            if (!move_entry(entry)) return false;
-        }
-        return true;
-    }
-
-    std::vector<fs::path> payloadEntries;
-    for (fs::directory_iterator it(payloadRoot, ec);
-         !ec && it != std::default_sentinel; it.increment(ec)) {
-        payloadEntries.push_back(it->path());
-    }
-    if (ec) return false;
-    for (auto& entry : payloadEntries) {
-        if (!move_entry(entry)) return false;
-    }
-    return true;
-}
-
-bool normalize_file_install_(const std::filesystem::path& installPath) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    if (!fs::exists(installPath, ec) || !fs::is_regular_file(installPath, ec)) return true;
-
-    auto parent = installPath.parent_path();
-    auto fileName = installPath.filename();
-    auto tempFile = parent / (fileName.string() + ".xlings.tmp");
-
-    fs::rename(installPath, tempFile, ec);
-    if (ec) return false;
-
-    fs::create_directories(installPath, ec);
-    if (ec) {
-        ec.clear();
-        fs::rename(tempFile, installPath, ec);
-        return false;
-    }
-
-    fs::rename(tempFile, installPath / fileName, ec);
-    if (!ec) return true;
-
-    ec.clear();
-    fs::copy_file(tempFile, installPath / fileName, fs::copy_options::overwrite_existing, ec);
-    if (ec) return false;
-    ec.clear();
-    fs::remove(tempFile, ec);
-    return !ec;
-}
+bool normalize_file_install_(const std::filesystem::path& installPath);
 
 class ScopedCurrentDir_ {
     std::filesystem::path oldDir_;
     bool changed_ { false };
 
 public:
-    explicit ScopedCurrentDir_(const std::filesystem::path& newDir) {
-        std::error_code ec;
-        oldDir_ = std::filesystem::current_path(ec);
-        if (ec || newDir.empty()) return;
-        std::filesystem::create_directories(newDir, ec);
-        if (ec) return;
-        std::filesystem::current_path(newDir, ec);
-        changed_ = !ec;
-    }
-
-    ~ScopedCurrentDir_() {
-        if (!changed_) return;
-        std::error_code ec;
-        std::filesystem::current_path(oldDir_, ec);
-    }
+    explicit ScopedCurrentDir_(const std::filesystem::path& newDir);
+
+    ~ScopedCurrentDir_();
 };
 
-std::filesystem::path current_workspace_config_path_() {
-    if (Config::has_project_config()) {
-        if (Config::project_subos_mode() == ProjectSubosMode::Named) {
-            return Config::project_dir() / ".xlings" / "subos" / Config::project_subos_name() / ".xlings.json";
-        }
-        if (Config::project_subos_mode() == ProjectSubosMode::Anonymous) {
-            return Config::project_state_path();
-        }
-        return Config::project_state_path();
-    }
-    return Config::paths().homeDir / "subos" / Config::paths().activeSubos / ".xlings.json";
-}
-
-xvm::SubosWorkspace load_workspace_file_(const std::filesystem::path& path) {
-    std::error_code ec;
-    if (!std::filesystem::exists(path, ec)) return {};
-    try {
-        auto content = platform::read_file_to_string(path.string());
-        auto json = nlohmann::json::parse(content, nullptr, false);
-        if (json.is_discarded() || !json.is_object()) return {};
-        if (!json.contains("workspace") || !json["workspace"].is_object()) return {};
-        return xvm::subos_workspace_from_json(json["workspace"]);
-    } catch (...) {
-        return {};
-    }
-}
+std::filesystem::path current_workspace_config_path_();
+
+xvm::SubosWorkspace load_workspace_file_(const std::filesystem::path& path);
 
 // Every workspace file that can pin a payload against deletion.
 //
@@ -1372,221 +399,18 @@ xvm::SubosWorkspace load_workspace_file_(const std::filesystem::path& path) {
 //
 // `scope` is retained for callers that still describe what they are removing,
 // but no longer selects a side.
-std::vector<std::filesystem::path> workspace_config_paths_for_scope_(PackageScope scope) {
-    namespace fs = std::filesystem;
-    (void)scope;
-    std::vector<fs::path> paths;
-    auto push = [&](fs::path p) {
-        if (p.empty()) return;
-        if (std::ranges::find(paths, p) != paths.end()) return;
-        paths.push_back(std::move(p));
-    };
-
-    if (Config::has_project_config()) {
-        auto projectRoot = Config::project_dir();
-        if (!projectRoot.empty()) {
-            push(Config::project_manifest_path());
-            push(Config::project_state_path());
-            auto subosRoot = projectRoot / ".xlings" / "subos";
-            std::error_code ec;
-            if (fs::exists(subosRoot, ec) && fs::is_directory(subosRoot, ec)) {
-                for (auto& entry : platform::dir_entries(subosRoot)) {
-                    if (entry.is_directory()) {
-                        push(entry.path() / ".xlings.json");
-                    }
-                }
-            }
-        }
-    }
-
-    auto subosRoot = Config::paths().homeDir / "subos";
-    std::error_code ec;
-    if (fs::exists(subosRoot, ec) && fs::is_directory(subosRoot, ec)) {
-        for (auto& entry : platform::dir_entries(subosRoot)) {
-            if (entry.is_directory()) {
-                auto name = entry.path().filename().string();
-                if (name != "current") {
-                    push(entry.path() / ".xlings.json");
-                }
-            }
-        }
-    }
-    return paths;
-}
+std::vector<std::filesystem::path> workspace_config_paths_for_scope_(PackageScope scope);
 
 bool is_version_referenced_anywhere_(PackageScope scope,
                                      const std::string& target,
                                      const std::string& version,
-                                     const std::filesystem::path& excludePath = {}) {
-    std::error_code ec;
-    auto excludeCanonical = excludePath.empty() ? std::filesystem::path{} : std::filesystem::weakly_canonical(excludePath, ec);
-    for (auto& configPath : workspace_config_paths_for_scope_(scope)) {
-        auto canonical = std::filesystem::weakly_canonical(configPath, ec);
-        if (!excludeCanonical.empty() && !ec && canonical == excludeCanonical) {
-            continue;
-        }
-        // 0.4.19+: a payload is "referenced" by a subos if EITHER its
-        // active version equals `version` OR `version` appears in that
-        // subos's installed[] set. Pre-0.4.19 the active-only check was
-        // sufficient because installed[] didn't exist; with C2 schema a
-        // user can `xlings remove` the active version while still having
-        // other installed versions, and a payload that only appears in
-        // some other subos's installed[] (but not its active) must still
-        // pin its xpkgs/ directory against GC.
-        //
-        // Stored values are namespaced (`ns:1.0` for non-primary repos,
-        // bare for primary). New removal callers pass the exact stored key;
-        // retain bare matching here for legacy workspace files.
-        auto matches = [&](std::string_view stored) {
-            return stored == version
-                || xvm::strip_namespace(std::string(stored)) == version;
-        };
-        auto sws = load_workspace_file_(configPath);
-        if (auto it = sws.active.find(target);
-            it != sws.active.end() && matches(it->second)) return true;
-        if (auto it = sws.installed.find(target); it != sws.installed.end()) {
-            for (auto& v : it->second) {
-                if (matches(v)) return true;
-            }
-        }
-    }
-    return false;
-}
-
-void remove_target_shims_(const std::string& target, const std::string& version) {
-    namespace fs = std::filesystem;
-    auto db = Config::versions();
-    auto* vinfo = xvm::get_vinfo(db, target);
-    auto& binDir = Config::paths().binDir;
-    std::error_code ec;
-
-    // A program's shim is a generic dispatcher to the bootstrap; the actual
-    // version it routes to is the workspace pointer (read at runtime). So
-    // the shim is only stale when **the current subos** has dropped its
-    // last version of the name. With surviving versions still in this
-    // subos's installed[], the shim must stay — auto-fallback in
-    // detach_current_subos_ updates `active` to the highest remaining
-    // version and the shim resolves through that.
-    //
-    // 0.4.19+: this check is now scoped to the **current subos's
-    // installed[]**, not the global versions DB. Pre-0.4.19 the gate
-    // was `is_last_version_for(global)`, which under-removed: subos A
-    // could drain its installed[] for a target while subos B still had
-    // some other version of it, leaving a stale shim in A's bin/. With
-    // C2 schema each subos's bin/ is independent — so is each subos's
-    // shim-lifetime decision.
-    //
-    // Caller contract: detach_current_subos_ has already pruned
-    // `version` from this subos's installed[] before calling us. So
-    // checking "is the post-removal installed[] empty?" gives the
-    // correct answer.
-    const auto& wsi = Config::workspace_installed();
-    auto subos_has_any_version_of = [&](const std::string& name) {
-        auto it = wsi.find(name);
-        return it != wsi.end() && !it->second.empty();
-    };
+                                     const std::filesystem::path& excludePath = {});
 
-    auto mainName = (vinfo && !vinfo->filename.empty()) ? vinfo->filename : target;
-    if (!subos_has_any_version_of(target)) {
-        auto mainShim = binDir / mainName;
-        if (fs::exists(mainShim, ec) || fs::is_symlink(mainShim, ec)) {
-            ec.clear();
-            fs::remove(mainShim, ec);
-        }
-    }
-
-    if (!vinfo) return;
-    for (auto& [bindingName, vermap] : vinfo->bindings) {
-        auto vit = vermap.find(version);
-        if (vit == vermap.end()) continue;
-        if (subos_has_any_version_of(bindingName)) continue;  // still in use here
-        auto bindPath = binDir / bindingName;
-        ec.clear();
-        if (fs::exists(bindPath, ec) || fs::is_symlink(bindPath, ec)) {
-            ec.clear();
-            fs::remove(bindPath, ec);
-        }
-    }
-}
+void remove_target_shims_(const std::string& target, const std::string& version);
 
 void detach_current_subos_(const std::string& target,
                            const std::string& version,
-                           bool persist = true) {
-    auto& ws = Config::workspace_mut();
-    auto& wsi = Config::workspace_installed_mut();
-
-    auto matches = [&](std::string_view stored) {
-        return stored == version;
-    };
-
-    // Step 1 (0.4.19+): always drop `version` from this subos's
-    // installed[] set, even when it isn't the currently active version.
-    // The set is the per-subos opt-in list; an explicit `xlings remove
-    // foo@X` always means "this subos no longer wants X".
-    bool installedChanged = false;
-    if (auto it = wsi.find(target); it != wsi.end()) {
-        auto& list = it->second;
-        auto pred = [&](const std::string& v) { return matches(v); };
-        auto erased = std::remove_if(list.begin(), list.end(), pred);
-        if (erased != list.end()) {
-            list.erase(erased, list.end());
-            installedChanged = true;
-            if (list.empty()) wsi.erase(it);
-        }
-    }
-
-    // Step 2: if `version` was the active pointer, do the actual subos
-    // teardown (remove headers / libs / shims) and then either fall
-    // back to another installed version or clear the pointer entirely.
-    auto wit = ws.find(target);
-    bool wasActive = wit != ws.end() && matches(wit->second);
-
-    if (wasActive) {
-        auto db = Config::versions();
-        auto sysroot_include = Config::paths().subosDir / "usr" / "include";
-        auto sysroot_lib = Config::paths().libDir;
-        // The whole release's headers, not just whatever single directory
-        // landed in this entry's `includedir`: a release declaring more than
-        // one header directory would otherwise leave all but the last behind
-        // in the sysroot, pointing into a payload that is being deleted.
-        for (const auto& asset :
-                 xvm::group_header_assets(db, target, version)) {
-            xvm::remove_headers(asset, sysroot_include);
-        }
-        if (const auto placement =
-                xvm::library_placement(db, target, version);
-            !placement.empty()) {
-            xvm::remove_library(placement.name, sysroot_lib);
-        }
-        if (const auto file = xvm::file_placement(db, target, version);
-            !file.empty()) {
-            xvm::remove_asset(Config::paths().subosDir / file.destination);
-        }
-        remove_target_shims_(target, version);
-
-        // Auto-fallback: when the user removes the active version but
-        // still has other versions installed in this subos, switch
-        // active to the highest remaining (installed[] is stored
-        // sorted ascending by subos_workspace_to_json — `back()` is
-        // the lexicographically-highest, which approximates "newest"
-        // for typical semver-ish version strings).
-        //
-        // The shim for the fallback version already exists from its
-        // earlier install — only the active pointer needs updating;
-        // headers/libs are NOT auto-relinked (lazy: next call to
-        // `xlings use` would do that explicitly). This avoids a
-        // surprise sysroot reshuffle on every remove.
-        if (auto sit = wsi.find(target); sit != wsi.end() && !sit->second.empty()) {
-            wit->second = sit->second.back();
-        } else {
-            ws.erase(wit);
-        }
-    }
-
-    if (persist && (wasActive || installedChanged)) {
-        Config::save_workspace();
-    }
-}
+                           bool persist = true);
 
 // Record a package's `subos.env` declarations into the subos it installs into.
 //
@@ -1599,573 +423,12 @@ void detach_current_subos_(const std::string& target,
 // uninstall unable to clean up (the owner's key is what removal keys on) and
 // would hand any recipe the ability to edit any other's environment.
 bool apply_subos_env_ops_(const std::vector<mcpplibs::xpkg::XvmOp>& operations,
-                          const PlanNode& node) {
-    namespace mf = xlings::subos::manifest;
-
-    std::vector<const mcpplibs::xpkg::XvmOp*> declarations;
-    for (const auto& op : operations)
-        if (op.op == "subos_env") declarations.push_back(&op);
-    if (declarations.empty()) return true;
-
-    const auto canonical = node.canonicalName.empty()
-        ? canonical_package_name(node.namespaceName, node.name)
-        : node.canonicalName;
-
-    const auto subosDir = Config::xvm_artifact_subos_dir();
-    auto docPath = mf::config_path(subosDir);
-    auto doc = mf::read_document(subosDir);
-    if (!doc) {
-        // Absent is recoverable (an old subos predates the block); unreadable
-        // is not, and must not be papered over by starting from {} -- that
-        // would discard a workspace we never managed to parse.
-        std::error_code ec;
-        if (std::filesystem::exists(docPath, ec)) {
-            log::error("[xim] {} is not readable JSON; refusing to record "
-                       "subos env declarations for {}@{}",
-                       docPath.string(), canonical, node.version);
-            return false;
-        }
-        nlohmann::json fresh;
-        fresh["workspace"] = nlohmann::json::object();
-        fresh[std::string(mf::BLOCK)] = mf::make_block(
-            mf::DEFAULT_RUNTIME, std::format("xlings {}", Info::VERSION),
-            platform::host_glibc_version());
-        doc = std::move(fresh);
-    }
-    if (!doc->contains(std::string(mf::BLOCK))
-        || !doc->at(std::string(mf::BLOCK)).is_object()) {
-        (*doc)[std::string(mf::BLOCK)] = mf::make_block(
-            mf::DEFAULT_RUNTIME, std::format("xlings {}", Info::VERSION),
-            platform::host_glibc_version());
-    }
-
-    // C1 -- the subos layer's "exactly one", for the case where nothing else
-    // can supply it.
-    //
-    // The store keeps many versions by design; each consumer freezes one into
-    // its own RPATH; the subos in between holds exactly one. Nothing enforced
-    // that, so installing a second version appended a second provider section
-    // and BOTH contributed. Measured: mesa@25.0.7 and mesa@25.0.7.1 both bound
-    // in one subos, both on __EGL_VENDOR_LIBRARY_DIRS, EGL enumerating the
-    // device twice, doctor silent. The two records agreed -- on an answer the
-    // model forbids.
-    //
-    // The live version is normally decided by xvm and read back at activation
-    // (manifest::select_effective), so a package WITH an active version needs
-    // nothing here: installing a second version leaves the first live until
-    // `xlings use` says otherwise, which is what install and use have meant
-    // since 2026.7.31. Superseding here as well would make install a second
-    // selector -- another answerer to a question that has one, which is the
-    // defect, not the fix.
-    //
-    // What is left is the case where xvm has no answer at all. Measured: a bare
-    // `xvm.add(name)` DOES record an active version, so an ordinary install
-    // never reaches this branch -- it covers a manifest whose workspace record
-    // was lost while its declarations survived (a payload pruned out from under
-    // it, a subos config copied between homes, a hand edit). There every
-    // provider contributes, so a second version really does double the
-    // environment, and the only moment anything can choose is now, while a
-    // human is naming a version. So: supersede only when nothing else can.
-    //
-    // Before the ownership checks below, deliberately: those return false on a
-    // malformed declaration, and unbinding first would leave the subos holding
-    // neither version.
-    std::vector<std::string> superseded;
-    {
-        const auto active = mf::active_versions(*doc);
-        std::set<std::string> ownNames;
-        for (const auto* op : declarations) {
-            if (!mf::is_binding(op->binding)) continue;
-            ownNames.insert(std::string(mf::binding_name(op->binding)));
-        }
-        for (const auto& name : ownNames) {
-            if (active.contains(name)) continue;   // xvm decides, not install
-            for (const auto& existing : mf::providers_named(*doc, name)) {
-                const bool sameBinding = std::ranges::any_of(
-                    declarations, [&](const auto* op) {
-                        return op->binding == existing;
-                    });
-                if (sameBinding) continue;     // re-install of the same version
-                superseded.push_back(existing);
-            }
-        }
-    }
-
-    bool changed = false;
-    // Collected per binding first, so each section can be written as a whole.
-    // std::map, not unordered: the write order of sections shows up in the file
-    // a user reads and in diffs of it.
-    std::map<std::string, std::vector<mf::EnvDecl>> perBinding;
-    for (const auto* op : declarations) {
-        if (!mf::is_binding(op->binding)) {
-            log::error("[xim] {}@{} declared env '{}' with binding '{}' "
-                       "(expected <name>@<version>); nothing recorded",
-                       canonical, node.version, op->var, op->binding);
-            return false;
-        }
-        const auto owner = mf::binding_name(op->binding);
-        if (owner != node.name && owner != canonical) {
-            log::error("[xim] {}@{} declared env '{}' for '{}', which it does "
-                       "not own; nothing recorded",
-                       canonical, node.version, op->var, op->binding);
-            return false;
-        }
-        // B5 / B3: a declaration that can put our code into someone else's
-        // process is a privileged operation, and install is the only moment a
-        // human is watching. Reported, not refused -- nvidia-gl-host-link
-        // legitimately needs one today, and refusing would leave the user with
-        // no GPU and no way forward. What must not happen is that it lands
-        // silently: the last one did, and `xlings subos use` returned a
-        // /bin/bash that died of SIGSEGV before printing a character.
-        //
-        // Default-deny by variable name (manifest::names_only_data), so a
-        // variable nobody has classified reads as privileged. See AD-3.
-        if (mf::is_privileged_env(op->var, op->value)) {
-            log::warn("[xim] {}@{} declares {} = {}", canonical, node.version,
-                      op->var, op->value);
-            log::warn("      This variable can load code from our payload into "
-                      "processes we do not own, including host binaries running "
-                      "under the host loader. Prefer RPATH on the consumer; use "
-                      "this only where RPATH cannot reach (a library that opens "
-                      "its plugins itself), and say why in the recipe.");
-        }
-        perBinding[op->binding].push_back(
-            {.var = op->var, .op = op->mode, .value = op->value});
-    }
-
-    // Written as a REPLACEMENT of each binding's section, not a union with it.
-    //
-    // `add_env` is idempotent per (var, op, value) triple, which keeps a re-run
-    // of the same declarations steady and silently accumulates a second
-    // generation when the recipe's declarations CHANGE. Measured while moving
-    // mesa's discovery paths from `${pkgdir}` to `${subosdir}`: the section held
-    // both, so LIBGL_DRIVERS_PATH resolved to the new subos directory followed
-    // by a stale payload path and __EGL_VENDOR_LIBRARY_DIRS listed one directory
-    // twice -- with nothing reporting it, and the stale entry becoming a dead
-    // directory as soon as that payload is collected.
-    //
-    // Only bindings that declared something THIS run are touched. A binding
-    // belonging to another package keeps its section; that is the same
-    // ownership-by-binding rule that lets uninstall need no recipe cleanup.
-    //
-    // A package that stops declaring env entirely is NOT handled here and must
-    // not be: `declarations` is empty then, this function returns before the
-    // ownership checks, and the stale section is removed by uninstall or by
-    // `superseded` above. Clearing on an empty batch would delete a live
-    // section every time an unrelated dependent's install re-ran a hook that
-    // happens to declare nothing.
-    for (const auto& [binding, decls] : perBinding) {
-        changed |= mf::set_env_section(*doc, binding, decls);
-    }
-
-    // Only now that every declaration passed. Reported at info level, not
-    // debug: a version silently leaving a subos is exactly the kind of state
-    // change users later cannot account for.
-    for (const auto& binding : superseded) {
-        if (!mf::remove_provider(*doc, binding)) continue;
-        changed = true;
-        log::info("[xim] subos '{}' now holds {}@{}; unbound {} (it declares no "
-                  "xvm version, so nothing else could say which is live)",
-                  Config::paths().activeSubos.empty()
-                      ? std::string{"default"} : Config::paths().activeSubos,
-                  canonical, node.version, binding);
-        log::info("      Its payload is untouched -- the store keeps every "
-                  "installed version. To keep both active, use separate subos.");
-    }
-
-    if (!changed) return true;
-
-    if (auto findings = mf::validate_block(*doc); !findings.empty()) {
-        log::error("[xim] recording env declarations for {}@{} would leave an "
-                   "invalid subos manifest: {}", canonical, node.version,
-                   mf::describe(findings.front().kind));
-        return false;
-    }
-
-    try {
-        platform::write_string_to_file(docPath.string(), doc->dump(2));
-    } catch (const std::exception& e) {
-        log::error("[xim] failed to write {}: {}", docPath.string(), e.what());
-        return false;
-    }
-    log::debug("[xim] recorded {} subos env declaration(s) for {}@{}",
-               declarations.size(), canonical, node.version);
-    return true;
-}
+                          const PlanNode& node);
 
 bool process_xvm_operations_(const PlanNode& node,
                              const std::filesystem::path& dataDir,
                              mcpplibs::xpkg::PackageExecutor& executor,
-                             bool useAfterInstall) {
-    auto xvm_ops = executor.xvm_operations();
-
-    // Before the early return below. A package that declares only env and
-    // registers nothing with xvm has an empty registration batch, and would
-    // otherwise install cleanly with its declarations dropped on the floor --
-    // the exact shape where "nothing happened" and "it worked" look alike.
-    if (!apply_subos_env_ops_(xvm_ops, node)) return false;
-
-    auto& paths = Config::paths();
-    auto& scopedDb = Config::versions_mut();
-    auto& scopedWorkspace = Config::workspace_mut();
-    auto& scopedInstalled = Config::workspace_installed_mut();
-    const auto artifactSubosDir =
-        Config::xvm_artifact_subos_dir();
-    const auto artifactBinDir = artifactSubosDir / "bin";
-    const auto sysroot_lib = artifactSubosDir / "lib";
-    const auto sysroot_include =
-        artifactSubosDir / "usr" / "include";
-
-    // Locate xlings binary for shim creation
-#ifdef _WIN32
-    auto xlings_bin = paths.homeDir / "bin" / "xlings.exe";
-    constexpr std::string_view shim_ext = ".exe";
-#else
-    auto xlings_bin = paths.homeDir / "bin" / "xlings";
-    constexpr std::string_view shim_ext = "";
-#endif
-    if (!std::filesystem::exists(xlings_bin))
-        xlings_bin = paths.homeDir / "xlings";
-
-    // Primary repo versions retain their historical bare keys. Other repos
-    // retain their namespace so install and exact removal resolve identically.
-    const auto versionNamespace = version_namespace_(node.namespaceName);
-
-    auto registration = normalize_xpkg_registration_plan(
-        node, xvm_ops, versionNamespace, dataDir, useAfterInstall);
-    if (!registration) {
-        log::warn(
-            "xvm registration normalization failed for {}@{}: {} "
-            "(operation={}, target='{}', version='{}')",
-            node.canonicalName.empty()
-                ? canonical_package_name(node.namespaceName, node.name)
-                : node.canonicalName,
-            node.version,
-            registration.error().message,
-            registration.error().operationIndex,
-            registration.error().target,
-            registration.error().version);
-        return false;
-    }
-    const bool hasRemoval = std::ranges::any_of(
-        xvm_ops,
-        [](const auto& operation) {
-            return operation.op == "remove"
-                || operation.op == "remove_all";
-        });
-    if (!hasRemoval
-        && registration->batch.nodes.empty()
-        && registration->batch.headers.empty()
-        && registration->effects.empty()) {
-        return true;
-    }
-
-    xvm::RemovalContext removalContext;
-    if (hasRemoval) {
-        auto snapshot = snapshot_xpkg_removal_context(
-            scopedDb, scopedWorkspace, xvm_ops,
-            registration->batch.provider,
-            registration->batch.providerVersion);
-        if (!snapshot) {
-            // Selection runs before any mutation, so nothing has moved yet.
-            log::error("{}", xvm::render(
-                xvm::describe(
-                    snapshot.error(),
-                    std::format("{}@{}",
-                                registration->batch.provider,
-                                registration->batch.providerVersion)),
-                /*nothingChanged=*/true));
-            return false;
-        }
-        removalContext = std::move(*snapshot);
-    }
-
-    const auto dbBeforeRemoval = scopedDb;
-    const auto workspaceBeforeRemoval = scopedWorkspace;
-    auto metadata = apply_xpkg_xvm_metadata_batch(
-        scopedDb,
-        scopedWorkspace,
-        scopedInstalled,
-        xvm_ops,
-        removalContext,
-        *registration);
-    if (!metadata) {
-        const auto owner = std::format("{}@{}",
-                                       registration->batch.provider,
-                                       registration->batch.providerVersion);
-        // apply_xpkg_xvm_metadata_batch works on copies and only swaps them
-        // in on success, so a failure here has left the stored state alone.
-        if (std::holds_alternative<xvm::RemovalError>(
-                metadata.error())) {
-            log::error("{}", xvm::render(
-                xvm::describe(
-                    std::get<xvm::RemovalError>(metadata.error()), owner),
-                /*nothingChanged=*/true));
-        } else {
-            log::error("{}", xvm::render(
-                xvm::describe(
-                    std::get<xvm::RegistrationError>(metadata.error()), owner),
-                /*nothingChanged=*/true));
-        }
-        return false;
-    }
-
-    cleanup_removed_xvm_library_artifacts(
-        sysroot_lib,
-        dbBeforeRemoval,
-        scopedDb,
-        metadata->removal);
-
-    // Removal takes the removed release's headers out of the sysroot. When
-    // it then falls back to a surviving release, nothing put that release's
-    // headers back -- the sysroot ended up with none at all, and `xlings use`
-    // could not repair it because switching to an already-active version is
-    // a no-op. Re-materialize whatever the fallback made active.
-    for (const auto& [target, version] : scopedWorkspace) {
-        auto beforeIt = workspaceBeforeRemoval.find(target);
-        if (beforeIt != workspaceBeforeRemoval.end()
-            && beforeIt->second == version) {
-            continue;  // unchanged
-        }
-        auto infoIt = scopedDb.find(target);
-        if (infoIt == scopedDb.end()) continue;
-        auto dataIt = infoIt->second.versions.find(version);
-        if (dataIt == infoIt->second.versions.end()) continue;
-        for (const auto& asset :
-                 xvm::group_header_assets(scopedDb, target, version)) {
-            xvm::install_headers(asset, sysroot_include);
-        }
-        if (const auto placement =
-                xvm::library_placement(scopedDb, target, version);
-            !placement.empty()) {
-            xvm::place_library(placement.source, placement.name, sysroot_lib);
-        }
-        if (const auto file = xvm::file_placement(scopedDb, target, version);
-            !file.empty()) {
-            xvm::place_asset(file.source,
-                             Config::paths().subosDir / file.destination);
-        }
-    }
-
-    // Written after the batch, not inside it: the batch owns the group model
-    // and must not be taught a legacy field. This runs against the committed
-    // scopedDb, so a package whose own name is not a registered target simply
-    // gets no marker rather than a phantom entry.
-    if (const auto headerVersion =
-            xvm::make_ns_version(versionNamespace, node.version);
-        attach_legacy_header_dir(
-            scopedDb, node.name, headerVersion, metadata->effects) == 0) {
-        const bool declaresHeaders = std::ranges::any_of(
-            metadata->effects, [](const XpkgFilesystemEffect& effect) {
-                return effect.kind == XpkgFilesystemEffectKind::InstallHeaders;
-            });
-        if (declaresHeaders) {
-            log::debug(
-                "[xim] headers declared but '{}@{}' is not a registered "
-                "target; `xlings use` will not swap them",
-                node.name, headerVersion);
-        }
-    }
-
-    for (const auto& effect : metadata->effects) {
-        auto resolved = resolve_xpkg_filesystem_effect(
-            scopedDb, scopedWorkspace, effect);
-        if (!resolved) {
-            log::warn(
-                "validated xvm effect target disappeared or changed kind: "
-                "{}@{}",
-                effect.target, effect.version);
-            continue;
-        }
-        if (resolved->kind
-            == XpkgFilesystemEffectKind::InstallHeaders) {
-            if (!resolved->active) {
-                // Installing a non-active version must not disturb the
-                // sysroot: `xlings use` is what moves headers, and it cannot
-                // undo this because switching to an already-active version
-                // is a no-op.
-                log::debug("[xim] headers for {}@{} not installed: not the "
-                           "active version", resolved->target, resolved->version);
-                continue;
-            }
-            xvm::install_headers(
-                resolved->sourceDir, sysroot_include);
-            continue;
-        }
-        if (resolved->kind
-            == XpkgFilesystemEffectKind::RemoveHeaders) {
-            xvm::remove_headers(
-                resolved->sourceDir, sysroot_include);
-            continue;
-        }
-        if (resolved->kind
-            == XpkgFilesystemEffectKind::ProgramShim) {
-            // A shim is only meaningful for a name that has an active
-            // version -- that is what shim_dispatch resolves against, and
-            // without one the file can only ever print "no active version
-            // of 'X' in current subos". Writing it anyway is what produced
-            // doctor's `orphan shim`, an error the user could not fix:
-            // `--fix` deleted the file and the next install recreated it.
-            //
-            // Registration deliberately withholds activation from a release
-            // whose group already has an active member (see
-            // registration.cppm, `activateGroup`), so every name that is new
-            // in that release lands here. The sibling effects below already
-            // guard on activation; this one did not.
-            //
-            // The question is about the NAME, not this version: a second
-            // version of an active program must not delete or skip the shim
-            // its active sibling needs. And a name activated later still
-            // gets its file -- `cmd_use` creates shims for every member of
-            // the release it switches to (xvm/commands.cppm).
-            const auto activeIt = scopedWorkspace.find(resolved->target);
-            const bool nameHasActiveVersion =
-                activeIt != scopedWorkspace.end()
-                && !activeIt->second.empty();
-            if (!nameHasActiveVersion) {
-                log::debug(
-                    "[xim] shim for {}@{} not created: no active version of "
-                    "'{}' in this subos",
-                    resolved->target, effect.version, resolved->target);
-                continue;
-            }
-            if (std::filesystem::exists(xlings_bin)) {
-                std::string shimName = resolved->target;
-                if (!shim_ext.empty() && !shimName.ends_with(shim_ext)) {
-                    shimName += shim_ext;
-                }
-                std::filesystem::create_directories(artifactBinDir);
-                xself::create_shim(
-                    xlings_bin, artifactBinDir / shimName);
-                if (artifactBinDir
-                    != Config::global_subos_bin_dir()) {
-                    common::mirror_shim_to_global_bin(
-                        xlings_bin, shimName);
-                }
-            }
-
-            if (resolved->active
-                && xvm::is_xlings_binary(resolved->target)
-                && std::filesystem::exists(xlings_bin)
-                && !resolved->path.empty()
-                && !resolved->sourceName.empty()) {
-                auto activeName = resolved->sourceName;
-                if (!shim_ext.empty()
-                    && !activeName.ends_with(shim_ext)) {
-                    activeName += shim_ext;
-                }
-                const auto activeBin =
-                    std::filesystem::path(resolved->path)
-                    / activeName;
-                if (std::filesystem::exists(activeBin)) {
-                    // The same writer `xlings use xlings <v>` goes through.
-                    // Two independent replacements of the one file every shim
-                    // dispatches through is how a home ends up running a
-                    // client nobody chose -- see entry_binary.cppm.
-                    entry_binary::replace_with(
-                        activeBin, xlings_bin,
-                        std::format("{}@{}", resolved->target, effect.version),
-                        effect.version);
-                }
-                xself::compat::v0_4_8::cleanup_legacy_alias_shims(
-                    artifactBinDir, xlings_bin);
-            }
-            continue;
-        }
-        if (resolved->kind == XpkgFilesystemEffectKind::FileAsset) {
-            if (!resolved->active) {
-                log::debug("[xim] file asset {}@{} not placed: not the "
-                           "active version", resolved->target,
-                           resolved->version);
-                continue;
-            }
-            if (const auto file = xvm::file_placement(
-                    scopedDb, resolved->target, resolved->version);
-                !file.empty()) {
-                xvm::place_asset(file.source,
-                                 artifactSubosDir / file.destination);
-            } else {
-                log::warn("[xim] file asset {}@{} declares no usable "
-                          "destination; nothing placed",
-                          resolved->target, resolved->version);
-            }
-            continue;
-        }
-        if (resolved->kind != XpkgFilesystemEffectKind::Library
-            || resolved->path.empty()) {
-            continue;
-        }
-        if (!resolved->active) {
-            // Installing a version that does not become active must not
-            // disturb the sysroot. `InstallHeaders` has been gated this way
-            // since 0.4.70; `Library` was not, so installing a second version
-            // of a package overwrote the active version's library while its
-            // headers stayed put -- the sysroot then held a library from one
-            // release beside headers from another, which compiles and fails
-            // at run time. `xlings use` is what moves libraries.
-            log::debug("[xim] library {}@{} not placed: not the active "
-                       "version", resolved->target, resolved->version);
-            continue;
-        }
-
-        const auto source =
-            std::filesystem::path(resolved->path)
-            / resolved->sourceName;
-        const auto destination =
-            sysroot_lib / resolved->destinationName;
-        std::filesystem::create_directories(sysroot_lib);
-        std::error_code ec;
-        if (std::filesystem::exists(destination, ec)
-            || std::filesystem::is_symlink(destination, ec)) {
-            std::filesystem::remove(destination, ec);
-        }
-        ec.clear();
-        if (std::filesystem::exists(source, ec)) {
-            std::filesystem::create_symlink(
-                source, destination, ec);
-        }
-    }
-
-    cleanup_removed_xvm_program_artifacts(
-        artifactBinDir,
-        dbBeforeRemoval,
-        scopedDb,
-        scopedInstalled,
-        metadata->removal);
-
-    // Announce any owner-less entry this install took over.
-    //
-    // Adoption replaces the contents recorded for a name@version that an
-    // older client wrote without ownership (xvm/registration.cppm). It is the
-    // right thing to do — the refusal it replaced left the user with no exit
-    // (#422) — but it is still a payload changing behind a name, so it is
-    // said out loud rather than applied silently.
-    for (const auto& member : metadata->registered) {
-        if (!member.adoptedLegacy) continue;
-        log::warn("[xvm] adopted a pre-ownership registration: {}@{} ('{}' changed)",
-                  member.target, member.version, member.adoptedLegacyField);
-    }
-
-    // Announce anything the batch left behind rather than refused over.
-    //
-    // These are names an older client registered for this same payload on a
-    // platform whose recipe produces them and this one's does not (a Windows
-    // llvm leaves `cl`, `lib`, `link`, `rc`). They keep their record and lose
-    // their edge to this release; `self doctor` reports them and can prune
-    // them. Silence here would make a release quietly shed members.
-    for (const auto& member : metadata->detachedLegacy) {
-        log::warn("[xvm] detached a legacy entry this platform no longer "
-                  "registers: {} (run `xlings self doctor --fix` to clear it)",
-                  xvm::display_coordinate(member.target, member.version));
-    }
-
-    if (!metadata->removal.removed.empty()
-        || !metadata->registered.empty()) {
-        Config::save_versions();
-        Config::save_workspace();
-    }
-    return true;
-}
+                             bool useAfterInstall);
 
 bool run_config_hook_(const PlanNode& node,
                       const std::filesystem::path& dataDir,
@@ -2173,25 +436,7 @@ bool run_config_hook_(const PlanNode& node,
                       mcpplibs::xpkg::ExecutionContext& ctx,
                       std::function<void(const InstallStatus&)> onStatus,
                       bool useAfterInstall,
-                      std::string* failureMessage = nullptr) {
-    if (!executor.has_hook(mcpplibs::xpkg::HookType::Config)) return true;
-    if (onStatus) {
-        onStatus({ node.name, InstallPhase::Configuring, 0.8f, "" });
-    }
-    ScopedCurrentDir_ configCwd(ctx.install_dir);
-    auto hookResult = executor.run_hook(mcpplibs::xpkg::HookType::Config, ctx);
-    if (!hookResult.success) {
-        if (failureMessage) {
-            *failureMessage = format_hook_failure("config", hookResult);
-        }
-        return false;
-    }
-    if (!process_xvm_operations_(node, dataDir, executor, useAfterInstall)) {
-        if (failureMessage) *failureMessage = "config hook failed";
-        return false;
-    }
-    return true;
-}
+                      std::string* failureMessage = nullptr);
 
 // A package that promised programs and delivered none of them.
 //
@@ -2214,34 +459,7 @@ bool run_config_hook_(const PlanNode& node,
 // recipes routinely declare one cross-platform program list and register the
 // subset that exists on this host. Zero out of N is what never has a benign
 // reading -- the package cannot do the thing it exists to do.
-std::vector<std::string> unfulfilled_program_promises_(const InstallPlan& plan) {
-    std::vector<std::string> broken;
-    // By value, per Config::versions()'s contract -- it merges global and
-    // project state into a fresh map, so a reference into the temporary would
-    // dangle at the end of the full expression.
-    const auto db = Config::versions();
-
-    for (const auto& node : plan.nodes) {
-        // Build-only deps are intentionally never registered or shimmed.
-        if (node.kind == DepKind::Build) continue;
-        if (node.programs.empty()) continue;
-
-        const bool anyRegistered = std::ranges::any_of(
-            node.programs,
-            [&](const std::string& prog) { return xvm::has_target(db, prog); });
-        if (anyRegistered) continue;
-
-        std::string names;
-        for (const auto& prog : node.programs) {
-            if (!names.empty()) names += ", ";
-            names += prog;
-        }
-        log::error("{} installed but registered none of the programs it "
-                   "declares: {}", node.name, names);
-        broken.push_back(node.name);
-    }
-    return broken;
-}
+std::vector<std::string> unfulfilled_program_promises_(const InstallPlan& plan);
 
 }  // namespace detail_
 
@@ -2252,8 +470,8 @@ class Installer {
     PackageCatalog* catalog_ { nullptr };
 
 public:
-    explicit Installer(IndexManager& index) : index_(&index) {}
-    explicit Installer(PackageCatalog& catalog) : catalog_(&catalog) {}
+    explicit Installer(IndexManager& index);
+    explicit Installer(PackageCatalog& catalog);
 
     // Resolve a build_deps entry (e.g. "gcc", "ns:gcc@15") to its
     // payload directory inside xpkgs/<store>/<version>. Plan is in topo
@@ -2262,28 +480,7 @@ public:
     static std::filesystem::path
     locate_dep_install_dir_(const InstallPlan& plan,
                             const std::filesystem::path& dataDir,
-                            std::string_view depRef) {
-        auto at = depRef.find('@');
-        auto baseRef = (at == std::string_view::npos) ? depRef
-                                                       : depRef.substr(0, at);
-        auto colon = baseRef.find(':');
-        std::string ns = (colon == std::string_view::npos)
-            ? std::string{}
-            : std::string(baseRef.substr(0, colon));
-        std::string bare = (colon == std::string_view::npos)
-            ? std::string(baseRef)
-            : std::string(baseRef.substr(colon + 1));
-        for (auto& n : plan.nodes) {
-            bool match = (n.name == bare)
-                       || (n.canonicalName == baseRef)
-                       || (n.rawName == depRef);
-            if (!ns.empty()) match = match && (n.namespaceName == ns);
-            if (!match) continue;
-            auto root = n.storeRoot.empty() ? (dataDir / "xpkgs") : n.storeRoot;
-            return root / detail_::effective_store_name_(n) / n.version;
-        }
-        return {};
-    }
+                            std::string_view depRef);
 
     // Execute an install plan.
     // useAfterInstall: when true, force the installed program version to
@@ -2296,897 +493,7 @@ public:
             InstallRequestHandler onInstallRequests = nullptr,
             DownloadProgressRenderer onRender = nullptr,
             CancellationToken* cancel = nullptr,
-            bool useAfterInstall = false) {
-
-        if (plan.has_errors()) {
-            return std::unexpected(
-                std::format("plan has errors: {}", plan.errors[0]));
-        }
-
-        auto dataDir = Config::paths().dataDir;
-        auto platform = detect_platform_();
-
-        // Phase 1: Collect download tasks for non-installed packages
-        log::debug("installer: {} node(s) in plan, dataDir={}", plan.nodes.size(), dataDir.string());
-        std::vector<DownloadTask> dlTasks;
-        std::unordered_set<std::string> plannedDownloads;
-        // Nodes a gate below refused. Phase 2 walks plan.nodes again and is
-        // otherwise unaware of anything decided here, so `continue` alone
-        // only skips the download -- the package still runs install() and
-        // config() and ends up registered. This set is what makes a refusal
-        // mean refused.
-        std::unordered_set<std::string> refusedNodes;
-        for (auto& node : plan.nodes) {
-            if (node.alreadyInstalled) continue;
-
-            const std::string hostArch =
-                mcpplibs::xpkg::normalize_arch(detail_::detect_arch_());
-            auto pkg = mcpplibs::xpkg::load_package(node.pkgFile, {
-                .platform = platform,
-                .arch = hostArch,
-            });
-            if (!pkg) {
-                log::warn("skipping {}: {}", node.name, pkg.error());
-                continue;
-            }
-
-            // Refuse a recipe written against a spec this build does not
-            // implement, rather than falling through to V1 semantics.
-            //
-            // Install only. An already-installed package whose recipe later
-            // moved past us must still be removable -- taking something out
-            // needs no understanding of the spec that put it in.
-            const auto specSupport = xpkg_spec_support(pkg->spec);
-            if (!specSupport.supported) {
-                if (specSupport.declared > 0) {
-                    log::error("{}: xpackage spec \"{}\" is newer than this "
-                               "xlings understands (max {})",
-                               node.name, pkg->spec, max_supported_xpkg_spec);
-                    log::info("try: xlings self update");
-                } else {
-                    log::error("{}: unreadable xpackage spec \"{}\"",
-                               node.name, pkg->spec);
-                }
-                refusedNodes.insert(detail_::plan_key_(node));
-                continue;
-            }
-
-            // Asked of the resource this node is about to download, not of
-            // the package-level `archs` union: a recipe whose macOS entry is a
-            // darwin-arm64 tarball is installable on arm64 no matter what the
-            // union says, and a V1 recipe with an under-declared union must
-            // not be refused on the strength of a field nothing ever enforced.
-            const auto* entry = find_entry(*pkg, platform, node.version);
-            const auto compatibility = check_target_compatibility(
-                *pkg, entry, platform, hostArch);
-            if (!compatibility.supported) {
-                log::error("{}", compatibility_error(node.canonicalName,
-                                                       compatibility));
-                refusedNodes.insert(detail_::plan_key_(node));
-                continue;
-            }
-            if (!compatibility.advisory.empty()) {
-                log::warn("{}", compatibility.advisory);
-            }
-
-            auto resource = detail_::resolve_download_resource_(
-                pkg->xpm, node.name, node.version, platform, hostArch,
-                dlConfig.preferredMirror);
-            if (!resource) {
-                log::warn("skipping {}: {}", node.name, resource.error());
-                continue;
-            }
-
-            DownloadTask task;
-            task.name = detail_::plan_key_(node);
-            task.url = resource->url;
-            task.sha256 = resource->sha256;
-            task.cacheIdentity = std::format(
-                "{}/{}/{}/{}/{}",
-                node.name, resource->version, platform, hostArch,
-                resource->useResFallbacks ? "xlings-res" : resource->url);
-            task.destDir = detail_::runtime_dir_(node, dataDir);
-
-            if (resource->useResFallbacks) {
-                task.fallbackUrls = detail_::build_xlings_res_fallback_urls_(
-                    node.name, resource->version, platform);
-            }
-
-            // Add remaining mirrors as fallbacks
-            if (!resource->mirrors.empty()) {
-                for (auto& [key, mirrorUrl] : resource->mirrors) {
-                    if (mirrorUrl != resource->url) {
-                        task.fallbackUrls.push_back(mirrorUrl);
-                    }
-                }
-            }
-            plannedDownloads.insert(task.name);
-            dlTasks.push_back(std::move(task));
-        }
-
-        std::unordered_map<std::string, DownloadResult> downloadResults;
-
-        // Download all
-        if (!dlTasks.empty()) {
-            log::debug("downloading {} package(s)...", dlTasks.size());
-            auto results = download_all(dlTasks, dlConfig, onRender,
-                [&](std::string_view name, float progress) {
-                    if (onStatus) {
-                        InstallStatus status;
-                        status.name = std::string(name);
-                        status.phase = progress >= 0
-                            ? InstallPhase::Downloading
-                            : InstallPhase::Failed;
-                        status.progress = std::max(0.0f, progress);
-                        onStatus(status);
-                    }
-                }, cancel);
-
-            for (auto& r : results) {
-                if (!r.success) {
-                    log::error("download failed for {}: {}", r.name, r.error);
-                } else {
-                    downloadResults[r.name] = r;
-                }
-            }
-        }
-
-        // The host glibc this subos recorded at creation, for rule A of the
-        // closure check below. Read once per plan: the manifest cannot change
-        // mid-install, and unknown (empty) stays unknown.
-        std::optional<std::string> hostGlibcCache;
-        auto host_glibc_recorded = [&]() -> const std::string& {
-            if (!hostGlibcCache) {
-                namespace mf = xlings::subos::manifest;
-                hostGlibcCache.emplace();
-                if (auto doc = mf::read_document(Config::xvm_artifact_subos_dir()))
-                    *hostGlibcCache = mf::parse(*doc).host_glibc;
-            }
-            return *hostGlibcCache;
-        };
-
-        // Every payload the ledger references, built once for the whole plan.
-        // Rebuilt per node it would be O(nodes x DB); the plan cannot register
-        // anything before phase 2 starts, so one snapshot is correct for the
-        // skip decision -- and the decision is about what a PREVIOUS run left
-        // behind, which is exactly what this snapshot holds.
-        const auto ledgerIndex = LedgerIndex(
-            Config::versions(), Config::paths().homeDir.string());
-
-        // Phase 2: Install each package in topological order
-        for (auto& node : plan.nodes) {
-            // Refused by a gate in phase 1. Skipping here rather than there
-            // is what keeps the refusal per-package: the rest of the plan
-            // installs normally.
-            if (refusedNodes.contains(detail_::plan_key_(node))) continue;
-            if (cancel && cancel->is_cancelled()) {
-                return std::unexpected(std::string("cancelled"));
-            }
-            if (onStatus) {
-                onStatus({ node.name, InstallPhase::Installing, 0.5f, "" });
-            }
-
-            // Create executor and run hooks
-            auto execResult = mcpplibs::xpkg::create_executor(node.pkgFile);
-            if (!execResult) {
-                log::error("failed to create executor for {}: {}",
-                           node.name, execResult.error());
-                if (onStatus) {
-                    onStatus({ node.name, InstallPhase::Failed, 0.0f,
-                               execResult.error() });
-                }
-                continue;
-            }
-
-            auto& executor = *execResult;
-            executor.set_log_level(std::string(log::level_string()));
-
-            // Build execution context
-            mcpplibs::xpkg::ExecutionContext ctx;
-            ctx.pkg_name = node.name;
-            ctx.version = node.version;
-            ctx.platform = platform;
-            auto targetRoot = node.storeRoot.empty() ? (dataDir / "xpkgs") : node.storeRoot;
-            ctx.install_dir = targetRoot / detail_::effective_store_name_(node) / node.version;
-            detail_::configure_xpkg_execution_artifact_paths_(
-                ctx);
-            detail_::configure_dependency_store_roots_(ctx, targetRoot);
-            ctx.xpkg_dir = node.pkgFile.parent_path();
-            ctx.project_data_dir = Config::project_data_dir();
-            // pkgindex_dir: package index repo root (for custom module loading).
-            // pkgFile layout: <pkgindex>/pkgs/<letter>/<name>.lua → 3 levels up.
-            bool pkgindexHasLibs = false;
-            ctx.pkgindex_dir =
-                detail_::pkgindex_root_for_(node.pkgFile, &pkgindexHasLibs);
-            if (!pkgindexHasLibs) {
-                // Loud, because the alternative is a package that installs
-                // "successfully" with none of its sysroot assets declared.
-                log::warn("{}: no pkgindex libs/ found -- every "
-                          "`xim.pkgindex.*` call in this recipe will be a "
-                          "silent no-op (sysroot assets, driver dirs and "
-                          "EGL/Vulkan manifests will NOT be declared)",
-                          node.name);
-            }
-            ctx.deps_list = node.deps;                  // legacy union (compat)
-            ctx.runtime_deps_list = node.runtime_deps;  // split form
-            ctx.build_deps_list   = node.build_deps;
-
-            // self_exports: pre-resolve relative paths to absolute by
-            // joining with this package's own install_dir.
-            if (!node.exports.loader.empty()) {
-                ctx.self_exports.loader = (ctx.install_dir / node.exports.loader).string();
-            }
-            ctx.self_exports.abi = node.exports.abi;
-            for (auto& d : node.exports.libdirs) {
-                ctx.self_exports.libdirs.push_back((ctx.install_dir / d).string());
-            }
-
-            // deps_exports: walk the topo plan to find each runtime dep
-            // node and pull its exports (already populated by resolver).
-            // Resolve relative paths against THAT dep's install_dir, not
-            // ours. Strip @version when matching dep_spec → dep node, so
-            // a runtime_deps entry "xim:glibc@2.39" matches the plan
-            // node whose canonicalName == "xim:glibc" + version "2.39".
-            //
-            // The version half is a RANGE, not a literal. `xim:glibc@>=2.38`
-            // resolves to the node at 2.39, and comparing the two as strings
-            // makes them unequal -- so the dep matched no node, contributed no
-            // exports, and elfpatch's predicate concluded "no loader provider
-            // in deps" and patched nothing at all. The package installs
-            // reporting success and is unusable: its own libraries keep a
-            // build-time RPATH, so anything dlopen'd out of it fails to find
-            // its siblings. Nothing in the output says so.
-            //
-            // Every recipe in the index pinned exactly, which is why this held
-            // for as long as it did. Ranges are the documented syntax, and the
-            // resolver already honours them -- this one comparison did not.
-            for (auto& dep_spec : node.runtime_deps) {
-                std::string dep_base = dep_spec;
-                std::string dep_ver;
-                if (auto at = dep_base.find('@'); at != std::string::npos) {
-                    dep_ver = dep_base.substr(at + 1);
-                    dep_base.resize(at);
-                }
-                for (auto& depNode : plan.nodes) {
-                    bool name_match = (depNode.canonicalName == dep_base
-                                    || depNode.name == dep_base
-                                    || depNode.rawName == dep_base);
-                    if (!name_match
-                        || !detail_::dep_version_matches_(depNode.version,
-                                                          dep_ver)) {
-                        continue;
-                    }
-                    auto depRoot = depNode.storeRoot.empty()
-                        ? (dataDir / "xpkgs") : depNode.storeRoot;
-                    auto depInstallDir = depRoot
-                        / detail_::effective_store_name_(depNode) / depNode.version;
-
-                    // Recorded for EVERY runtime dep, declared exports or not.
-                    //
-                    // This used to `break` here when a dep declared nothing,
-                    // throwing away the depInstallDir just computed — and the
-                    // consumer then re-derived it from the dep's name, which
-                    // is a second answer to a question that has one. With two
-                    // versions of a package installed the two answers differ,
-                    // and the product is a binary whose interpreter comes from
-                    // one payload and whose RUNPATH from another. It faults
-                    // before main and blames a GLIBC_PRIVATE symbol.
-                    //
-                    // Design and the six edge cases the assertion below must
-                    // honour:
-                    // .agents/docs/2026-08-05-dependency-resolution-single-source.md
-                    mcpplibs::xpkg::ResolvedDep r;
-                    r.spec        = dep_spec;
-                    r.name        = depNode.canonicalName.empty()
-                                        ? depNode.name : depNode.canonicalName;
-                    r.version     = depNode.version;
-                    r.install_dir = depInstallDir.string();
-                    r.source      = dep_ver.empty()            ? "plan-any"
-                                  : dep_ver == depNode.version ? "plan-exact"
-                                                               : "plan-range";
-                    if (!depNode.exports.libdirs.empty()) {
-                        for (auto& d : depNode.exports.libdirs) {
-                            r.libdirs.push_back((depInstallDir / d).string());
-                        }
-                    } else {
-                        // The {lib64, lib} convention, applied HERE and only
-                        // here. It used to be applied by each consumer, which
-                        // is how a convention becomes a second resolver.
-                        for (const auto* sub : {"lib64", "lib"}) {
-                            auto cand = depInstallDir / sub;
-                            if (std::filesystem::is_directory(cand)) {
-                                r.libdirs.push_back(cand.string());
-                                break;
-                            }
-                        }
-                    }
-                    ctx.resolved_deps[dep_spec] = std::move(r);
-
-                    if (depNode.exports.loader.empty() && depNode.exports.libdirs.empty()) {
-                        // Nothing declared: no DepExport entry, by design.
-                        // The resolved record above is what consumers use.
-                        break;
-                    }
-                    mcpplibs::xpkg::DepExport e;
-                    if (!depNode.exports.loader.empty()) {
-                        e.loader = (depInstallDir / depNode.exports.loader).string();
-                    }
-                    e.abi = depNode.exports.abi;
-                    for (auto& d : depNode.exports.libdirs) {
-                        e.libdirs.push_back((depInstallDir / d).string());
-                    }
-                    ctx.deps_exports[dep_spec] = std::move(e);
-                    break;
-                }
-            }
-
-            auto planKey = detail_::plan_key_(node);
-            auto dlIt = downloadResults.find(planKey);
-
-            std::optional<std::filesystem::path> extractedRoot;
-            if (plannedDownloads.contains(planKey) && dlIt == downloadResults.end()) {
-                log::error("download artifact missing for {}", node.name);
-                if (onStatus) {
-                    onStatus({ node.name, InstallPhase::Failed, 0.0f, "download artifact missing" });
-                }
-                continue;
-            }
-            // run_dir is the user's working directory (where xlings was invoked),
-            // not the download/runtime directory. Hooks use it for resolving
-            // relative paths and determining project install locations.
-            ctx.run_dir = std::filesystem::current_path();
-
-            if (dlIt != downloadResults.end()) {
-                ctx.install_file = dlIt->second.localFile;
-                if (detail_::is_archive_(dlIt->second.localFile)) {
-                    if (onStatus) {
-                        onStatus({ node.name, InstallPhase::Extracting, 0.35f, "" });
-                    }
-                    // Extract into the same runtime dir as the download
-                    auto runtimeDir = dlIt->second.localFile.parent_path();
-                    auto extracted = extract_archive_detailed(
-                        dlIt->second.localFile, runtimeDir);
-                    if (!extracted) {
-                        auto error = std::move(extracted).error();
-                        if (evict_invalid_archive_cache_(
-                                dlIt->second.localFile, error)) {
-                            log::warn(
-                                "evicted invalid archive cache for {}: {}",
-                                node.name, dlIt->second.localFile.string());
-                        }
-                        log::error("extract failed for {}: {}",
-                                   node.name, error.message);
-                        if (onStatus) {
-                            onStatus({
-                                node.name, InstallPhase::Failed, 0.0f,
-                                error.message});
-                        }
-                        continue;
-                    }
-                    extractedRoot = *extracted;
-                }
-            }
-            // No download artifact: install_file stays empty (type-only packages
-            // like auto-config don't need a payload).  Do NOT fall back to
-            // node.pkgFile — that is the package *definition* file; an install
-            // hook calling os.mv(install_file, install_dir) would move it out
-            // of the package index, destroying the index entry.
-
-            // Ensure install_dir exists so hooks can mv/cp into it
-            {
-                std::error_code ec;
-                std::filesystem::create_directories(ctx.install_dir, ec);
-                // A genuine failure here (commonly EACCES on a root-owned
-                // dir left by a prior `sudo` install) used to be swallowed,
-                // surfacing later as a confusing hook failure. Surface it.
-                if (ec && !std::filesystem::is_directory(ctx.install_dir)) {
-                    log::warn("create install dir {} failed: {}",
-                              ctx.install_dir.string(), ec.message());
-                }
-            }
-
-            // A payload that belongs to another platform is not installed,
-            // whatever the records say. Only a PROVABLE mismatch overrides
-            // them: Unknown (scripts, data, a type-only package) keeps the
-            // fast path, so nothing that works today starts reinstalling.
-            const auto payloadVerdict =
-                classify_payload_platform(ctx.install_dir);
-            const bool foreignPayload =
-                payloadVerdict == PayloadPlatform::Foreign;
-            if (foreignPayload) {
-                log::warn("{}: installed payload is not for {} — reinstalling",
-                          node.name, host_platform_tag());
-                log::warn("  payload: {}",
-                          Config::display_path(ctx.install_dir));
-            }
-
-            bool payloadInstalled = node.alreadyInstalled && !foreignPayload;
-
-            // Check if already installed via hook
-            if (foreignPayload) {
-                // The hooks below all answer "is it installed", and every one
-                // of them would say yes about the wrong platform's files.
-            }
-            else if (!payloadInstalled && executor.has_hook(mcpplibs::xpkg::HookType::Installed)) {
-                auto hookResult = executor.check_installed(ctx);
-                if (hookResult.success && !hookResult.version.empty()) {
-                    log::debug("{} already installed (version {})",
-                              node.name, hookResult.version);
-                    payloadInstalled = true;
-                }
-            }
-            // Default: check xvm version database when no installed hook.
-            //
-            // Trust-but-verify: a DB entry alone isn't enough. If the
-            // payload directory the entry points to is missing or empty
-            // (broken-payload state — payload manually rm'd, partial
-            // uninstall, FS corruption), fall through and let the install
-            // hook re-create the payload.  Without this fall-through,
-            // `xlings install <pkg>@<ver>` reports success without
-            // actually doing anything — the user can never recover from
-            // a broken payload via the obvious command.
-            else if (!payloadInstalled) {
-                auto db = Config::versions();
-                auto resolved = xvm::match_version(db, node.name, node.version);
-                if (!resolved.empty()) {
-                    bool payload_ok = true;
-                    if (auto* vdata = xvm::get_vdata(db, node.name, resolved);
-                        vdata && !vdata->path.empty()) {
-                        auto expanded = xvm::expand_path(
-                            vdata->path, Config::paths().homeDir.string());
-                        std::error_code ec;
-                        payload_ok = std::filesystem::is_directory(expanded, ec)
-                                  && payload_has_content(expanded);
-                    }
-                    if (payload_ok) {
-                        log::debug("{} already installed in xvm (version {})",
-                                  node.name, resolved);
-                        payloadInstalled = true;
-                    } else {
-                        log::debug("{} registered as {} in xvm but payload "
-                                  "missing — re-running install hook",
-                                  node.name, resolved);
-                    }
-                }
-            }
-
-            // The one that closes #541 ①.
-            //
-            // Everything above answers "is there a payload here". A hook that
-            // failed halfway leaves one, so every check above says yes and the
-            // hook is never re-run: the repair command's own precondition is
-            // satisfied by the wreckage it exists to clear. `installation_state`
-            // asks whether the payload and the records AGREE, and re-runs the
-            // hook when they do not.
-            //
-            // Positive evidence only -- a stamp that predates the `registered`
-            // field yields no verdict, so a home installed by an older client
-            // does not start reinstalling itself. See install_state.cppm.
-            if (payloadInstalled && !foreignPayload) {
-                const auto state = installation_state(
-                    ledgerIndex, node.namespaceName, node.name, node.version,
-                    ctx.install_dir);
-                if (state.is_incomplete()) {
-                    log::warn("[{}@{}] previous install left an incomplete "
-                              "state ({}); running its install hook again",
-                              node.name, node.version, state.reason);
-                    payloadInstalled = false;
-                }
-            }
-
-            // Run install hook
-            if (!payloadInstalled && executor.has_hook(mcpplibs::xpkg::HookType::Install)) {
-                log::debug("installing {}...", node.name);
-                log::debug("installer: install_dir={}", ctx.install_dir.string());
-                // Set cwd to the download/runtime directory so hooks can
-                // find downloaded files via relative paths.  ctx.run_dir
-                // (user's original cwd) is exposed via system.rundir().
-                // When there is no download artifact we fall back to the
-                // runtime dir rather than install_dir: hooks commonly start
-                // with os.tryrm(install_dir) to get a clean slate, which
-                // would delete the CWD and cause subsequent getcwd() calls
-                // to fail.
-                auto hookCwd = (dlIt != downloadResults.end())
-                    ? dlIt->second.localFile.parent_path()
-                    : detail_::runtime_dir_(node, dataDir); // fallback to runtime dir
-                detail_::ScopedCurrentDir_ installCwd(hookCwd);
-
-                // Inject XLINGS_BUILDDEP_<UPPER>_PATH for every build_dep
-                // declared by this node, and prepend their bin/ dirs to
-                // PATH for the duration of the hook. The hook (and any
-                // subprocess it spawns) sees both forms; xpkg-side
-                // pkginfo.build_dep() picks the env path first.
-                std::string oldPath = std::getenv("PATH") ? std::getenv("PATH") : "";
-                std::vector<std::string> setEnvKeys;
-                std::string newPath = oldPath;
-                for (auto& bd : node.build_deps) {
-                    auto bdDir = locate_dep_install_dir_(plan, dataDir, bd);
-                    if (bdDir.empty()) {
-                        log::debug("[{}] build_dep '{}' not found in plan",
-                                   node.name, bd);
-                        continue;
-                    }
-                    std::string nameOnly = bd;
-                    if (auto a = nameOnly.find('@'); a != std::string::npos)
-                        nameOnly.resize(a);
-                    if (auto c = nameOnly.find(':'); c != std::string::npos)
-                        nameOnly = nameOnly.substr(c + 1);
-                    std::string upper;
-                    upper.reserve(nameOnly.size());
-                    for (char c : nameOnly) {
-                        upper += std::isalnum(static_cast<unsigned char>(c))
-                            ? static_cast<char>(std::toupper(static_cast<unsigned char>(c)))
-                            : '_';
-                    }
-                    auto envKey = "XLINGS_BUILDDEP_" + upper + "_PATH";
-                    platform::set_env_variable(envKey, bdDir.string());
-                    setEnvKeys.push_back(envKey);
-                    auto bdBin = (bdDir / "bin").string();
-                    if (std::filesystem::exists(bdDir / "bin")) {
-                        newPath = bdBin + std::string(1, platform::PATH_SEPARATOR) + newPath;
-                    }
-                    log::debug("[{}] build_dep {} -> {} (env {})",
-                               node.name, bd, bdDir.string(), envKey);
-                }
-                if (!setEnvKeys.empty()) {
-                    platform::set_env_variable("PATH", newPath);
-                }
-
-                auto hookResult = executor.run_hook(
-                    mcpplibs::xpkg::HookType::Install, ctx);
-
-                // Restore env regardless of hook outcome
-                if (!setEnvKeys.empty()) {
-                    platform::set_env_variable("PATH", oldPath);
-                    for (auto& k : setEnvKeys) {
-                        platform::set_env_variable(k, "");
-                    }
-                }
-
-                if (!hookResult.success) {
-                    auto message = detail_::format_hook_failure(
-                        "install", hookResult);
-                    // Record the failure ON the payload. Without this the next
-                    // `xlings install` finds a non-empty directory, concludes
-                    // "already installed", skips the hook, and reports success
-                    // -- the state #541 ① calls permanently stuck. The payload
-                    // is the only place the next run is guaranteed to look.
-                    write_payload_failure_marker(
-                        ctx.install_dir, node.version, message);
-                    if (onStatus) {
-                        onStatus({ node.name, InstallPhase::Failed, 0.0f,
-                                   std::move(message) });
-                    }
-                    continue;
-                }
-            } else if (!payloadInstalled && node.pkgType == 1 /* Script */) {
-                log::debug("installing script {}...", node.name);
-                if (!script::default_install(node, ctx)) {
-                    if (onStatus) {
-                        onStatus({ node.name, InstallPhase::Failed, 0.0f,
-                                   "default script install failed" });
-                    }
-                    continue;
-                }
-            } else if (!payloadInstalled && node.pkgType == 4 /* Subos */) {
-                log::debug("installing subos base {}...", node.name);
-                if (!subos::default_install(node, ctx)) {
-                    if (onStatus) {
-                        onStatus({ node.name, InstallPhase::Failed, 0.0f,
-                                   "default subos install failed" });
-                    }
-                    continue;
-                }
-            }
-
-            if (!payloadInstalled && extractedRoot && !detail_::has_directory_entries_(ctx.install_dir)) {
-                if (!detail_::stage_extracted_payload_(*extractedRoot, ctx.install_dir)) {
-                    log::error("failed to stage extracted payload for {}", node.name);
-                    write_payload_failure_marker(
-                        ctx.install_dir, node.version,
-                        "failed to stage extracted payload");
-                    if (onStatus) {
-                        onStatus({ node.name, InstallPhase::Failed, 0.0f,
-                                   "failed to stage extracted payload" });
-                    }
-                    continue;
-                }
-            }
-
-            if (!payloadInstalled && !detail_::normalize_file_install_(ctx.install_dir)) {
-                log::error("failed to normalize file install layout for {}", node.name);
-                write_payload_failure_marker(
-                    ctx.install_dir, node.version,
-                    "failed to normalize file install layout");
-                if (onStatus) {
-                    onStatus({ node.name, InstallPhase::Failed, 0.0f,
-                               "failed to normalize file install layout" });
-                }
-                continue;
-            }
-
-            // Auto-stamp: drop a `.xim-installed` marker in install_dir if
-            // it's still empty after every install path (hook + extracted-
-            // payload fallback + script default). Wrapper packages
-            // (linux-headers, fromsource:* aliases) legitimately leave
-            // install_dir empty because their real payload lives in a
-            // separately-installed dep — without a stamp, xlings's
-            // installed-probe (`is_directory && !is_empty`) reports
-            // "not installed" and re-runs install + config on every
-            // dependent install. Critical: this MUST come after
-            // stage_extracted_payload_ above; otherwise a stamp written
-            // earlier would falsely make install_dir look "non-empty"
-            // and skip the extracted-payload fallback (which exists for
-            // packages whose hook silently no-ops, e.g. patchelf where
-            // the tarball has no top-level dir).
-            if (!payloadInstalled && node.pkgType != 3 /* Config */) {
-                // TODO(config): formalize config packages as repeatable,
-                // no-install procedures in libxpkg/spec. Keep current hook
-                // semantics for now; just avoid xlings-owned markers that
-                // would make an otherwise empty config directory look
-                // installed.
-                executor.apply_install_stamp_if_empty(ctx);
-            }
-
-            // Record which platform produced this payload. Written on every
-            // path that just installed one, and also when the fast path was
-            // taken and the heuristic had to be consulted -- that second case
-            // is the self-heal: a pre-stamp payload is classified once and
-            // never again.
-            // Record which platform produced this payload -- but ONLY after a
-            // path that actually installed one, and only if the files on disk
-            // agree. Stamping unconditionally is worse than not stamping at
-            // all: an install hook that started with os.tryrm(install_dir) and
-            // then had no artifact to unpack (the shape a foreign payload
-            // reaches here in) would leave an empty directory carrying this
-            // platform's stamp, and every later run would believe it.
-            if (!payloadInstalled && node.pkgType != 3 /* Config */
-                && classify_payload_content(ctx.install_dir)
-                       != PayloadPlatform::Foreign) {
-                write_payload_stamp(ctx.install_dir, node.version);
-            }
-
-            // Apply elfpatch auto-patching if the install hook enabled it
-            if (!payloadInstalled) {
-                // Ensure binDir is in PATH so elfpatch can find patchelf
-                auto binDir = ctx.bin_dir.string();
-                auto curPath = std::string(std::getenv("PATH") ? std::getenv("PATH") : "");
-                if (!binDir.empty() && curPath.find(binDir) == std::string::npos) {
-                    platform::set_env_variable("PATH",
-                        binDir + std::string(1, platform::PATH_SEPARATOR) + curPath);
-                }
-                auto epResult = executor.apply_elfpatch_auto();
-                if (epResult.success && !epResult.output.empty()) {
-                    log::debug("{}: elfpatch auto: {}", node.name, epResult.output);
-                } else if (!epResult.success) {
-                    log::debug("{}: elfpatch auto failed: {}", node.name, epResult.error);
-                }
-
-                // The invariant, checked on what elfpatch actually wrote
-                // rather than on what it was asked to write.
-                //
-                // Everything above is supposed to make a violation
-                // unconstructible. This is the layer that does not take that
-                // on trust — and it is cheap, a string compare per ELF. What
-                // it replaces is a segmentation fault in the user's terminal
-                // days later, reported as an undefined GLIBC_PRIVATE symbol
-                // that names neither a package nor a version.
-                // The decision, kept as data next to what it produced.
-                //
-                // A log line answers "why is it 2.39 here" only for as long
-                // as someone still has the log and the store has not moved
-                // on. Anything that has to be reproduced to be inspected is
-                // not traceable — and reproducing THIS means recreating a
-                // store state, which is the thing that varies.
-                if (!ctx.resolved_deps.empty()) {
-                    nlohmann::json rec;
-                    rec["package"] = std::format("{}@{}", node.name, node.version);
-                    rec["deps"] = nlohmann::json::array();
-                    // Sorted, so two installs of the same plan produce the
-                    // same bytes and a diff between homes means something.
-                    std::vector<std::string> specs;
-                    for (const auto& [spec, _] : ctx.resolved_deps)
-                        specs.push_back(spec);
-                    std::ranges::sort(specs);
-                    for (const auto& spec : specs) {
-                        const auto& r = ctx.resolved_deps.at(spec);
-                        rec["deps"].push_back({
-                            {"spec",        r.spec},
-                            {"name",        r.name},
-                            {"version",     r.version},
-                            {"install_dir", r.install_dir},
-                            {"libdirs",     r.libdirs},
-                            {"source",      r.source},
-                        });
-                    }
-                    std::error_code wec;
-                    if (std::filesystem::is_directory(ctx.install_dir, wec)) {
-                        std::ofstream out(ctx.install_dir / ".xlings-resolution.json");
-                        if (out) out << rec.dump(2) << '\n';
-                    }
-                }
-
-                if (auto bad = elfcheck::scan_payload(ctx.install_dir);
-                    !bad.empty()) {
-                    for (const auto& f : bad) {
-                        log::error("{}", elfcheck::describe(f));
-                    }
-                    log::error("  this is a resolution defect, not a bad "
-                               "payload -- report it with the two paths above");
-                    return std::unexpected(std::format(
-                        "{}@{}: loader/libc payload mismatch in {} binary(ies)",
-                        node.name, node.version, bad.size()));
-                }
-            }
-
-            // Process deferred pkgmanager.install()/remove() requests synchronously
-            // before config hook, so config can access sub-dependencies
-            {
-                auto reqs = executor.install_requests();
-                if (!reqs.empty() && onInstallRequests) {
-                    for (auto& req : reqs) {
-                        log::debug("[{}] deferred {}: {}", node.name, req.op, req.target);
-                    }
-                    onInstallRequests(reqs);
-                }
-            }
-
-            if (node.kind == DepKind::Build) {
-                // Build-only deps: payload is on disk and resolvable via
-                // pkginfo.build_dep() / XLINGS_BUILDDEP_*_PATH. We skip
-                // config hook + xvm operations entirely so the dep does
-                // NOT take over a workspace slot or get a PATH shim.
-                log::debug("[{}] kind=Build: skipping config hook / workspace activation",
-                           node.name);
-            } else if (!executor.has_hook(mcpplibs::xpkg::HookType::Config) && node.pkgType == 1 /* Script */) {
-                if (!script::default_config(
-                        node,
-                        dataDir,
-                        detail_::version_namespace_(node.namespaceName))) {
-                    if (onStatus) {
-                        onStatus({ node.name, InstallPhase::Failed, 0.0f,
-                                   "default script config failed" });
-                    }
-                    continue;
-                }
-            } else if (!executor.has_hook(mcpplibs::xpkg::HookType::Config) && node.pkgType == 4 /* Subos */) {
-                if (!subos::default_config(
-                        node,
-                        dataDir,
-                        detail_::version_namespace_(node.namespaceName))) {
-                    if (onStatus) {
-                        onStatus({ node.name, InstallPhase::Failed, 0.0f,
-                                   "default subos config failed" });
-                    }
-                    continue;
-                }
-            } else {
-                std::string configFailure;
-                if (!detail_::run_config_hook_(
-                        node, dataDir, executor, ctx, onStatus,
-                        useAfterInstall, &configFailure)) {
-                    // Same reason as the install hook above, and this one
-                    // matters more: config is where registration happens, so
-                    // its failure is exactly "payload on disk, ledger empty" --
-                    // the state that used to be indistinguishable from a
-                    // package that legitimately registers nothing.
-                    write_payload_failure_marker(
-                        ctx.install_dir, node.version, configFailure);
-                    if (onStatus) {
-                        onStatus({ node.name, InstallPhase::Failed, 0.0f,
-                                   std::move(configFailure) });
-                    }
-                    continue;
-                }
-            }
-
-            if (node.pkgType != 3 /* Config */) {
-                // TODO(config): same soft policy as the install stamp. A
-                // config package with no author-created payload must not
-                // become installed solely because xlings copied metadata into
-                // install_dir. Future libxpkg/spec work should define the
-                // stricter config contract.
-                if (auto snapshot = detail_::save_xpkg_snapshot_(node.pkgFile, ctx.install_dir);
-                    !snapshot) {
-                    log::error("failed to save xpkg snapshot for {}: {}",
-                               node.name, snapshot.error());
-                    if (onStatus) {
-                        onStatus({ node.name, InstallPhase::Failed, 0.0f,
-                                   snapshot.error() });
-                    }
-                    continue;
-                }
-            }
-
-            // C2, execution point 2 (warn-only): the closure predicate the
-            // index CI enforces, evaluated where the payload actually lands.
-            // mcpp#392 happened on a machine no CI ever saw. Fresh installs
-            // only -- a re-mapped payload was scanned when it first arrived,
-            // and re-scanning a 400MB payload on every dependent install
-            // would price the check out of existence.
-            if (!payloadInstalled && node.pkgType != 3 /* Config */) {
-                const auto rep = closurecheck::scan_payload(
-                    ctx.install_dir, dataDir / "xpkgs", host_glibc_recorded());
-                for (const auto& m : rep.missing) {
-                    log::warn("[{}@{}] {}", node.name, node.version,
-                              closurecheck::describe_missing(m));
-                }
-                if (rep.floor) {
-                    log::warn("[{}@{}] {}", node.name, node.version,
-                              closurecheck::describe_floor(*rep.floor));
-                }
-                if (rep.nonTransitive) {
-                    log::warn("[{}@{}] {}", node.name, node.version,
-                              closurecheck::describe_non_transitive(
-                                  *rep.nonTransitive));
-                }
-            }
-
-            // Re-stamp with what the install actually REGISTERED.
-            //
-            // The stamp above was written before the config hook ran, because
-            // its other job -- recording which platform produced the payload --
-            // has to happen on the install path. The registration count can
-            // only be known here, after the hook and after xvm accepted (or
-            // silently dropped) what it produced.
-            //
-            // This is the observation that makes a finished install checkable.
-            // Without it, "the run reached the end" and "the run did its work"
-            // are the same output, which is how a stack that wired nothing
-            // reported `installed` on a real home.
-            if (node.pkgType != 3 /* Config */) {
-                const auto registered = count_ledger_registrations(
-                    Config::versions(), Config::paths().homeDir.string(),
-                    node.namespaceName, node.name, node.version);
-                write_payload_stamp(ctx.install_dir, node.version, registered);
-            }
-
-            if (catalog_) {
-                catalog_->mark_installed(PackageMatch{
-                    .rawName = node.rawName,
-                    .name = node.name,
-                    .version = node.version,
-                    .namespaceName = node.namespaceName,
-                    .canonicalName = node.canonicalName,
-                    .repoName = node.repoName,
-                    .pkgFile = node.pkgFile,
-                    .storeRoot = node.storeRoot,
-                    .scope = node.scope,
-                    .installed = true,
-                }, true);
-            } else {
-                index_->mark_installed(node.name, true);
-            }
-
-            if (onStatus) {
-                onStatus({ node.name, InstallPhase::Done, 1.0f,
-                           payloadInstalled ? "already installed" : "" });
-            }
-            if (payloadInstalled) {
-                log::debug("{}@{} mapping to current subos", node.name, node.version);
-            } else {
-                log::debug("{}@{} installed successfully", node.name, node.version);
-            }
-        }
-
-        // Every hook returned success; that is not the same as the packages
-        // being usable. Fail the install rather than let a checkmark stand for
-        // a package that registered none of the programs it promised.
-        if (auto broken = detail_::unfulfilled_program_promises_(plan);
-            !broken.empty()) {
-            for (const auto& name : broken) {
-                if (onStatus) {
-                    onStatus({ name, InstallPhase::Failed, 0.0f,
-                               "declared programs were not registered" });
-                }
-            }
-            return std::unexpected(std::format(
-                "{} installed but registered none of its declared programs",
-                broken.front()));
-        }
-
-        return {};
-    }
+            bool useAfterInstall = false);
 
     // What `uninstall` actually did.
     //
@@ -3206,378 +513,10 @@ public:
 
     // Uninstall a package
     std::expected<UninstallOutcome, std::string>
-    uninstall(const std::string& name) {
-        auto platform = detect_platform_();
-        auto currentWorkspacePath = detail_::current_workspace_config_path_();
-
-        auto parse_target = [](std::string target) {
-            auto at = target.find('@');
-            if (at == std::string::npos) return std::pair{target, std::string{}};
-            return std::pair{target.substr(0, at), target.substr(at + 1)};
-        };
-
-        auto [targetName, requestedVersion] = parse_target(name);
-        if (requestedVersion.empty()) {
-            requestedVersion = xvm::get_active_version(Config::effective_workspace(), targetName);
-        }
-        std::string resolvedTarget;
-        if (requestedVersion.empty()) {
-            resolvedTarget = targetName;
-        } else {
-            auto [ns, bareVersion] = xvm::parse_ns_version(requestedVersion);
-            if (ns.empty()) {
-                resolvedTarget = targetName + "@" + bareVersion;
-            } else {
-                resolvedTarget = ns + ":" + targetName + "@" + bareVersion;
-            }
-        }
-
-        std::filesystem::path pkgFile;
-        std::filesystem::path installDir;
-        std::optional<PackageMatch> resolvedMatch;
-
-        if (catalog_) {
-            auto match = catalog_->resolve_target(resolvedTarget, platform);
-            if (!match) return std::unexpected(match.error());
-            resolvedMatch = *match;
-            pkgFile = match->pkgFile;
-            installDir = (match->storeRoot.empty() ? (Config::paths().dataDir / "xpkgs") : match->storeRoot)
-                / detail_::effective_store_name_(*match)
-                / match->version;
-        } else {
-            auto* entry = index_->find_entry(name);
-            if (!entry) {
-                return std::unexpected(std::format("package '{}' not found", name));
-            }
-            pkgFile = entry->path;
-            installDir = Config::paths().dataDir / "xpkgs" / name;
-        }
-
-        auto detachTarget = resolvedMatch ? resolvedMatch->name : targetName;
-        auto detachVersion = resolvedMatch ? resolvedMatch->version : requestedVersion;
-        if (resolvedMatch) {
-            detachVersion = xvm::make_ns_version(
-                detail_::version_namespace_(resolvedMatch->namespaceName),
-                resolvedMatch->version);
-        }
-        auto executingProvider = resolvedMatch
-            ? (resolvedMatch->canonicalName.empty()
-                ? canonical_package_name(
-                    resolvedMatch->namespaceName,
-                    resolvedMatch->name)
-                : resolvedMatch->canonicalName)
-            : targetName;
-        auto executingProviderVersion = resolvedMatch
-            ? resolvedMatch->version
-            : xvm::strip_namespace(detachVersion);
-
-        auto removalSnapshot = snapshot_xpkg_removal_context(
-            Config::versions_mut(), Config::workspace(), {},
-            executingProvider, executingProviderVersion,
-            detachTarget, detachVersion);
-
-        // Removing a package that registered no version is a NO-OP, not a
-        // failure (openxlings/xlings#506).
-        //
-        // The old code failed here with
-        //
-        //   xvm removal selection failed for local:gcc@15.1.0:
-        //   exact removal version is not registered (target='gcc', ...)
-        //
-        // and returned before the recipe's `uninstall()` hook could run -- so the
-        // package could be installed but never removed, and its own cleanup never
-        // executed.
-        //
-        // The asymmetry is the argument: the package registered no version at
-        // INSTALL time and install succeeded. Failing removal over the same fact
-        // punishes a shape the installer already accepted. `type = "config"` and
-        // `type = "script"` recipes are in that state by design.
-        //
-        // Narrow deliberately: only VersionNotFound, and only when the executing
-        // provider owns no version for this target. A mismatched version owned by
-        // this provider still fails loudly; another provider's version neither
-        // blocks this hook nor enters its removal selection.
-        xvm::RemovalContext removalContext;
-        if (removalSnapshot) {
-            removalContext = std::move(*removalSnapshot);
-        } else if (removalSnapshot.error().kind
-                       == xvm::RemovalErrorKind::VersionNotFound
-                   && detail_::executing_provider_owns_no_version(
-                          Config::versions_mut(), detachTarget,
-                          executingProvider)) {
-            log::info("{}: registers no xvm version; running its uninstall hook "
-                      "and removing the payload",
-                      executingProvider);
-        } else {
-            return std::unexpected(std::format(
-                "xvm removal selection failed for {}@{}: {} "
-                "(target='{}', version='{}')",
-                executingProvider, executingProviderVersion,
-                removalSnapshot.error().message,
-                removalSnapshot.error().target,
-                removalSnapshot.error().version));
-        }
-        if (auto memberIt = removalContext.members.find(detachTarget);
-            memberIt != removalContext.members.end()) {
-            detachVersion = memberIt->second;
-        }
-
-        auto stillReferenced = !detachVersion.empty()
-            && detail_::is_version_referenced_anywhere_(
-                resolvedMatch ? resolvedMatch->scope : PackageScope::Global,
-                detachTarget,
-                detachVersion,
-                currentWorkspacePath);
-
-        if (stillReferenced) {
-            detail_::detach_current_subos_(detachTarget, detachVersion);
-            log::debug("{}@{} detached from current subos; payload retained",
-                      detachTarget, detachVersion);
-            // Reported, not just logged at debug: this is the branch whose
-            // silence made a no-op look like a removal (#443).
-            return UninstallOutcome{
-                .detachedOnly = true,
-                .target       = detachTarget,
-                .version      = detachVersion,
-            };
-        }
-
-        auto executorPkgFile = detail_::uninstall_xpkg_file_(pkgFile, installDir);
-        if (executorPkgFile != pkgFile) {
-            log::debug("using xpkg snapshot for uninstall: {}", executorPkgFile.string());
-        }
-
-        auto execResult = mcpplibs::xpkg::create_executor(executorPkgFile);
-        if (!execResult) {
-            return std::unexpected(execResult.error());
-        }
-
-        auto& executor = *execResult;
-        executor.set_log_level(std::string(log::level_string()));
-
-        mcpplibs::xpkg::ExecutionContext ctx;
-        ctx.pkg_name = resolvedMatch ? resolvedMatch->name : name;
-        ctx.version = resolvedMatch ? resolvedMatch->version : std::string{};
-        ctx.platform = platform;
-        const auto artifactSubosDir =
-            detail_::configure_xpkg_execution_artifact_paths_(
-                ctx);
-        auto selectedStore = resolvedMatch
-            ? (resolvedMatch->storeRoot.empty()
-                ? Config::paths().dataDir / "xpkgs"
-                : resolvedMatch->storeRoot)
-            : Config::paths().dataDir / "xpkgs";
-        detail_::configure_dependency_store_roots_(ctx, selectedStore);
-        ctx.install_dir = installDir;
-        ctx.xpkg_dir = pkgFile.parent_path();
-        ctx.pkgindex_dir = detail_::pkgindex_root_for_(pkgFile);
-
-        bool useDefaultRemoval = false;
-        if (executor.has_hook(mcpplibs::xpkg::HookType::Uninstall)) {
-            log::debug("uninstalling {}...", name);
-            auto result = executor.run_hook(
-                mcpplibs::xpkg::HookType::Uninstall, ctx);
-            if (!result.success) {
-                return std::unexpected(
-                    detail_::format_hook_failure("uninstall", result));
-            }
-        } else {
-            // Check if this is a script-type or subos-type package and run default uninstall
-            bool isScriptType = false;
-            bool isSubosType  = false;
-            if (catalog_ && resolvedMatch) {
-                auto pkg = catalog_->load_package(*resolvedMatch);
-                if (pkg) {
-                    isScriptType = (pkg->type == mcpplibs::xpkg::PackageType::Script);
-                    isSubosType  = (pkg->type == mcpplibs::xpkg::PackageType::Subos);
-                }
-            } else if (index_) {
-                auto* entry = index_->find_entry(targetName);
-                if (entry) {
-                    isScriptType = (entry->type == mcpplibs::xpkg::PackageType::Script);
-                    isSubosType  = (entry->type == mcpplibs::xpkg::PackageType::Subos);
-                }
-            }
-            useDefaultRemoval = isScriptType || isSubosType;
-        }
-
-        // Process xvm operations collected by uninstall hook
-        auto xvm_ops = executor.xvm_operations();
-        if (useDefaultRemoval) {
-            xvm_ops.push_back({
-                .op = "remove",
-                .name = detachTarget,
-                .version = detachVersion,
-            });
-        }
-        auto sysroot_include =
-            artifactSubosDir / "usr" / "include";
-
-        const auto dbBeforeRemoval = Config::versions_mut();
-        auto removalResult = apply_xpkg_removal_operations(
-            Config::versions_mut(),
-            Config::workspace_mut(),
-            Config::workspace_installed_mut(),
-            xvm_ops,
-            removalContext,
-            xvm::RemovalBatchOptions{
-                .purgeSelection = true,
-            });
-        if (!removalResult) {
-            return std::unexpected(std::format(
-                "xvm removal batch failed for {}@{}: {} "
-                "(target='{}', version='{}')",
-                executingProvider, executingProviderVersion,
-                removalResult.error().message,
-                removalResult.error().target,
-                removalResult.error().version));
-        }
-
-        // Drop this package's subos env section. Keyed by binding, so it takes
-        // exactly what the package added and leaves every other provider's
-        // alone -- the recipe's uninstall() writes nothing for this.
-        //
-        // Matched by package *name* rather than the exact binding: the removal
-        // above resolves versions through namespaces and group members, so the
-        // binding recorded at install time is not reliably reconstructible
-        // here. A home that installed two versions of the same package can
-        // hold a section for each, and leaving the other one behind would
-        // point a driver search at a payload that is being deleted.
-        {
-            namespace mf = xlings::subos::manifest;
-            if (auto doc = mf::read_document(artifactSubosDir)) {
-                bool changed = false;
-                for (const auto& binding :
-                         mf::providers_named(*doc, executingProvider)) {
-                    changed |= mf::remove_provider(*doc, binding);
-                }
-                // providers_named matches the bare name; a namespaced install
-                // records the canonical one, so ask again under it.
-                if (executingProvider != detachTarget) {
-                    for (const auto& binding :
-                             mf::providers_named(*doc, detachTarget)) {
-                        changed |= mf::remove_provider(*doc, binding);
-                    }
-                }
-                if (changed) {
-                    try {
-                        platform::write_string_to_file(
-                            mf::config_path(artifactSubosDir).string(),
-                            doc->dump(2));
-                    } catch (const std::exception& e) {
-                        // Not fatal to the uninstall -- the payload is already
-                        // going -- but it must be said. A stale section points
-                        // at a directory that no longer exists, which doctor
-                        // D2/D3 will report.
-                        log::warn("[xim] could not clear subos env "
-                                  "declarations for {}: {}",
-                                  executingProvider, e.what());
-                    }
-                }
-            }
-        }
-
-        for (const auto& op : xvm_ops) {
-            if (op.op == "remove_headers") {
-                xvm::remove_headers(op.includedir, sysroot_include);
-            }
-        }
-
-        bool detachedByBatch = false;
-        for (const auto& removed : removalResult->removed) {
-            if (removed.target == detachTarget
-                && removed.version == detachVersion) {
-                detachedByBatch = true;
-            }
-        }
-        cleanup_removed_xvm_library_artifacts(
-            artifactSubosDir / "lib",
-            dbBeforeRemoval,
-            Config::versions_mut(),
-            *removalResult);
-        cleanup_removed_xvm_program_artifacts(
-            artifactSubosDir / "bin",
-            dbBeforeRemoval,
-            Config::versions_mut(),
-            Config::workspace_installed(),
-            *removalResult);
-        if (!detachedByBatch && !detachVersion.empty()) {
-            detail_::detach_current_subos_(
-                detachTarget, detachVersion, false);
-        }
-
-        Config::save_versions();
-        Config::save_workspace();
-
-        if (catalog_) {
-            catalog_->mark_installed(*resolvedMatch, false);
-        } else {
-            index_->mark_installed(name, false);
-        }
-        std::error_code ec;
-        std::filesystem::remove_all(installDir, ec);
-        if (ec) {
-            log::warn("failed to remove payload dir {}: {}", installDir.string(), ec.message());
-        }
-
-        // installDir is the version directory (e.g. .../xim-x-node/22.17.1).
-        // Its parent is the per-package directory (.../xim-x-node) which
-        // holds one subdirectory per installed version of the same package.
-        // After we delete the version we just uninstalled, the package
-        // directory may be left as an empty stub if this was its last
-        // version — sweep it.
-        //
-        // Why "list-then-remove" instead of "remove and tolerate ENOTEMPTY":
-        // fs::remove (non-recursive) silently returns false for non-empty
-        // directories, which would conflate the "still has versions, leave
-        // it alone" expected case with real errors (permission denied, IO
-        // failure). It is also a maintenance trap — the next reader can
-        // upgrade it to fs::remove_all and wipe sibling versions. So check
-        // emptiness explicitly first.
-        //
-        // Cross-platform: directory_iterator and fs::remove are part of
-        // std::filesystem and behave identically on Linux/macOS/Windows
-        // for the cases we care about (empty dir → end iterator; remove of
-        // an empty directory → succeeds; non-existent or unreadable parent
-        // → ec set, we skip). One platform-specific edge case worth naming:
-        // file managers occasionally drop hidden metadata into the dir
-        // (.DS_Store on macOS, Thumbs.db on Windows). Those count as
-        // non-empty, so we will leave the package directory alone — that
-        // is the right behavior; never silently delete files we did not
-        // create.
-        auto parent = installDir.parent_path();
-        std::error_code listEc;
-        auto first = std::filesystem::directory_iterator(parent, listEc);
-        if (!listEc && first == std::default_sentinel) {
-            std::error_code rmEc;
-            if (std::filesystem::remove(parent, rmEc)) {
-                log::debug("swept empty package dir: {}", parent.string());
-            } else if (rmEc) {
-                log::warn("failed to sweep empty package dir {}: {}",
-                          parent.string(), rmEc.message());
-            }
-        }
-
-        log::debug("{} uninstalled", resolvedTarget);
-        return UninstallOutcome{
-            .detachedOnly = false,
-            .target       = detachTarget,
-            .version      = detachVersion,
-        };
-    }
+    uninstall(const std::string& name);
 
 private:
-    static std::string detect_platform_() {
-        #if defined(__linux__)
-            return "linux";
-        #elif defined(__APPLE__)
-            return "macosx";
-        #elif defined(_WIN32)
-            return "windows";
-        #else
-            return "unknown";
-        #endif
-    }
+    static std::string detect_platform_();
 };
 
 } // namespace xlings::xim
diff --git a/src/core/xim/inventory.cpp b/src/core/xim/inventory.cpp
new file mode 100644
index 00000000..1074d86e
--- /dev/null
+++ b/src/core/xim/inventory.cpp
@@ -0,0 +1,722 @@
+module xlings.core.xim.inventory;
+
+import std;
+import xlings.core.config;
+import xlings.core.profile;
+import xlings.core.version_order;
+import xlings.core.xim.catalog;
+import xlings.core.xim.install_state;
+import xlings.core.xim.payload;
+import xlings.core.xvm.bindings;
+import xlings.core.xvm.db;
+import xlings.core.xvm.owner;
+import xlings.core.xvm.types;
+import xlings.platform;
+
+namespace xlings::xim {
+
+std::pair<std::string, std::string> identity_from_store_name(
+    std::string_view storeName) {
+    const auto separator = storeName.find("-x-");
+    if (separator == std::string_view::npos) {
+        return {{}, std::string(storeName)};
+    }
+    return {std::string(storeName.substr(0, separator)),
+            std::string(storeName.substr(separator + 3))};
+}
+
+namespace detail {
+
+void trace_payload_visit(InventoryTrace* trace,
+                         const std::filesystem::path& versionDir) {
+    if (trace != nullptr) trace->payloadVersionDirs.push_back(versionDir);
+}
+
+void push_candidate(std::vector<xvm::InstallCoordinate>& candidates,
+                    xvm::InstallCoordinate candidate) {
+    if (candidate.empty() || candidate.version.empty()) return;
+    if (std::ranges::find(candidates, candidate) != candidates.end()) return;
+    candidates.push_back(std::move(candidate));
+}
+
+xvm::InstallCoordinate direct_coordinate(const std::string& target,
+                                         const std::string& version) {
+    const auto [namespaceName, bareVersion] = xvm::parse_ns_version(version);
+    return {.ns = namespaceName,
+            .package = target,
+            .version = bareVersion};
+}
+
+const xvm::VData* version_data(const xvm::VersionDB& db,
+                               const TargetVersion& pair) {
+    const auto info = db.find(pair.first);
+    if (info == db.end()) return nullptr;
+    const auto data = info->second.versions.find(pair.second);
+    return data == info->second.versions.end() ? nullptr : &data->second;
+}
+
+SelectionPtr bounded_selection(const xvm::VersionDB& db, const TargetVersion& seed, SelectionCache& cache, xvm::BindingSelectionResolver& resolver, InventoryTrace* trace) {
+    if (const auto cached = cache.find(seed); cached != cache.end()) {
+        return cached->second;
+    }
+
+    const auto* seedData = version_data(db, seed);
+    if (seedData == nullptr) {
+        cache[seed] = nullptr;
+        return nullptr;
+    }
+    const auto seedInfo = db.find(seed.first);
+    if (seedInfo == db.end()) {
+        cache[seed] = nullptr;
+        return nullptr;
+    }
+    const bool hasCanonicalMetadata = seedData->bindingMembersDeclared
+        || !seedData->bindingMembers.empty()
+        || seedData->bindingHeadersDeclared
+        || !seedData->bindingHeaders.empty()
+        || !seedData->bindingIntegrityIssues.empty()
+        || !seedData->bindingUnreadable.empty();
+    if (!seedData->bindingGroup && !hasCanonicalMetadata
+        && seedInfo->second.bindings.empty()) {
+        cache[seed] = nullptr;
+        return nullptr;
+    }
+
+    if (trace != nullptr) {
+        trace->bindingSelections.push_back(
+            seed.first + "@" + seed.second);
+    }
+    auto selected = resolver.resolve(seed.first, seed.second);
+    if (trace != nullptr) {
+        trace->legacyIncomingIndexBuilds =
+            resolver.legacy_incoming_index_builds();
+    }
+    if (!selected) {
+        cache[seed] = nullptr;
+        return nullptr;
+    }
+    auto value = std::make_shared<BoundedSelection>();
+    value->members = selected->members;
+    value->source = selected->source;
+    if (seedData->bindingGroup) {
+        value->root = TargetVersion{
+            seedData->bindingGroup->rootTarget,
+            seedData->bindingGroup->rootVersion,
+        };
+    }
+
+    for (const auto& [target, version] : value->members) {
+        cache[{target, version}] = value;
+    }
+    return value;
+}
+
+bool legacy_root_in_selection(const xvm::VersionDB& db,
+                              const BoundedSelection& selection,
+                              const TargetVersion& candidate) {
+    for (const auto& [peerTarget, peerVersion] : selection.members) {
+        if (peerTarget == candidate.first) continue;
+        const auto peer = db.find(peerTarget);
+        if (peer == db.end()) continue;
+        const auto binding = peer->second.bindings.find(candidate.first);
+        if (binding == peer->second.bindings.end()) continue;
+        const auto edge = binding->second.find(peerVersion);
+        if (edge != binding->second.end()
+            && edge->second == candidate.second) {
+            return true;
+        }
+    }
+    return false;
+}
+
+std::vector<xvm::InstallCoordinate> direct_owner_candidates_for(
+    const xvm::VersionDB& db,
+    const TargetVersion& pair) {
+    std::vector<xvm::InstallCoordinate> candidates;
+    const auto* data = version_data(db, pair);
+    if (data && data->bindingGroup
+        && !data->bindingGroup->providerVersion.empty()) {
+        const auto provider = parse_package_target(
+            data->bindingGroup->provider);
+        push_candidate(candidates, {
+            .ns = provider.namespaceName,
+            .package = provider.name,
+            .version = xvm::strip_namespace(
+                data->bindingGroup->providerVersion),
+        });
+    }
+    if (data) {
+        if (auto fromPath = xvm::coordinate_from_payload_path(data->path)) {
+            push_candidate(candidates, std::move(*fromPath));
+        }
+    }
+    push_candidate(candidates, direct_coordinate(pair.first, pair.second));
+    return candidates;
+}
+
+IncomingEdgeIndex build_incoming_edges(const xvm::VersionDB& db) {
+    IncomingEdgeIndex incoming;
+    for (const auto& [sourceTarget, sourceInfo] : db) {
+        for (const auto& [destinationTarget, versions] : sourceInfo.bindings) {
+            for (const auto& [sourceVersion, destinationVersion] : versions) {
+                incoming[{destinationTarget, destinationVersion}]
+                    .emplace_back(sourceTarget, sourceVersion);
+            }
+        }
+    }
+    return incoming;
+}
+
+std::vector<xvm::InstallCoordinate> shallow_owner_candidates_for(const xvm::VersionDB& db, const TargetVersion& pair, const IncomingEdgeIndex* incoming) {
+    auto candidates = direct_owner_candidates_for(db, pair);
+    const auto* data = version_data(db, pair);
+    if (data && data->bindingGroup) {
+        const TargetVersion root{
+            data->bindingGroup->rootTarget,
+            data->bindingGroup->rootVersion,
+        };
+        if (root != pair) {
+            push_candidate(candidates, direct_coordinate(
+                root.first, root.second));
+            if (const auto* rootData = version_data(db, root)) {
+                if (auto fromPath =
+                        xvm::coordinate_from_payload_path(rootData->path)) {
+                    push_candidate(candidates, std::move(*fromPath));
+                }
+            }
+        }
+        return candidates;
+    }
+
+    std::vector<TargetVersion> pending{pair};
+    std::set<TargetVersion> visited;
+    const auto reach = [&](const TargetVersion& peer) {
+        push_candidate(candidates, direct_coordinate(peer.first, peer.second));
+        if (const auto* peerData = version_data(db, peer)) {
+            if (auto fromPath =
+                    xvm::coordinate_from_payload_path(peerData->path)) {
+                push_candidate(candidates, std::move(*fromPath));
+            }
+        }
+        if (!visited.contains(peer)) pending.push_back(peer);
+    };
+    while (!pending.empty()) {
+        auto current = std::move(pending.back());
+        pending.pop_back();
+        if (!visited.insert(current).second) continue;
+        if (incoming != nullptr) {
+            if (const auto found = incoming->find(current);
+                found != incoming->end()) {
+                for (const auto& source : found->second) reach(source);
+            }
+        }
+        const auto info = db.find(current.first);
+        if (info == db.end()) continue;
+        for (const auto& [peerTarget, versions] : info->second.bindings) {
+            const auto edge = versions.find(current.second);
+            if (edge == versions.end()) continue;
+            reach(TargetVersion{peerTarget, edge->second});
+        }
+    }
+    return candidates;
+}
+
+std::vector<xvm::InstallCoordinate> owner_candidates_for(const xvm::VersionDB& db, const TargetVersion& pair, SelectionCache& selectionCache, xvm::BindingSelectionResolver& resolver, InventoryTrace* trace) {
+    auto candidates = direct_owner_candidates_for(db, pair);
+
+    const auto selection = bounded_selection(
+        db, pair, selectionCache, resolver, trace);
+    if (!selection) return candidates;
+    if (selection->source == xvm::BindingSource::ProviderGroup) {
+        if (selection->root && *selection->root != pair) {
+            push_candidate(candidates, direct_coordinate(
+                selection->root->first, selection->root->second));
+            if (const auto* rootData = version_data(db, *selection->root)) {
+                if (auto fromPath =
+                        xvm::coordinate_from_payload_path(rootData->path)) {
+                    push_candidate(candidates, std::move(*fromPath));
+                }
+            }
+        }
+        return candidates;
+    }
+
+    for (const auto& [target, version] : selection->members) {
+        const TargetVersion candidate{target, version};
+        if (candidate == pair
+            || !legacy_root_in_selection(db, *selection, candidate)) {
+            continue;
+        }
+        push_candidate(candidates, direct_coordinate(target, version));
+        if (const auto* rootData = version_data(db, candidate)) {
+            if (auto fromPath =
+                    xvm::coordinate_from_payload_path(rootData->path)) {
+                push_candidate(candidates, std::move(*fromPath));
+            }
+        }
+    }
+    return candidates;
+}
+
+bool identity_matches(std::string_view namespaceName,
+                      std::string_view name,
+                      std::string_view filter,
+                      CoordinateMatch match) {
+    if (filter.empty()) return true;
+    const auto canonical = canonical_package_name(namespaceName, name);
+    if (match == CoordinateMatch::exact) return canonical == filter;
+    return canonical.contains(filter) || name.contains(filter);
+}
+
+bool candidate_may_match(const xvm::InstallCoordinate& candidate,
+                         std::string_view filter,
+                         CoordinateMatch match) {
+    return identity_matches(
+        candidate.ns, candidate.package, filter, match);
+}
+
+OwnedCoordinate resolve_owner(std::span<const xvm::InstallCoordinate> candidates, const TargetVersion& pair, std::span<const std::filesystem::path> storeRoots, MetadataLookup& metadata, InventoryTrace* trace) {
+    for (const auto& candidate : candidates) {
+        if (const auto* found = metadata.by_identity(
+                candidate.ns, candidate.package)) {
+            return {.coordinate = candidate, .storeRoot = found->storeRoot};
+        }
+    }
+    for (const auto& candidate : candidates) {
+        for (const auto& root : storeRoots) {
+            const auto versionDir = root
+                / package_store_name(candidate.ns, candidate.package)
+                / candidate.version;
+            trace_payload_visit(trace, versionDir);
+            std::error_code ec;
+            if (std::filesystem::is_directory(versionDir, ec)) {
+                return {.coordinate = candidate, .storeRoot = root};
+            }
+        }
+    }
+    if (const auto* unique = metadata.by_short_name(pair.first)) {
+        const auto [_, bareVersion] = xvm::parse_ns_version(pair.second);
+        return {
+            .coordinate = {.ns = unique->namespaceName,
+                           .package = unique->name,
+                           .version = bareVersion},
+            .storeRoot = unique->storeRoot,
+        };
+    }
+    if (!candidates.empty()) return {.coordinate = candidates.front()};
+    return {.coordinate = direct_coordinate(pair.first, pair.second)};
+}
+
+RelatedCoordinates build_owner_coordinates(const xvm::VersionDB& db, const std::set<TargetVersion>& requested, std::string_view filter, std::span<const std::filesystem::path> storeRoots, MetadataLookup& metadata, InventoryTrace* trace, CoordinateMatch match) {
+    RelatedCoordinates related;
+    SelectionCache selectionCache;
+    xvm::BindingSelectionResolver bindingResolver{db};
+    // Only a filtered query can skip a pair, so only a filtered query pays for
+    // the reverse index the skip decision needs to be safe.
+    std::optional<IncomingEdgeIndex> incoming;
+    if (!filter.empty()) incoming = build_incoming_edges(db);
+    for (const auto& pair : requested) {
+        if (!filter.empty()) {
+            const auto shallow = shallow_owner_candidates_for(
+                db, pair, incoming ? &*incoming : nullptr);
+            auto mayMatch = std::ranges::any_of(
+                shallow, [&](const auto& candidate) {
+                    return candidate_may_match(candidate, filter, match);
+                });
+            if (!mayMatch) {
+                const auto* unique = metadata.by_short_name(pair.first);
+                mayMatch = unique != nullptr
+                    && identity_matches(unique->namespaceName, unique->name,
+                                        filter, match);
+            }
+            if (!mayMatch) continue;
+        }
+        auto candidates = owner_candidates_for(
+            db, pair, selectionCache, bindingResolver, trace);
+        auto owner = resolve_owner(
+            candidates, pair, storeRoots, metadata, trace);
+        if (!identity_matches(owner.coordinate.ns, owner.coordinate.package,
+                              filter, match)) {
+            continue;
+        }
+        related.emplace(pair, std::move(owner));
+    }
+    return related;
+}
+
+std::vector<InventoryWorkspace> load_inventory_workspaces(bool allSubos) {
+    std::vector<InventoryWorkspace> workspaces;
+    const auto currentName = Config::paths().subosDir.filename().string();
+    workspaces.push_back({
+        .name = currentName.empty() ? std::string{"current"} : currentName,
+        .active = Config::effective_workspace(),
+        .installed = Config::workspace_installed(),
+        .current = true,
+    });
+    if (!allSubos) return workspaces;
+
+    for (auto& snapshot : profile::load_subos_snapshots(
+             Config::paths().homeDir)) {
+        std::error_code equivalentEc;
+        const auto samePath = std::filesystem::equivalent(
+            snapshot.dir, Config::paths().subosDir, equivalentEc);
+        if (snapshot.name == currentName || samePath) continue;
+        workspaces.push_back({
+            .name = snapshot.name,
+            .active = std::move(snapshot.workspace.active),
+            .installed = std::move(snapshot.workspace.installed),
+            .current = false,
+        });
+    }
+    return workspaces;
+}
+
+std::set<TargetVersion> requested_pairs(
+    std::span<const InventoryWorkspace> workspaces) {
+    std::set<TargetVersion> requested;
+    for (const auto& workspace : workspaces) {
+        for (const auto& [target, versions] : workspace.installed) {
+            for (const auto& version : versions) {
+                requested.emplace(target, version);
+            }
+        }
+        for (const auto& [target, version] : workspace.active) {
+            requested.emplace(target, version);
+        }
+    }
+    return requested;
+}
+
+std::vector<std::filesystem::path> inventory_store_roots() {
+    std::vector<std::filesystem::path> roots;
+    if (Config::has_project_config()) {
+        const auto projectData = Config::project_data_dir();
+        if (!projectData.empty()) roots.push_back(projectData / "xpkgs");
+    }
+    const auto global = Config::global_data_dir() / "xpkgs";
+    if (std::ranges::find(roots, global) == roots.end()) {
+        roots.push_back(global);
+    }
+    return roots;
+}
+
+std::vector<InstalledPackageRecord> assemble_inventory(const xvm::VersionDB& db, std::span<const InventoryWorkspace> workspaces, std::span<const std::filesystem::path> storeRoots, MetadataLookup& metadata, std::string_view filter, CoordinateMatch match, InventoryTrace* trace, bool includePayloadOnly) {
+    const auto requested = requested_pairs(workspaces);
+    const auto related = build_owner_coordinates(
+        db, requested, filter, storeRoots, metadata, trace, match);
+    // Built once for the whole inventory rather than per record: the query
+    // contract says local commands answer immediately, and one pass over the
+    // DB is what keeps `info` proportional to the answer instead of the home.
+    const LedgerIndex ledgerIndex(db, Config::paths().homeDir.string());
+    std::map<std::string, InstalledPackageRecord> records;
+    std::map<std::string, std::filesystem::path> catalogFallbacks;
+    std::set<std::string> workspaceDerived;
+    std::set<std::string> stampDerived;
+
+    const auto ensure_record = [&](const OwnedCoordinate& owned)
+        -> InstalledPackageRecord& {
+        const auto& coordinate = owned.coordinate;
+        auto [it, inserted] = records.try_emplace(coordinate.canonical());
+        auto& record = it->second;
+        if (inserted) {
+            record.namespaceName = coordinate.ns;
+            record.name = coordinate.package;
+            record.canonicalName = canonical_package_name(
+                coordinate.ns, coordinate.package);
+            record.version = coordinate.version;
+        }
+        if (!owned.storeRoot.empty()) {
+            catalogFallbacks.try_emplace(coordinate.canonical(),
+                owned.storeRoot
+                / package_store_name(coordinate.ns, coordinate.package)
+                / coordinate.version);
+        }
+        return record;
+    };
+
+    for (const auto& workspace : workspaces) {
+        for (const auto& [target, versions] : workspace.installed) {
+            for (const auto& version : versions) {
+                const auto found = related.find({target, version});
+                if (found == related.end()) continue;
+                auto& record = ensure_record(found->second);
+                workspaceDerived.insert(found->second.coordinate.canonical());
+                record.suboses.insert(workspace.name);
+                record.inCurrentSubos |= workspace.current;
+            }
+        }
+        for (const auto& [target, version] : workspace.active) {
+            const auto found = related.find({target, version});
+            if (found == related.end()) continue;
+            auto& record = ensure_record(found->second);
+            workspaceDerived.insert(found->second.coordinate.canonical());
+            record.suboses.insert(workspace.name);
+            record.inCurrentSubos |= workspace.current;
+            record.active = true;
+        }
+    }
+
+    // Project comes first. If both stores contain the same canonical stamp,
+    // the project-scoped payload is the one the catalog also prefers.
+    if (includePayloadOnly) for (const auto& storeRoot : storeRoots) {
+        std::error_code ec;
+        if (!std::filesystem::is_directory(storeRoot, ec)) continue;
+        for (const auto& packageDir : platform::dir_entries(storeRoot)) {
+            if (!packageDir.is_directory(ec)) continue;
+            const auto storeName = packageDir.path().filename().string();
+            const auto [namespaceName, name] =
+                identity_from_store_name(storeName);
+            if (!identity_matches(namespaceName, name, filter, match)) continue;
+            for (const auto& versionDir :
+                    platform::dir_entries(packageDir.path())) {
+                if (!versionDir.is_directory(ec)) continue;
+                trace_payload_visit(trace, versionDir.path());
+                const auto stamped = std::filesystem::is_regular_file(
+                    versionDir.path()
+                        / std::filesystem::path(kPayloadStampFile), ec);
+                ec.clear();
+                const auto legacyMarked = std::filesystem::is_regular_file(
+                    versionDir.path() / ".xim-installed", ec);
+                if (!stamped && !legacyMarked) continue;
+                OwnedCoordinate owned{
+                    .coordinate = {.ns = namespaceName,
+                                   .package = name,
+                                   .version = versionDir.path()
+                                                  .filename().string()},
+                    .storeRoot = storeRoot,
+                };
+                auto& record = ensure_record(owned);
+                if (stampDerived.insert(
+                        owned.coordinate.canonical()).second) {
+                    record.payloadPath = versionDir.path();
+                }
+            }
+        }
+    }
+
+    std::vector<InstalledPackageRecord> result;
+    result.reserve(records.size());
+    for (auto& [coordinate, record] : records) {
+        const auto* found = workspaceDerived.contains(coordinate)
+            ? metadata.load_details(record.namespaceName, record.name)
+            : metadata.load_stamped_details(
+                  record.namespaceName, record.name);
+        if (found) {
+            record.namespaceName = found->namespaceName;
+            record.name = found->name;
+            record.canonicalName = found->canonicalName;
+            record.description = found->description;
+            record.programs = found->programs;
+            if (!found->storeRoot.empty()) {
+                catalogFallbacks.try_emplace(coordinate,
+                    found->storeRoot
+                    / package_store_name(record.namespaceName, record.name)
+                    / record.version);
+            }
+        }
+        if (record.payloadPath.empty()) {
+            for (const auto& root : storeRoots) {
+                const auto candidate = root
+                    / package_store_name(record.namespaceName, record.name)
+                    / record.version;
+                trace_payload_visit(trace, candidate);
+                std::error_code ec;
+                if (std::filesystem::is_directory(candidate, ec)) {
+                    record.payloadPath = candidate;
+                    break;
+                }
+            }
+        }
+        if (record.payloadPath.empty()) {
+            if (const auto fallback = catalogFallbacks.find(coordinate);
+                fallback != catalogFallbacks.end()) {
+                record.payloadPath = fallback->second;
+            }
+        }
+        if (record.payloadPath.empty() && !storeRoots.empty()) {
+            record.payloadPath = storeRoots.back()
+                / package_store_name(record.namespaceName, record.name)
+                / record.version;
+        }
+        trace_payload_visit(trace, record.payloadPath);
+        record.payloadPresent = payload_has_content(record.payloadPath);
+        // Asked here rather than derived from the two flags above, because the
+        // interesting cases are exactly the ones those flags agree on: a
+        // stamped payload with no ledger entry has `payloadPresent` true and an
+        // index entry, and is unusable. One answerer, asked by everyone.
+        if (const auto state = installation_state(
+                ledgerIndex, record.namespaceName, record.name,
+                record.version, record.payloadPath);
+            state.is_incomplete()) {
+            record.incomplete = true;
+            record.incompleteReason = state.reason;
+        }
+        if (!record.payloadPresent) {
+            record.degradedReason = "payload missing";
+        } else if (!found) {
+            record.degradedReason = "index entry unavailable";
+        }
+        result.push_back(std::move(record));
+    }
+
+    std::ranges::stable_sort(result, [](const auto& lhs, const auto& rhs) {
+        if (lhs.canonicalName != rhs.canonicalName) {
+            return lhs.canonicalName < rhs.canonicalName;
+        }
+        return version_order::compare(lhs.version, rhs.version) > 0;
+    });
+    return result;
+}
+
+std::vector<InstalledPackageRecord> assemble_inventory(
+    const xvm::VersionDB& db,
+    std::span<const InventoryWorkspace> workspaces,
+    const std::filesystem::path& storeRoot,
+    MetadataLookup& metadata,
+    bool includePayloadOnly) {
+    const std::array roots{storeRoot};
+    return assemble_inventory(
+        db, workspaces, roots, metadata, {}, CoordinateMatch::contains,
+        nullptr, includePayloadOnly);
+}
+
+}
+
+std::vector<InstalledPackageRecord> collect_inventory_impl(
+    PackageCatalog& catalog, bool allSubos,
+    std::optional<std::string_view> filter,
+    detail::CoordinateMatch match,
+    InventoryTrace* trace) {
+    detail::MetadataLookup metadata(catalog, trace);
+    const auto workspaces = detail::load_inventory_workspaces(allSubos);
+    const auto storeRoots = detail::inventory_store_roots();
+    return detail::assemble_inventory(
+        Config::versions(), workspaces, storeRoots, metadata,
+        filter.value_or(std::string_view{}), match, trace);
+}
+
+std::vector<InstalledPackageRecord> collect_inventory(PackageCatalog& catalog, bool allSubos, std::optional<std::string_view> canonicalFilter, InventoryTrace* trace) {
+    return collect_inventory_impl(
+        catalog, allSubos, canonicalFilter,
+        detail::CoordinateMatch::contains, trace);
+}
+
+std::vector<InstalledPackageRecord> collect_package_inventory(PackageCatalog& catalog, const std::string& canonicalName, bool allSubos, InventoryTrace* trace) {
+    const auto parsed = parse_package_target(canonicalName);
+    if (parsed.name.empty() || !parsed.version.empty()) return {};
+    return collect_inventory_impl(
+        catalog, allSubos, std::string_view{canonicalName},
+        detail::CoordinateMatch::exact, trace);
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::xim::detail {
+
+MetadataLookup::MetadataLookup(PackageCatalog& catalog, InventoryTrace* trace) : catalog_(&catalog), trace_(trace) {}
+
+MetadataLookup::MetadataLookup(std::map<std::string, CatalogMetadata> table) {
+    for (auto& [storeName, item] : table) {
+        const auto shortName = item.name;
+        exact_.emplace(storeName, CatalogRecord{
+            .metadata = std::move(item),
+            .detailsLoaded = true,
+        });
+        if (auto found = shortKeys_.find(shortName);
+            found == shortKeys_.end()) {
+            shortKeys_.emplace(shortName, storeName);
+        } else {
+            found->second.reset();
+        }
+    }
+}
+
+const CatalogMetadata* MetadataLookup::by_identity(const std::string& namespaceName,
+                                       const std::string& name) {
+    const auto storeName = package_store_name(namespaceName, name);
+    if (!exact_.contains(storeName)) {
+        auto resolved = resolve_(namespaceName.empty()
+            ? name : namespaceName + ":" + name);
+        if (resolved
+            && package_store_name(resolved->metadata.namespaceName,
+                                  resolved->metadata.name) != storeName) {
+            resolved.reset();
+        }
+        exact_.emplace(storeName, std::move(resolved));
+    }
+    return metadata_for_store_(storeName);
+}
+
+const CatalogMetadata* MetadataLookup::by_short_name(const std::string& name) {
+    if (!shortKeys_.contains(name)) {
+        auto resolved = resolve_(name);
+        if (!resolved) {
+            shortKeys_.emplace(name, std::nullopt);
+        } else {
+            const auto storeName = package_store_name(
+                resolved->metadata.namespaceName,
+                resolved->metadata.name);
+            if (auto found = exact_.find(storeName);
+                found == exact_.end() || !found->second) {
+                exact_[storeName] = std::move(resolved);
+            }
+            shortKeys_.emplace(name, storeName);
+        }
+    }
+    const auto& key = shortKeys_.at(name);
+    return key ? metadata_for_store_(*key) : nullptr;
+}
+
+const CatalogMetadata* MetadataLookup::load_details(const std::string& namespaceName,
+                                        const std::string& name) {
+    const auto* identity = by_identity(namespaceName, name);
+    if (identity == nullptr) return nullptr;
+    const auto storeName = package_store_name(namespaceName, name);
+    auto& record = *exact_.at(storeName);
+    if (!record.detailsLoaded && record.match && catalog_ != nullptr) {
+        if (trace_ != nullptr) {
+            trace_->metadataIdentities.push_back(
+                record.metadata.canonicalName);
+        }
+        if (auto pkg = catalog_->load_package(*record.match)) {
+            record.metadata.description = std::string(pkg->description);
+            record.metadata.programs = pkg->programs;
+        }
+        record.detailsLoaded = true;
+    }
+    return &record.metadata;
+}
+
+const CatalogMetadata* MetadataLookup::load_stamped_details(
+        const std::string& namespaceName, const std::string& name) {
+    // by_identity is a metadata-only local-index lookup. A recipe is
+    // loaded only after that lookup proves this exact stamped identity is
+    // unique; missing and ambiguous stamps remain self-describing rows.
+    return load_details(namespaceName, name);
+}
+
+const CatalogMetadata* MetadataLookup::metadata_for_store_(const std::string& storeName) {
+    const auto found = exact_.find(storeName);
+    if (found == exact_.end() || !found->second) return nullptr;
+    return &found->second->metadata;
+}
+
+std::optional<CatalogRecord> MetadataLookup::resolve_(const std::string& target) {
+    if (catalog_ == nullptr) return std::nullopt;
+    auto match = catalog_->resolve_local_identity(target);
+    if (!match) return std::nullopt;
+    return CatalogRecord{
+        .metadata = {
+            .namespaceName = match->namespaceName,
+            .name = match->name,
+            .canonicalName = match->canonicalName,
+            .storeRoot = match->storeRoot,
+        },
+        .match = std::move(*match),
+    };
+}
+
+} // namespace xlings::xim::detail
diff --git a/src/core/xim/inventory.cppm b/src/core/xim/inventory.cppm
index 12a187ef..92787e71 100644
--- a/src/core/xim/inventory.cppm
+++ b/src/core/xim/inventory.cppm
@@ -3,7 +3,6 @@ export module xlings.core.xim.inventory;
 import std;
 import xlings.core.config;
 import xlings.core.profile;
-import xlings.core.version_order;
 import xlings.core.xim.catalog;
 import xlings.core.xim.install_state;
 import xlings.core.xim.payload;
@@ -11,7 +10,6 @@ import xlings.core.xvm.bindings;
 import xlings.core.xvm.db;
 import xlings.core.xvm.owner;
 import xlings.core.xvm.types;
-import xlings.platform;
 
 // What is installed, taken from the records that decide it.
 //
@@ -60,14 +58,7 @@ struct InventoryTrace {
 };
 
 std::pair<std::string, std::string> identity_from_store_name(
-    std::string_view storeName) {
-    const auto separator = storeName.find("-x-");
-    if (separator == std::string_view::npos) {
-        return {{}, std::string(storeName)};
-    }
-    return {std::string(storeName.substr(0, separator)),
-            std::string(storeName.substr(separator + 3))};
-}
+    std::string_view storeName);
 
 namespace detail {
 
@@ -91,110 +82,25 @@ struct CatalogRecord {
 // deferred until a row has survived workspace scope and filtering.
 class MetadataLookup {
 public:
-    MetadataLookup(PackageCatalog& catalog, InventoryTrace* trace = nullptr)
-        : catalog_(&catalog), trace_(trace) {}
-
-    explicit MetadataLookup(std::map<std::string, CatalogMetadata> table) {
-        for (auto& [storeName, item] : table) {
-            const auto shortName = item.name;
-            exact_.emplace(storeName, CatalogRecord{
-                .metadata = std::move(item),
-                .detailsLoaded = true,
-            });
-            if (auto found = shortKeys_.find(shortName);
-                found == shortKeys_.end()) {
-                shortKeys_.emplace(shortName, storeName);
-            } else {
-                found->second.reset();
-            }
-        }
-    }
+    MetadataLookup(PackageCatalog& catalog, InventoryTrace* trace = nullptr);
+
+    explicit MetadataLookup(std::map<std::string, CatalogMetadata> table);
 
     const CatalogMetadata* by_identity(const std::string& namespaceName,
-                                       const std::string& name) {
-        const auto storeName = package_store_name(namespaceName, name);
-        if (!exact_.contains(storeName)) {
-            auto resolved = resolve_(namespaceName.empty()
-                ? name : namespaceName + ":" + name);
-            if (resolved
-                && package_store_name(resolved->metadata.namespaceName,
-                                      resolved->metadata.name) != storeName) {
-                resolved.reset();
-            }
-            exact_.emplace(storeName, std::move(resolved));
-        }
-        return metadata_for_store_(storeName);
-    }
-
-    const CatalogMetadata* by_short_name(const std::string& name) {
-        if (!shortKeys_.contains(name)) {
-            auto resolved = resolve_(name);
-            if (!resolved) {
-                shortKeys_.emplace(name, std::nullopt);
-            } else {
-                const auto storeName = package_store_name(
-                    resolved->metadata.namespaceName,
-                    resolved->metadata.name);
-                if (auto found = exact_.find(storeName);
-                    found == exact_.end() || !found->second) {
-                    exact_[storeName] = std::move(resolved);
-                }
-                shortKeys_.emplace(name, storeName);
-            }
-        }
-        const auto& key = shortKeys_.at(name);
-        return key ? metadata_for_store_(*key) : nullptr;
-    }
+                                       const std::string& name);
+
+    const CatalogMetadata* by_short_name(const std::string& name);
 
     const CatalogMetadata* load_details(const std::string& namespaceName,
-                                        const std::string& name) {
-        const auto* identity = by_identity(namespaceName, name);
-        if (identity == nullptr) return nullptr;
-        const auto storeName = package_store_name(namespaceName, name);
-        auto& record = *exact_.at(storeName);
-        if (!record.detailsLoaded && record.match && catalog_ != nullptr) {
-            if (trace_ != nullptr) {
-                trace_->metadataIdentities.push_back(
-                    record.metadata.canonicalName);
-            }
-            if (auto pkg = catalog_->load_package(*record.match)) {
-                record.metadata.description = std::string(pkg->description);
-                record.metadata.programs = pkg->programs;
-            }
-            record.detailsLoaded = true;
-        }
-        return &record.metadata;
-    }
+                                        const std::string& name);
 
     const CatalogMetadata* load_stamped_details(
-        const std::string& namespaceName, const std::string& name) {
-        // by_identity is a metadata-only local-index lookup. A recipe is
-        // loaded only after that lookup proves this exact stamped identity is
-        // unique; missing and ambiguous stamps remain self-describing rows.
-        return load_details(namespaceName, name);
-    }
+        const std::string& namespaceName, const std::string& name);
 
 private:
-    const CatalogMetadata* metadata_for_store_(const std::string& storeName) {
-        const auto found = exact_.find(storeName);
-        if (found == exact_.end() || !found->second) return nullptr;
-        return &found->second->metadata;
-    }
-
-    std::optional<CatalogRecord> resolve_(const std::string& target) {
-        if (catalog_ == nullptr) return std::nullopt;
-        auto match = catalog_->resolve_local_identity(target);
-        if (!match) return std::nullopt;
-        return CatalogRecord{
-            .metadata = {
-                .namespaceName = match->namespaceName,
-                .name = match->name,
-                .canonicalName = match->canonicalName,
-                .storeRoot = match->storeRoot,
-            },
-            .match = std::move(*match),
-        };
-    }
+    const CatalogMetadata* metadata_for_store_(const std::string& storeName);
+
+    std::optional<CatalogRecord> resolve_(const std::string& target);
 
     PackageCatalog* catalog_ { nullptr };
     InventoryTrace* trace_ { nullptr };
@@ -217,32 +123,16 @@ enum class CoordinateMatch {
 };
 
 void trace_payload_visit(InventoryTrace* trace,
-                         const std::filesystem::path& versionDir) {
-    if (trace != nullptr) trace->payloadVersionDirs.push_back(versionDir);
-}
+                         const std::filesystem::path& versionDir);
 
 void push_candidate(std::vector<xvm::InstallCoordinate>& candidates,
-                    xvm::InstallCoordinate candidate) {
-    if (candidate.empty() || candidate.version.empty()) return;
-    if (std::ranges::find(candidates, candidate) != candidates.end()) return;
-    candidates.push_back(std::move(candidate));
-}
+                    xvm::InstallCoordinate candidate);
 
 xvm::InstallCoordinate direct_coordinate(const std::string& target,
-                                         const std::string& version) {
-    const auto [namespaceName, bareVersion] = xvm::parse_ns_version(version);
-    return {.ns = namespaceName,
-            .package = target,
-            .version = bareVersion};
-}
+                                         const std::string& version);
 
 const xvm::VData* version_data(const xvm::VersionDB& db,
-                               const TargetVersion& pair) {
-    const auto info = db.find(pair.first);
-    if (info == db.end()) return nullptr;
-    const auto data = info->second.versions.find(pair.second);
-    return data == info->second.versions.end() ? nullptr : &data->second;
-}
+                               const TargetVersion& pair);
 
 struct BoundedSelection {
     std::map<std::string, std::string> members;
@@ -262,122 +152,22 @@ SelectionPtr bounded_selection(const xvm::VersionDB& db,
                                const TargetVersion& seed,
                                SelectionCache& cache,
                                xvm::BindingSelectionResolver& resolver,
-                               InventoryTrace* trace = nullptr) {
-    if (const auto cached = cache.find(seed); cached != cache.end()) {
-        return cached->second;
-    }
-
-    const auto* seedData = version_data(db, seed);
-    if (seedData == nullptr) {
-        cache[seed] = nullptr;
-        return nullptr;
-    }
-    const auto seedInfo = db.find(seed.first);
-    if (seedInfo == db.end()) {
-        cache[seed] = nullptr;
-        return nullptr;
-    }
-    const bool hasCanonicalMetadata = seedData->bindingMembersDeclared
-        || !seedData->bindingMembers.empty()
-        || seedData->bindingHeadersDeclared
-        || !seedData->bindingHeaders.empty()
-        || !seedData->bindingIntegrityIssues.empty()
-        || !seedData->bindingUnreadable.empty();
-    if (!seedData->bindingGroup && !hasCanonicalMetadata
-        && seedInfo->second.bindings.empty()) {
-        cache[seed] = nullptr;
-        return nullptr;
-    }
-
-    if (trace != nullptr) {
-        trace->bindingSelections.push_back(
-            seed.first + "@" + seed.second);
-    }
-    auto selected = resolver.resolve(seed.first, seed.second);
-    if (trace != nullptr) {
-        trace->legacyIncomingIndexBuilds =
-            resolver.legacy_incoming_index_builds();
-    }
-    if (!selected) {
-        cache[seed] = nullptr;
-        return nullptr;
-    }
-    auto value = std::make_shared<BoundedSelection>();
-    value->members = selected->members;
-    value->source = selected->source;
-    if (seedData->bindingGroup) {
-        value->root = TargetVersion{
-            seedData->bindingGroup->rootTarget,
-            seedData->bindingGroup->rootVersion,
-        };
-    }
-
-    for (const auto& [target, version] : value->members) {
-        cache[{target, version}] = value;
-    }
-    return value;
-}
+                               InventoryTrace* trace = nullptr);
 
 bool legacy_root_in_selection(const xvm::VersionDB& db,
                               const BoundedSelection& selection,
-                              const TargetVersion& candidate) {
-    for (const auto& [peerTarget, peerVersion] : selection.members) {
-        if (peerTarget == candidate.first) continue;
-        const auto peer = db.find(peerTarget);
-        if (peer == db.end()) continue;
-        const auto binding = peer->second.bindings.find(candidate.first);
-        if (binding == peer->second.bindings.end()) continue;
-        const auto edge = binding->second.find(peerVersion);
-        if (edge != binding->second.end()
-            && edge->second == candidate.second) {
-            return true;
-        }
-    }
-    return false;
-}
+                              const TargetVersion& candidate);
 
 std::vector<xvm::InstallCoordinate> direct_owner_candidates_for(
     const xvm::VersionDB& db,
-    const TargetVersion& pair) {
-    std::vector<xvm::InstallCoordinate> candidates;
-    const auto* data = version_data(db, pair);
-    if (data && data->bindingGroup
-        && !data->bindingGroup->providerVersion.empty()) {
-        const auto provider = parse_package_target(
-            data->bindingGroup->provider);
-        push_candidate(candidates, {
-            .ns = provider.namespaceName,
-            .package = provider.name,
-            .version = xvm::strip_namespace(
-                data->bindingGroup->providerVersion),
-        });
-    }
-    if (data) {
-        if (auto fromPath = xvm::coordinate_from_payload_path(data->path)) {
-            push_candidate(candidates, std::move(*fromPath));
-        }
-    }
-    push_candidate(candidates, direct_coordinate(pair.first, pair.second));
-    return candidates;
-}
+    const TargetVersion& pair);
 
 using IncomingEdgeIndex =
     std::map<TargetVersion, std::vector<TargetVersion>>;
 
 // Every `source -> destination` edge, read backwards. Built at most once per
 // query and only when a filter is present.
-IncomingEdgeIndex build_incoming_edges(const xvm::VersionDB& db) {
-    IncomingEdgeIndex incoming;
-    for (const auto& [sourceTarget, sourceInfo] : db) {
-        for (const auto& [destinationTarget, versions] : sourceInfo.bindings) {
-            for (const auto& [sourceVersion, destinationVersion] : versions) {
-                incoming[{destinationTarget, destinationVersion}]
-                    .emplace_back(sourceTarget, sourceVersion);
-            }
-        }
-    }
-    return incoming;
-}
+IncomingEdgeIndex build_incoming_edges(const xvm::VersionDB& db);
 
 // A cheap over-approximation of owner_candidates_for, used only to decide
 // whether a filtered query can skip a pair before paying for full binding
@@ -393,155 +183,30 @@ IncomingEdgeIndex build_incoming_edges(const xvm::VersionDB& db) {
 std::vector<xvm::InstallCoordinate> shallow_owner_candidates_for(
     const xvm::VersionDB& db,
     const TargetVersion& pair,
-    const IncomingEdgeIndex* incoming = nullptr) {
-    auto candidates = direct_owner_candidates_for(db, pair);
-    const auto* data = version_data(db, pair);
-    if (data && data->bindingGroup) {
-        const TargetVersion root{
-            data->bindingGroup->rootTarget,
-            data->bindingGroup->rootVersion,
-        };
-        if (root != pair) {
-            push_candidate(candidates, direct_coordinate(
-                root.first, root.second));
-            if (const auto* rootData = version_data(db, root)) {
-                if (auto fromPath =
-                        xvm::coordinate_from_payload_path(rootData->path)) {
-                    push_candidate(candidates, std::move(*fromPath));
-                }
-            }
-        }
-        return candidates;
-    }
-
-    std::vector<TargetVersion> pending{pair};
-    std::set<TargetVersion> visited;
-    const auto reach = [&](const TargetVersion& peer) {
-        push_candidate(candidates, direct_coordinate(peer.first, peer.second));
-        if (const auto* peerData = version_data(db, peer)) {
-            if (auto fromPath =
-                    xvm::coordinate_from_payload_path(peerData->path)) {
-                push_candidate(candidates, std::move(*fromPath));
-            }
-        }
-        if (!visited.contains(peer)) pending.push_back(peer);
-    };
-    while (!pending.empty()) {
-        auto current = std::move(pending.back());
-        pending.pop_back();
-        if (!visited.insert(current).second) continue;
-        if (incoming != nullptr) {
-            if (const auto found = incoming->find(current);
-                found != incoming->end()) {
-                for (const auto& source : found->second) reach(source);
-            }
-        }
-        const auto info = db.find(current.first);
-        if (info == db.end()) continue;
-        for (const auto& [peerTarget, versions] : info->second.bindings) {
-            const auto edge = versions.find(current.second);
-            if (edge == versions.end()) continue;
-            reach(TargetVersion{peerTarget, edge->second});
-        }
-    }
-    return candidates;
-}
+    const IncomingEdgeIndex* incoming = nullptr);
 
 std::vector<xvm::InstallCoordinate> owner_candidates_for(
     const xvm::VersionDB& db,
     const TargetVersion& pair,
     SelectionCache& selectionCache,
     xvm::BindingSelectionResolver& resolver,
-    InventoryTrace* trace = nullptr) {
-    auto candidates = direct_owner_candidates_for(db, pair);
-
-    const auto selection = bounded_selection(
-        db, pair, selectionCache, resolver, trace);
-    if (!selection) return candidates;
-    if (selection->source == xvm::BindingSource::ProviderGroup) {
-        if (selection->root && *selection->root != pair) {
-            push_candidate(candidates, direct_coordinate(
-                selection->root->first, selection->root->second));
-            if (const auto* rootData = version_data(db, *selection->root)) {
-                if (auto fromPath =
-                        xvm::coordinate_from_payload_path(rootData->path)) {
-                    push_candidate(candidates, std::move(*fromPath));
-                }
-            }
-        }
-        return candidates;
-    }
-
-    for (const auto& [target, version] : selection->members) {
-        const TargetVersion candidate{target, version};
-        if (candidate == pair
-            || !legacy_root_in_selection(db, *selection, candidate)) {
-            continue;
-        }
-        push_candidate(candidates, direct_coordinate(target, version));
-        if (const auto* rootData = version_data(db, candidate)) {
-            if (auto fromPath =
-                    xvm::coordinate_from_payload_path(rootData->path)) {
-                push_candidate(candidates, std::move(*fromPath));
-            }
-        }
-    }
-    return candidates;
-}
+    InventoryTrace* trace = nullptr);
 
 bool identity_matches(std::string_view namespaceName,
                       std::string_view name,
                       std::string_view filter,
-                      CoordinateMatch match) {
-    if (filter.empty()) return true;
-    const auto canonical = canonical_package_name(namespaceName, name);
-    if (match == CoordinateMatch::exact) return canonical == filter;
-    return canonical.contains(filter) || name.contains(filter);
-}
+                      CoordinateMatch match);
 
 bool candidate_may_match(const xvm::InstallCoordinate& candidate,
                          std::string_view filter,
-                         CoordinateMatch match) {
-    return identity_matches(
-        candidate.ns, candidate.package, filter, match);
-}
+                         CoordinateMatch match);
 
 OwnedCoordinate resolve_owner(
     std::span<const xvm::InstallCoordinate> candidates,
     const TargetVersion& pair,
     std::span<const std::filesystem::path> storeRoots,
     MetadataLookup& metadata,
-    InventoryTrace* trace = nullptr) {
-    for (const auto& candidate : candidates) {
-        if (const auto* found = metadata.by_identity(
-                candidate.ns, candidate.package)) {
-            return {.coordinate = candidate, .storeRoot = found->storeRoot};
-        }
-    }
-    for (const auto& candidate : candidates) {
-        for (const auto& root : storeRoots) {
-            const auto versionDir = root
-                / package_store_name(candidate.ns, candidate.package)
-                / candidate.version;
-            trace_payload_visit(trace, versionDir);
-            std::error_code ec;
-            if (std::filesystem::is_directory(versionDir, ec)) {
-                return {.coordinate = candidate, .storeRoot = root};
-            }
-        }
-    }
-    if (const auto* unique = metadata.by_short_name(pair.first)) {
-        const auto [_, bareVersion] = xvm::parse_ns_version(pair.second);
-        return {
-            .coordinate = {.ns = unique->namespaceName,
-                           .package = unique->name,
-                           .version = bareVersion},
-            .storeRoot = unique->storeRoot,
-        };
-    }
-    if (!candidates.empty()) return {.coordinate = candidates.front()};
-    return {.coordinate = direct_coordinate(pair.first, pair.second)};
-}
+    InventoryTrace* trace = nullptr);
 
 RelatedCoordinates build_owner_coordinates(
     const xvm::VersionDB& db,
@@ -550,98 +215,14 @@ RelatedCoordinates build_owner_coordinates(
     std::span<const std::filesystem::path> storeRoots,
     MetadataLookup& metadata,
     InventoryTrace* trace = nullptr,
-    CoordinateMatch match = CoordinateMatch::contains) {
-    RelatedCoordinates related;
-    SelectionCache selectionCache;
-    xvm::BindingSelectionResolver bindingResolver{db};
-    // Only a filtered query can skip a pair, so only a filtered query pays for
-    // the reverse index the skip decision needs to be safe.
-    std::optional<IncomingEdgeIndex> incoming;
-    if (!filter.empty()) incoming = build_incoming_edges(db);
-    for (const auto& pair : requested) {
-        if (!filter.empty()) {
-            const auto shallow = shallow_owner_candidates_for(
-                db, pair, incoming ? &*incoming : nullptr);
-            auto mayMatch = std::ranges::any_of(
-                shallow, [&](const auto& candidate) {
-                    return candidate_may_match(candidate, filter, match);
-                });
-            if (!mayMatch) {
-                const auto* unique = metadata.by_short_name(pair.first);
-                mayMatch = unique != nullptr
-                    && identity_matches(unique->namespaceName, unique->name,
-                                        filter, match);
-            }
-            if (!mayMatch) continue;
-        }
-        auto candidates = owner_candidates_for(
-            db, pair, selectionCache, bindingResolver, trace);
-        auto owner = resolve_owner(
-            candidates, pair, storeRoots, metadata, trace);
-        if (!identity_matches(owner.coordinate.ns, owner.coordinate.package,
-                              filter, match)) {
-            continue;
-        }
-        related.emplace(pair, std::move(owner));
-    }
-    return related;
-}
-
-std::vector<InventoryWorkspace> load_inventory_workspaces(bool allSubos) {
-    std::vector<InventoryWorkspace> workspaces;
-    const auto currentName = Config::paths().subosDir.filename().string();
-    workspaces.push_back({
-        .name = currentName.empty() ? std::string{"current"} : currentName,
-        .active = Config::effective_workspace(),
-        .installed = Config::workspace_installed(),
-        .current = true,
-    });
-    if (!allSubos) return workspaces;
-
-    for (auto& snapshot : profile::load_subos_snapshots(
-             Config::paths().homeDir)) {
-        std::error_code equivalentEc;
-        const auto samePath = std::filesystem::equivalent(
-            snapshot.dir, Config::paths().subosDir, equivalentEc);
-        if (snapshot.name == currentName || samePath) continue;
-        workspaces.push_back({
-            .name = snapshot.name,
-            .active = std::move(snapshot.workspace.active),
-            .installed = std::move(snapshot.workspace.installed),
-            .current = false,
-        });
-    }
-    return workspaces;
-}
+    CoordinateMatch match = CoordinateMatch::contains);
+
+std::vector<InventoryWorkspace> load_inventory_workspaces(bool allSubos);
 
 std::set<TargetVersion> requested_pairs(
-    std::span<const InventoryWorkspace> workspaces) {
-    std::set<TargetVersion> requested;
-    for (const auto& workspace : workspaces) {
-        for (const auto& [target, versions] : workspace.installed) {
-            for (const auto& version : versions) {
-                requested.emplace(target, version);
-            }
-        }
-        for (const auto& [target, version] : workspace.active) {
-            requested.emplace(target, version);
-        }
-    }
-    return requested;
-}
-
-std::vector<std::filesystem::path> inventory_store_roots() {
-    std::vector<std::filesystem::path> roots;
-    if (Config::has_project_config()) {
-        const auto projectData = Config::project_data_dir();
-        if (!projectData.empty()) roots.push_back(projectData / "xpkgs");
-    }
-    const auto global = Config::global_data_dir() / "xpkgs";
-    if (std::ranges::find(roots, global) == roots.end()) {
-        roots.push_back(global);
-    }
-    return roots;
-}
+    std::span<const InventoryWorkspace> workspaces);
+
+std::vector<std::filesystem::path> inventory_store_roots();
 
 std::vector<InstalledPackageRecord> assemble_inventory(
     const xvm::VersionDB& db,
@@ -651,173 +232,7 @@ std::vector<InstalledPackageRecord> assemble_inventory(
     std::string_view filter,
     CoordinateMatch match,
     InventoryTrace* trace = nullptr,
-    bool includePayloadOnly = true) {
-    const auto requested = requested_pairs(workspaces);
-    const auto related = build_owner_coordinates(
-        db, requested, filter, storeRoots, metadata, trace, match);
-    // Built once for the whole inventory rather than per record: the query
-    // contract says local commands answer immediately, and one pass over the
-    // DB is what keeps `info` proportional to the answer instead of the home.
-    const LedgerIndex ledgerIndex(db, Config::paths().homeDir.string());
-    std::map<std::string, InstalledPackageRecord> records;
-    std::map<std::string, std::filesystem::path> catalogFallbacks;
-    std::set<std::string> workspaceDerived;
-    std::set<std::string> stampDerived;
-
-    const auto ensure_record = [&](const OwnedCoordinate& owned)
-        -> InstalledPackageRecord& {
-        const auto& coordinate = owned.coordinate;
-        auto [it, inserted] = records.try_emplace(coordinate.canonical());
-        auto& record = it->second;
-        if (inserted) {
-            record.namespaceName = coordinate.ns;
-            record.name = coordinate.package;
-            record.canonicalName = canonical_package_name(
-                coordinate.ns, coordinate.package);
-            record.version = coordinate.version;
-        }
-        if (!owned.storeRoot.empty()) {
-            catalogFallbacks.try_emplace(coordinate.canonical(),
-                owned.storeRoot
-                / package_store_name(coordinate.ns, coordinate.package)
-                / coordinate.version);
-        }
-        return record;
-    };
-
-    for (const auto& workspace : workspaces) {
-        for (const auto& [target, versions] : workspace.installed) {
-            for (const auto& version : versions) {
-                const auto found = related.find({target, version});
-                if (found == related.end()) continue;
-                auto& record = ensure_record(found->second);
-                workspaceDerived.insert(found->second.coordinate.canonical());
-                record.suboses.insert(workspace.name);
-                record.inCurrentSubos |= workspace.current;
-            }
-        }
-        for (const auto& [target, version] : workspace.active) {
-            const auto found = related.find({target, version});
-            if (found == related.end()) continue;
-            auto& record = ensure_record(found->second);
-            workspaceDerived.insert(found->second.coordinate.canonical());
-            record.suboses.insert(workspace.name);
-            record.inCurrentSubos |= workspace.current;
-            record.active = true;
-        }
-    }
-
-    // Project comes first. If both stores contain the same canonical stamp,
-    // the project-scoped payload is the one the catalog also prefers.
-    if (includePayloadOnly) for (const auto& storeRoot : storeRoots) {
-        std::error_code ec;
-        if (!std::filesystem::is_directory(storeRoot, ec)) continue;
-        for (const auto& packageDir : platform::dir_entries(storeRoot)) {
-            if (!packageDir.is_directory(ec)) continue;
-            const auto storeName = packageDir.path().filename().string();
-            const auto [namespaceName, name] =
-                identity_from_store_name(storeName);
-            if (!identity_matches(namespaceName, name, filter, match)) continue;
-            for (const auto& versionDir :
-                    platform::dir_entries(packageDir.path())) {
-                if (!versionDir.is_directory(ec)) continue;
-                trace_payload_visit(trace, versionDir.path());
-                const auto stamped = std::filesystem::is_regular_file(
-                    versionDir.path()
-                        / std::filesystem::path(kPayloadStampFile), ec);
-                ec.clear();
-                const auto legacyMarked = std::filesystem::is_regular_file(
-                    versionDir.path() / ".xim-installed", ec);
-                if (!stamped && !legacyMarked) continue;
-                OwnedCoordinate owned{
-                    .coordinate = {.ns = namespaceName,
-                                   .package = name,
-                                   .version = versionDir.path()
-                                                  .filename().string()},
-                    .storeRoot = storeRoot,
-                };
-                auto& record = ensure_record(owned);
-                if (stampDerived.insert(
-                        owned.coordinate.canonical()).second) {
-                    record.payloadPath = versionDir.path();
-                }
-            }
-        }
-    }
-
-    std::vector<InstalledPackageRecord> result;
-    result.reserve(records.size());
-    for (auto& [coordinate, record] : records) {
-        const auto* found = workspaceDerived.contains(coordinate)
-            ? metadata.load_details(record.namespaceName, record.name)
-            : metadata.load_stamped_details(
-                  record.namespaceName, record.name);
-        if (found) {
-            record.namespaceName = found->namespaceName;
-            record.name = found->name;
-            record.canonicalName = found->canonicalName;
-            record.description = found->description;
-            record.programs = found->programs;
-            if (!found->storeRoot.empty()) {
-                catalogFallbacks.try_emplace(coordinate,
-                    found->storeRoot
-                    / package_store_name(record.namespaceName, record.name)
-                    / record.version);
-            }
-        }
-        if (record.payloadPath.empty()) {
-            for (const auto& root : storeRoots) {
-                const auto candidate = root
-                    / package_store_name(record.namespaceName, record.name)
-                    / record.version;
-                trace_payload_visit(trace, candidate);
-                std::error_code ec;
-                if (std::filesystem::is_directory(candidate, ec)) {
-                    record.payloadPath = candidate;
-                    break;
-                }
-            }
-        }
-        if (record.payloadPath.empty()) {
-            if (const auto fallback = catalogFallbacks.find(coordinate);
-                fallback != catalogFallbacks.end()) {
-                record.payloadPath = fallback->second;
-            }
-        }
-        if (record.payloadPath.empty() && !storeRoots.empty()) {
-            record.payloadPath = storeRoots.back()
-                / package_store_name(record.namespaceName, record.name)
-                / record.version;
-        }
-        trace_payload_visit(trace, record.payloadPath);
-        record.payloadPresent = payload_has_content(record.payloadPath);
-        // Asked here rather than derived from the two flags above, because the
-        // interesting cases are exactly the ones those flags agree on: a
-        // stamped payload with no ledger entry has `payloadPresent` true and an
-        // index entry, and is unusable. One answerer, asked by everyone.
-        if (const auto state = installation_state(
-                ledgerIndex, record.namespaceName, record.name,
-                record.version, record.payloadPath);
-            state.is_incomplete()) {
-            record.incomplete = true;
-            record.incompleteReason = state.reason;
-        }
-        if (!record.payloadPresent) {
-            record.degradedReason = "payload missing";
-        } else if (!found) {
-            record.degradedReason = "index entry unavailable";
-        }
-        result.push_back(std::move(record));
-    }
-
-    std::ranges::stable_sort(result, [](const auto& lhs, const auto& rhs) {
-        if (lhs.canonicalName != rhs.canonicalName) {
-            return lhs.canonicalName < rhs.canonicalName;
-        }
-        return version_order::compare(lhs.version, rhs.version) > 0;
-    });
-    return result;
-}
+    bool includePayloadOnly = true);
 
 // Compatibility seam for the deterministic inventory tests and callers that
 // intentionally exclude payload-only records. Production queries use the
@@ -827,12 +242,7 @@ std::vector<InstalledPackageRecord> assemble_inventory(
     std::span<const InventoryWorkspace> workspaces,
     const std::filesystem::path& storeRoot,
     MetadataLookup& metadata,
-    bool includePayloadOnly) {
-    const std::array roots{storeRoot};
-    return assemble_inventory(
-        db, workspaces, roots, metadata, {}, CoordinateMatch::contains,
-        nullptr, includePayloadOnly);
-}
+    bool includePayloadOnly);
 
 }  // namespace detail
 
@@ -840,32 +250,15 @@ std::vector<InstalledPackageRecord> collect_inventory_impl(
     PackageCatalog& catalog, bool allSubos,
     std::optional<std::string_view> filter,
     detail::CoordinateMatch match,
-    InventoryTrace* trace) {
-    detail::MetadataLookup metadata(catalog, trace);
-    const auto workspaces = detail::load_inventory_workspaces(allSubos);
-    const auto storeRoots = detail::inventory_store_roots();
-    return detail::assemble_inventory(
-        Config::versions(), workspaces, storeRoots, metadata,
-        filter.value_or(std::string_view{}), match, trace);
-}
+    InventoryTrace* trace);
 
 std::vector<InstalledPackageRecord> collect_inventory(
     PackageCatalog& catalog, bool allSubos,
     std::optional<std::string_view> canonicalFilter = std::nullopt,
-    InventoryTrace* trace = nullptr) {
-    return collect_inventory_impl(
-        catalog, allSubos, canonicalFilter,
-        detail::CoordinateMatch::contains, trace);
-}
+    InventoryTrace* trace = nullptr);
 
 std::vector<InstalledPackageRecord> collect_package_inventory(
     PackageCatalog& catalog, const std::string& canonicalName,
-    bool allSubos = true, InventoryTrace* trace = nullptr) {
-    const auto parsed = parse_package_target(canonicalName);
-    if (parsed.name.empty() || !parsed.version.empty()) return {};
-    return collect_inventory_impl(
-        catalog, allSubos, std::string_view{canonicalName},
-        detail::CoordinateMatch::exact, trace);
-}
+    bool allSubos = true, InventoryTrace* trace = nullptr);
 
 }  // namespace xlings::xim
diff --git a/src/core/xim/libxpkg/types/script.cpp b/src/core/xim/libxpkg/types/script.cpp
new file mode 100644
index 00000000..4a74cf0f
--- /dev/null
+++ b/src/core/xim/libxpkg/types/script.cpp
@@ -0,0 +1,133 @@
+module xlings.core.xim.libxpkg.types.script;
+
+import std;
+import xlings.core.xim.libxpkg.types.type;
+import xlings.core.xim.catalog;
+import xlings.core.common;
+import xlings.core.config;
+import xlings.core.log;
+import xlings.core.xself;
+import xlings.core.xvm.db;
+import xlings.core.xvm.removal;
+import mcpplibs.xpkg.executor;
+
+namespace xlings::xim::script {
+
+bool default_install(const PlanNode& node,
+                     mcpplibs::xpkg::ExecutionContext& ctx) {
+    auto dest = ctx.install_dir / (node.name + ".lua");
+    std::error_code ec;
+    std::filesystem::create_directories(ctx.install_dir, ec);
+    if (ec) {
+        log::error("failed to create install dir {}: {}", ctx.install_dir.string(), ec.message());
+        return false;
+    }
+    std::filesystem::copy_file(node.pkgFile, dest,
+                               std::filesystem::copy_options::overwrite_existing, ec);
+    if (ec) {
+        log::error("failed to copy script {} -> {}: {}", node.pkgFile.string(), dest.string(), ec.message());
+        return false;
+    }
+    log::debug("script installed: {}", dest.string());
+    return true;
+}
+
+bool default_config(const PlanNode& node,
+                    const std::filesystem::path& dataDir,
+                    const std::string& versionNamespace) {
+    auto storeName = package_store_name(node.namespaceName, node.name);
+    auto targetScript = (node.storeRoot.empty() ? (dataDir / "xpkgs") : node.storeRoot)
+        / storeName
+        / node.version
+        / (node.name + ".lua");
+
+    auto alias = "xlings script " + targetScript.string();
+    auto bindir = targetScript.parent_path().string();
+
+    xvm::add_version(Config::versions_mut(),
+                     node.name, node.version, bindir, "program", "", alias,
+                     versionNamespace);
+
+    auto ver_key = xvm::make_ns_version(versionNamespace, node.version);
+    Config::workspace_mut()[node.name] = ver_key;
+
+    auto paths = Config::paths();
+#ifdef _WIN32
+    auto xlings_bin = paths.homeDir / "bin" / "xlings.exe";
+    constexpr std::string_view shim_ext = ".exe";
+#else
+    auto xlings_bin = paths.homeDir / "bin" / "xlings";
+    constexpr std::string_view shim_ext = "";
+#endif
+    // Bootstrap-layout fallback: pre-`self init` the binary may live
+    // directly at <homeDir>/xlings before being moved under bin/.
+    // Matches the resolution used in xvm/commands.cppm and xself/doctor.cppm.
+    if (!std::filesystem::exists(xlings_bin))
+        xlings_bin = paths.homeDir / ("xlings" + std::string(shim_ext));
+
+    if (std::filesystem::exists(xlings_bin)) {
+        std::string shim_name = node.name;
+        if (!shim_ext.empty() && !shim_name.ends_with(shim_ext))
+            shim_name += std::string(shim_ext);
+        std::filesystem::create_directories(paths.binDir);
+        xself::create_shim(xlings_bin, paths.binDir / shim_name);
+        common::mirror_shim_to_global_bin(xlings_bin, shim_name);
+    }
+
+    Config::save_versions();
+    Config::save_workspace();
+    return true;
+}
+
+bool default_uninstall(const std::string& name, const std::string& version) {
+    if (version.empty()) return false;
+
+    auto exactVersion = xvm::resolve_exact_version_key(
+        Config::versions_mut(), name, version);
+    if (!exactVersion) return false;
+    const auto wasActive =
+        Config::workspace().contains(name)
+        && Config::workspace().at(name) == *exactVersion;
+    const std::vector<xvm::RemovalOperation> operations{
+        {
+            .op = "remove",
+            .name = name,
+            .version = *exactVersion,
+        },
+    };
+    auto removal = xvm::apply_removal_batch(
+        Config::versions_mut(),
+        Config::workspace_mut(),
+        Config::workspace_installed_mut(),
+        operations,
+        {});
+    if (!removal) return false;
+
+    auto paths = Config::paths();
+#ifdef _WIN32
+    constexpr std::string_view shim_ext = ".exe";
+#else
+    constexpr std::string_view shim_ext = "";
+#endif
+    std::string shim_name = name;
+    if (!shim_ext.empty() && !shim_name.ends_with(shim_ext))
+        shim_name += std::string(shim_ext);
+    auto shim_path = paths.binDir / shim_name;
+    if (wasActive
+        && !xvm::has_usable_workspace_version(
+            Config::versions_mut(),
+            Config::workspace_installed(),
+            name)) {
+        std::error_code ec;
+        if (std::filesystem::exists(shim_path, ec)) {
+            ec.clear();
+            std::filesystem::remove(shim_path, ec);
+        }
+    }
+
+    Config::save_versions();
+    Config::save_workspace();
+    return true;
+}
+
+}
diff --git a/src/core/xim/libxpkg/types/script.cppm b/src/core/xim/libxpkg/types/script.cppm
index ced72b5e..96c51185 100644
--- a/src/core/xim/libxpkg/types/script.cppm
+++ b/src/core/xim/libxpkg/types/script.cppm
@@ -3,9 +3,7 @@ export module xlings.core.xim.libxpkg.types.script;
 import std;
 import xlings.core.xim.libxpkg.types.type;
 import xlings.core.xim.catalog;
-import xlings.core.common;
 import xlings.core.config;
-import xlings.core.log;
 import xlings.core.xself;
 import xlings.core.xvm.db;
 import xlings.core.xvm.removal;
@@ -14,120 +12,12 @@ import mcpplibs.xpkg.executor;
 export namespace xlings::xim::script {
 
 bool default_install(const PlanNode& node,
-                     mcpplibs::xpkg::ExecutionContext& ctx) {
-    auto dest = ctx.install_dir / (node.name + ".lua");
-    std::error_code ec;
-    std::filesystem::create_directories(ctx.install_dir, ec);
-    if (ec) {
-        log::error("failed to create install dir {}: {}", ctx.install_dir.string(), ec.message());
-        return false;
-    }
-    std::filesystem::copy_file(node.pkgFile, dest,
-                               std::filesystem::copy_options::overwrite_existing, ec);
-    if (ec) {
-        log::error("failed to copy script {} -> {}: {}", node.pkgFile.string(), dest.string(), ec.message());
-        return false;
-    }
-    log::debug("script installed: {}", dest.string());
-    return true;
-}
+                     mcpplibs::xpkg::ExecutionContext& ctx);
 
 bool default_config(const PlanNode& node,
                     const std::filesystem::path& dataDir,
-                    const std::string& versionNamespace) {
-    auto storeName = package_store_name(node.namespaceName, node.name);
-    auto targetScript = (node.storeRoot.empty() ? (dataDir / "xpkgs") : node.storeRoot)
-        / storeName
-        / node.version
-        / (node.name + ".lua");
+                    const std::string& versionNamespace);
 
-    auto alias = "xlings script " + targetScript.string();
-    auto bindir = targetScript.parent_path().string();
-
-    xvm::add_version(Config::versions_mut(),
-                     node.name, node.version, bindir, "program", "", alias,
-                     versionNamespace);
-
-    auto ver_key = xvm::make_ns_version(versionNamespace, node.version);
-    Config::workspace_mut()[node.name] = ver_key;
-
-    auto paths = Config::paths();
-#ifdef _WIN32
-    auto xlings_bin = paths.homeDir / "bin" / "xlings.exe";
-    constexpr std::string_view shim_ext = ".exe";
-#else
-    auto xlings_bin = paths.homeDir / "bin" / "xlings";
-    constexpr std::string_view shim_ext = "";
-#endif
-    // Bootstrap-layout fallback: pre-`self init` the binary may live
-    // directly at <homeDir>/xlings before being moved under bin/.
-    // Matches the resolution used in xvm/commands.cppm and xself/doctor.cppm.
-    if (!std::filesystem::exists(xlings_bin))
-        xlings_bin = paths.homeDir / ("xlings" + std::string(shim_ext));
-
-    if (std::filesystem::exists(xlings_bin)) {
-        std::string shim_name = node.name;
-        if (!shim_ext.empty() && !shim_name.ends_with(shim_ext))
-            shim_name += std::string(shim_ext);
-        std::filesystem::create_directories(paths.binDir);
-        xself::create_shim(xlings_bin, paths.binDir / shim_name);
-        common::mirror_shim_to_global_bin(xlings_bin, shim_name);
-    }
-
-    Config::save_versions();
-    Config::save_workspace();
-    return true;
-}
-
-bool default_uninstall(const std::string& name, const std::string& version) {
-    if (version.empty()) return false;
-
-    auto exactVersion = xvm::resolve_exact_version_key(
-        Config::versions_mut(), name, version);
-    if (!exactVersion) return false;
-    const auto wasActive =
-        Config::workspace().contains(name)
-        && Config::workspace().at(name) == *exactVersion;
-    const std::vector<xvm::RemovalOperation> operations{
-        {
-            .op = "remove",
-            .name = name,
-            .version = *exactVersion,
-        },
-    };
-    auto removal = xvm::apply_removal_batch(
-        Config::versions_mut(),
-        Config::workspace_mut(),
-        Config::workspace_installed_mut(),
-        operations,
-        {});
-    if (!removal) return false;
-
-    auto paths = Config::paths();
-#ifdef _WIN32
-    constexpr std::string_view shim_ext = ".exe";
-#else
-    constexpr std::string_view shim_ext = "";
-#endif
-    std::string shim_name = name;
-    if (!shim_ext.empty() && !shim_name.ends_with(shim_ext))
-        shim_name += std::string(shim_ext);
-    auto shim_path = paths.binDir / shim_name;
-    if (wasActive
-        && !xvm::has_usable_workspace_version(
-            Config::versions_mut(),
-            Config::workspace_installed(),
-            name)) {
-        std::error_code ec;
-        if (std::filesystem::exists(shim_path, ec)) {
-            ec.clear();
-            std::filesystem::remove(shim_path, ec);
-        }
-    }
-
-    Config::save_versions();
-    Config::save_workspace();
-    return true;
-}
+bool default_uninstall(const std::string& name, const std::string& version);
 
 } // namespace xlings::xim::script
diff --git a/src/core/xim/libxpkg/types/subos.cpp b/src/core/xim/libxpkg/types/subos.cpp
new file mode 100644
index 00000000..d153b25e
--- /dev/null
+++ b/src/core/xim/libxpkg/types/subos.cpp
@@ -0,0 +1,109 @@
+module xlings.core.xim.libxpkg.types.subos;
+
+import std;
+import xlings.core.xim.libxpkg.types.type;
+import xlings.core.xim.catalog;
+import xlings.core.common;
+import xlings.core.config;
+import xlings.core.log;
+import xlings.core.xvm.db;
+import xlings.core.xvm.removal;
+import xlings.libs.json;
+import mcpplibs.xpkg.executor;
+
+namespace xlings::xim::subos {
+
+bool default_install(const PlanNode& node,
+                     mcpplibs::xpkg::ExecutionContext& ctx) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+
+    fs::create_directories(ctx.install_dir, ec);
+    if (ec) {
+        log::error("subos: failed to create install dir {}: {}",
+                   ctx.install_dir.string(), ec.message());
+        return false;
+    }
+
+    // Ensure bin/ exists for shim placement at fork time (subos new --from
+    // expects to find this layout).
+    fs::create_directories(ctx.install_dir / "bin", ec);
+
+    // If tarball already laid down .xlings.json, leave it untouched (author
+    // intent). Otherwise synthesize a minimal workspace from xpm.deps so
+    // `subos new --from <pkg>` has a workspace to copy.
+    auto xlingsJson = ctx.install_dir / ".xlings.json";
+    if (!fs::exists(xlingsJson)) {
+        nlohmann::json j;
+        j["workspace"] = nlohmann::json::object();
+        for (const auto& dep : node.deps) {
+            // dep tokens look like "name@version", "ns:name@version", or "name"
+            std::string raw = dep;
+            if (auto colon = raw.find(':'); colon != std::string::npos) {
+                raw = raw.substr(colon + 1);
+            }
+            if (auto at = raw.find('@'); at != std::string::npos) {
+                j["workspace"][raw.substr(0, at)] = raw.substr(at + 1);
+            } else if (!raw.empty()) {
+                j["workspace"][raw] = "latest";
+            }
+        }
+        std::ofstream ofs(xlingsJson);
+        ofs << j.dump(2);
+    }
+
+    log::debug("subos base installed at {}", ctx.install_dir.string());
+    return true;
+}
+
+bool default_config(const PlanNode& node,
+                    const std::filesystem::path& dataDir,
+                    const std::string& versionNamespace) {
+    auto storeName = package_store_name(node.namespaceName, node.name);
+    auto installDir = (node.storeRoot.empty() ? (dataDir / "xpkgs") : node.storeRoot)
+        / storeName
+        / node.version;
+    auto bindir = (installDir / "bin").string();
+
+    // Register so `xlings list` / `xlings info` / `xlings uninstall` work
+    // normally. Subos base does NOT need a `xlings`-dispatching shim like
+    // type=script does — the package is a fork source, not a runnable.
+    xvm::add_version(Config::versions_mut(),
+                     node.name, node.version, bindir, "subos-base", "", "",
+                     versionNamespace);
+
+    auto ver_key = xvm::make_ns_version(versionNamespace, node.version);
+    Config::workspace_mut()[node.name] = ver_key;
+
+    Config::save_versions();
+    Config::save_workspace();
+    return true;
+}
+
+bool default_uninstall(const std::string& name, const std::string& version) {
+    // Remove xvm entry; xim's standard uninstall path handles the on-disk
+    // payload at xpkgs/<name>/<ver>/. Forks already in subos/ are independent
+    // and not touched by this — their .xlings.json points to xpkgs they
+    // reference directly (deps), and those deps are independent xpkgs.
+    if (version.empty()) return false;
+    const std::vector<xvm::RemovalOperation> operations{
+        {
+            .op = "remove",
+            .name = name,
+            .version = version,
+        },
+    };
+    auto removal = xvm::apply_removal_batch(
+        Config::versions_mut(),
+        Config::workspace_mut(),
+        Config::workspace_installed_mut(),
+        operations,
+        {});
+    if (!removal) return false;
+
+    Config::save_versions();
+    Config::save_workspace();
+    return true;
+}
+
+}
diff --git a/src/core/xim/libxpkg/types/subos.cppm b/src/core/xim/libxpkg/types/subos.cppm
index c521f48a..5605160d 100644
--- a/src/core/xim/libxpkg/types/subos.cppm
+++ b/src/core/xim/libxpkg/types/subos.cppm
@@ -3,12 +3,9 @@ export module xlings.core.xim.libxpkg.types.subos;
 import std;
 import xlings.core.xim.libxpkg.types.type;
 import xlings.core.xim.catalog;
-import xlings.core.common;
 import xlings.core.config;
-import xlings.core.log;
 import xlings.core.xvm.db;
 import xlings.core.xvm.removal;
-import xlings.libs.json;
 import mcpplibs.xpkg.executor;
 
 // Default xim handlers for `type = "subos"` packages.
@@ -34,96 +31,12 @@ import mcpplibs.xpkg.executor;
 export namespace xlings::xim::subos {
 
 bool default_install(const PlanNode& node,
-                     mcpplibs::xpkg::ExecutionContext& ctx) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-
-    fs::create_directories(ctx.install_dir, ec);
-    if (ec) {
-        log::error("subos: failed to create install dir {}: {}",
-                   ctx.install_dir.string(), ec.message());
-        return false;
-    }
-
-    // Ensure bin/ exists for shim placement at fork time (subos new --from
-    // expects to find this layout).
-    fs::create_directories(ctx.install_dir / "bin", ec);
-
-    // If tarball already laid down .xlings.json, leave it untouched (author
-    // intent). Otherwise synthesize a minimal workspace from xpm.deps so
-    // `subos new --from <pkg>` has a workspace to copy.
-    auto xlingsJson = ctx.install_dir / ".xlings.json";
-    if (!fs::exists(xlingsJson)) {
-        nlohmann::json j;
-        j["workspace"] = nlohmann::json::object();
-        for (const auto& dep : node.deps) {
-            // dep tokens look like "name@version", "ns:name@version", or "name"
-            std::string raw = dep;
-            if (auto colon = raw.find(':'); colon != std::string::npos) {
-                raw = raw.substr(colon + 1);
-            }
-            if (auto at = raw.find('@'); at != std::string::npos) {
-                j["workspace"][raw.substr(0, at)] = raw.substr(at + 1);
-            } else if (!raw.empty()) {
-                j["workspace"][raw] = "latest";
-            }
-        }
-        std::ofstream ofs(xlingsJson);
-        ofs << j.dump(2);
-    }
-
-    log::debug("subos base installed at {}", ctx.install_dir.string());
-    return true;
-}
+                     mcpplibs::xpkg::ExecutionContext& ctx);
 
 bool default_config(const PlanNode& node,
                     const std::filesystem::path& dataDir,
-                    const std::string& versionNamespace) {
-    auto storeName = package_store_name(node.namespaceName, node.name);
-    auto installDir = (node.storeRoot.empty() ? (dataDir / "xpkgs") : node.storeRoot)
-        / storeName
-        / node.version;
-    auto bindir = (installDir / "bin").string();
-
-    // Register so `xlings list` / `xlings info` / `xlings uninstall` work
-    // normally. Subos base does NOT need a `xlings`-dispatching shim like
-    // type=script does — the package is a fork source, not a runnable.
-    xvm::add_version(Config::versions_mut(),
-                     node.name, node.version, bindir, "subos-base", "", "",
-                     versionNamespace);
-
-    auto ver_key = xvm::make_ns_version(versionNamespace, node.version);
-    Config::workspace_mut()[node.name] = ver_key;
-
-    Config::save_versions();
-    Config::save_workspace();
-    return true;
-}
-
-bool default_uninstall(const std::string& name, const std::string& version) {
-    // Remove xvm entry; xim's standard uninstall path handles the on-disk
-    // payload at xpkgs/<name>/<ver>/. Forks already in subos/ are independent
-    // and not touched by this — their .xlings.json points to xpkgs they
-    // reference directly (deps), and those deps are independent xpkgs.
-    if (version.empty()) return false;
-    const std::vector<xvm::RemovalOperation> operations{
-        {
-            .op = "remove",
-            .name = name,
-            .version = version,
-        },
-    };
-    auto removal = xvm::apply_removal_batch(
-        Config::versions_mut(),
-        Config::workspace_mut(),
-        Config::workspace_installed_mut(),
-        operations,
-        {});
-    if (!removal) return false;
+                    const std::string& versionNamespace);
 
-    Config::save_versions();
-    Config::save_workspace();
-    return true;
-}
+bool default_uninstall(const std::string& name, const std::string& version);
 
 } // namespace xlings::xim::subos
diff --git a/src/core/xim/libxpkg/types/type.cpp b/src/core/xim/libxpkg/types/type.cpp
new file mode 100644
index 00000000..c8ad546d
--- /dev/null
+++ b/src/core/xim/libxpkg/types/type.cpp
@@ -0,0 +1,19 @@
+module xlings.core.xim.libxpkg.types.type;
+
+import std;
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::xim {
+
+bool InstallPlan::has_errors() const { return !errors.empty(); }
+
+std::size_t InstallPlan::pending_count() const {
+    std::size_t n = 0;
+    for (auto& nd : nodes)
+        if (!nd.alreadyInstalled) ++n;
+    return n;
+}
+
+} // namespace xlings::xim
diff --git a/src/core/xim/libxpkg/types/type.cppm b/src/core/xim/libxpkg/types/type.cppm
index fc94312e..33dc5371 100644
--- a/src/core/xim/libxpkg/types/type.cppm
+++ b/src/core/xim/libxpkg/types/type.cppm
@@ -115,13 +115,8 @@ struct InstallPlan {
     std::vector<PlanNode> nodes;
     std::vector<std::string> errors;
 
-    bool has_errors() const { return !errors.empty(); }
-    std::size_t pending_count() const {
-        std::size_t n = 0;
-        for (auto& nd : nodes)
-            if (!nd.alreadyInstalled) ++n;
-        return n;
-    }
+    bool has_errors() const;
+    std::size_t pending_count() const;
 
     InstallPlan() = default;
 #if defined(_MSC_VER)
diff --git a/src/core/xim/payload.cpp b/src/core/xim/payload.cpp
new file mode 100644
index 00000000..cf8d7568
--- /dev/null
+++ b/src/core/xim/payload.cpp
@@ -0,0 +1,213 @@
+module xlings.core.xim.payload;
+
+import std;
+import xlings.platform;
+import xlings.core.config;
+
+namespace xlings::xim {
+
+std::string_view host_platform_tag() {
+#if defined(_WIN32)
+    return "windows";
+#elif defined(__APPLE__)
+    return "macosx";
+#else
+    return "linux";
+#endif
+}
+
+std::string_view executable_format_(const std::filesystem::path& file) {
+    std::ifstream in(file, std::ios::binary);
+    if (!in) return "";
+    unsigned char m[4] = {0, 0, 0, 0};
+    in.read(reinterpret_cast<char*>(m), 4);
+    const auto n = in.gcount();
+    if (n >= 4 && m[0] == 0x7F && m[1] == 'E' && m[2] == 'L' && m[3] == 'F')
+        return "linux";
+    if (n >= 2 && m[0] == 'M' && m[1] == 'Z')
+        return "windows";
+    if (n >= 4) {
+        const std::uint32_t w = (std::uint32_t(m[0]) << 24) | (std::uint32_t(m[1]) << 16)
+                              | (std::uint32_t(m[2]) << 8) | std::uint32_t(m[3]);
+        // Mach-O 32/64, both byte orders, plus the fat/universal magic.
+        if (w == 0xFEEDFACEu || w == 0xFEEDFACFu || w == 0xCEFAEDFEu
+            || w == 0xCFFAEDFEu || w == 0xCAFEBABEu || w == 0xBEBAFECAu)
+            return "macosx";
+    }
+    return "";
+}
+
+bool payload_has_content(const std::filesystem::path& dir) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    if (!fs::is_directory(dir, ec)) return false;
+    for (const auto& entry : platform::dir_entries(dir)) {
+        if (entry.path().filename().string() != kPayloadStampFile) return true;
+    }
+    return false;
+}
+
+PayloadPlatform classify_payload_content(const std::filesystem::path& dir) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    if (!fs::is_directory(dir, ec)) return PayloadPlatform::Unknown;
+
+    const auto probeDir = fs::is_directory(dir / "bin", ec) ? dir / "bin" : dir;
+    int examined = 0;
+    bool sawForeign = false;
+    for (const auto& entry : platform::dir_entries(probeDir)) {
+        if (examined >= 8) break;
+        std::error_code fec;
+        if (!fs::is_regular_file(entry.path(), fec)) continue;
+        const auto fmt = executable_format_(entry.path());
+        if (fmt.empty()) continue;   // script, data, unrecognized
+        ++examined;
+        if (fmt == host_platform_tag()) return PayloadPlatform::Host;
+        sawForeign = true;
+    }
+    return sawForeign ? PayloadPlatform::Foreign : PayloadPlatform::Unknown;
+}
+
+PayloadPlatform classify_payload_platform(const std::filesystem::path& dir) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    if (!fs::is_directory(dir, ec)) return PayloadPlatform::Unknown;
+
+    // The stamp is authoritative when present.
+    if (auto stamp = dir / std::filesystem::path(kPayloadStampFile);
+        fs::is_regular_file(stamp, ec)) {
+        // Read as text rather than through the JSON parser: this function is
+        // the first thing in the module and instantiating the parser here
+        // trips a GCC 16 modules failure ("failed to load pendings for
+        // 'std::map'") whose error message names an unrelated module. The
+        // stamp is written by write_payload_stamp below and has exactly one
+        // shape, so a scan for the field is sufficient and total.
+        auto content = platform::read_file_to_string(stamp.string());
+        if (auto key = content.find("\"os\""); key != std::string::npos) {
+            auto colon = content.find(':', key);
+            auto open = colon == std::string::npos
+                ? std::string::npos : content.find('"', colon);
+            auto close = open == std::string::npos
+                ? std::string::npos : content.find('"', open + 1);
+            if (close != std::string::npos) {
+                const auto recorded =
+                    content.substr(open + 1, close - open - 1);
+                return recorded == host_platform_tag()
+                    ? PayloadPlatform::Host : PayloadPlatform::Foreign;
+            }
+        }
+        {
+            // Unreadable stamp: fall through to the heuristic rather than
+            // treating an unparseable file as a verdict.
+        }
+    }
+
+    // No stamp: sample the payload. Deliberately biased toward Unknown --
+    // a false Foreign costs a needless reinstall of a working package, so
+    // ONE file of the host's own format is enough to settle it, and a
+    // payload of scripts settles nothing.
+    return classify_payload_content(dir);
+}
+
+bool stamped_incomplete(const std::filesystem::path& dir) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    const auto stamp = dir / std::filesystem::path(kPayloadStampFile);
+    if (!fs::is_regular_file(stamp, ec)) return false;
+    const auto content = platform::read_file_to_string(stamp.string());
+    const auto key = content.find("\"incomplete\"");
+    if (key == std::string::npos) return false;
+    const auto colon = content.find(':', key);
+    if (colon == std::string::npos) return false;
+    return content.find("true", colon) != std::string::npos
+        && content.find("true", colon) < content.find('\n', colon);
+}
+
+int stamped_registration_count(const std::filesystem::path& dir) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    const auto stamp = dir / std::filesystem::path(kPayloadStampFile);
+    if (!fs::is_regular_file(stamp, ec)) return kRegisteredUnrecorded;
+    // Scanned by hand, like classify_payload_platform above and for the same
+    // reason: instantiating the JSON parser in this module trips a GCC 16
+    // modules failure that names an unrelated module.
+    const auto content = platform::read_file_to_string(stamp.string());
+    const auto key = content.find("\"registered\"");
+    if (key == std::string::npos) return kRegisteredUnrecorded;
+    const auto colon = content.find(':', key);
+    if (colon == std::string::npos) return kRegisteredUnrecorded;
+    std::size_t i = colon + 1;
+    while (i < content.size() && (content[i] == ' ' || content[i] == '\t')) ++i;
+    int value = 0;
+    bool any = false;
+    while (i < content.size() && content[i] >= '0' && content[i] <= '9') {
+        value = value * 10 + (content[i] - '0');
+        ++i;
+        any = true;
+    }
+    return any ? value : kRegisteredUnrecorded;
+}
+
+void write_payload_stamp(const std::filesystem::path& dir, std::string_view version, int registered) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    if (!fs::is_directory(dir, ec)) return;
+    // An empty install dir belongs to a wrapper package whose real payload
+    // lives elsewhere. Writing here would make it look non-empty, which is
+    // the very signal the installed-probe reads.
+    if (fs::is_empty(dir, ec) || ec) return;
+    // Written by hand for the same reason classify_payload_platform reads by
+    // hand (see there). No user input in any field.
+    auto text = std::format(
+        "{{\n  \"os\": \"{}\",\n  \"version\": \"{}\",\n"
+        "  \"xlings_version\": \"{}\"",
+        host_platform_tag(), version, Info::VERSION);
+    if (registered != kRegisteredUnrecorded) {
+        text += std::format(",\n  \"registered\": {}", registered);
+    }
+    text += "\n}\n";
+    platform::write_string_to_file(
+        (dir / std::filesystem::path(kPayloadStampFile)).string(), text);
+}
+
+void write_payload_failure_marker(const std::filesystem::path& dir,
+                                  std::string_view version,
+                                  std::string_view reason) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    fs::create_directories(dir, ec);
+    if (!fs::is_directory(dir, ec)) return;
+    // Quotes and backslashes in the reason would break the hand-written
+    // reader; the field is diagnostic, so sanitising beats escaping.
+    //
+    // Bounded, and runs of whitespace collapsed. A hook failure carries the
+    // bounded hook transcript, and writing that verbatim produced a 4 KB
+    // marker whose `reason` was mostly one repeated padding character. The
+    // field exists to tell a human what went wrong at a glance; the full
+    // transcript already went to the log, where it belongs.
+    constexpr std::size_t kReasonLimit = 200;
+    std::string safe;
+    safe.reserve(std::min(reason.size(), kReasonLimit));
+    bool lastWasSpace = false;
+    for (const char c : reason) {
+        if (safe.size() >= kReasonLimit) { safe += " ..."; break; }
+        const bool space = c == '"' || c == '\\' || c == '\n' || c == '\r'
+                        || c == '\t' || c == ' ';
+        if (space) {
+            if (!lastWasSpace && !safe.empty()) safe.push_back(' ');
+            lastWasSpace = true;
+        } else {
+            safe.push_back(c);
+            lastWasSpace = false;
+        }
+    }
+    const auto text = std::format(
+        "{{\n  \"os\": \"{}\",\n  \"version\": \"{}\",\n"
+        "  \"xlings_version\": \"{}\",\n  \"incomplete\": true,\n"
+        "  \"reason\": \"{}\"\n}}\n",
+        host_platform_tag(), version, Info::VERSION, safe);
+    platform::write_string_to_file(
+        (dir / std::filesystem::path(kPayloadStampFile)).string(), text);
+}
+
+}
diff --git a/src/core/xim/payload.cppm b/src/core/xim/payload.cppm
index 6856f380..11b852e6 100644
--- a/src/core/xim/payload.cppm
+++ b/src/core/xim/payload.cppm
@@ -2,7 +2,6 @@ export module xlings.core.xim.payload;
 
 import std;
 
-import xlings.platform;
 import xlings.core.config;
 
 export namespace xlings::xim {
@@ -26,37 +25,10 @@ enum class PayloadPlatform {
 
 constexpr std::string_view kPayloadStampFile = ".xpkg-install.json";
 
-std::string_view host_platform_tag() {
-#if defined(_WIN32)
-    return "windows";
-#elif defined(__APPLE__)
-    return "macosx";
-#else
-    return "linux";
-#endif
-}
+std::string_view host_platform_tag();
 
 // Classify one executable by its first bytes. Returns "" when unrecognized.
-std::string_view executable_format_(const std::filesystem::path& file) {
-    std::ifstream in(file, std::ios::binary);
-    if (!in) return "";
-    unsigned char m[4] = {0, 0, 0, 0};
-    in.read(reinterpret_cast<char*>(m), 4);
-    const auto n = in.gcount();
-    if (n >= 4 && m[0] == 0x7F && m[1] == 'E' && m[2] == 'L' && m[3] == 'F')
-        return "linux";
-    if (n >= 2 && m[0] == 'M' && m[1] == 'Z')
-        return "windows";
-    if (n >= 4) {
-        const std::uint32_t w = (std::uint32_t(m[0]) << 24) | (std::uint32_t(m[1]) << 16)
-                              | (std::uint32_t(m[2]) << 8) | std::uint32_t(m[3]);
-        // Mach-O 32/64, both byte orders, plus the fat/universal magic.
-        if (w == 0xFEEDFACEu || w == 0xFEEDFACFu || w == 0xCEFAEDFEu
-            || w == 0xCFFAEDFEu || w == 0xCAFEBABEu || w == 0xBEBAFECAu)
-            return "macosx";
-    }
-    return "";
-}
+std::string_view executable_format_(const std::filesystem::path& file);
 
 // Whether the payload holds anything besides our own bookkeeping.
 //
@@ -66,81 +38,15 @@ std::string_view executable_format_(const std::filesystem::path& file) {
 // `.xim-installed` marker is deliberately NOT excluded: wrapper packages
 // whose real payload lives in a dependency use it to mean exactly "installed,
 // nothing here".
-bool payload_has_content(const std::filesystem::path& dir) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    if (!fs::is_directory(dir, ec)) return false;
-    for (const auto& entry : platform::dir_entries(dir)) {
-        if (entry.path().filename().string() != kPayloadStampFile) return true;
-    }
-    return false;
-}
+bool payload_has_content(const std::filesystem::path& dir);
 
 // What the FILES say, ignoring any stamp. Separate from the function below
 // because "should this payload be stamped" must never be answered by reading
 // the stamp: a run that wrote one over a payload it did not actually install
 // would then confirm its own claim forever.
-PayloadPlatform classify_payload_content(const std::filesystem::path& dir) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    if (!fs::is_directory(dir, ec)) return PayloadPlatform::Unknown;
+PayloadPlatform classify_payload_content(const std::filesystem::path& dir);
 
-    const auto probeDir = fs::is_directory(dir / "bin", ec) ? dir / "bin" : dir;
-    int examined = 0;
-    bool sawForeign = false;
-    for (const auto& entry : platform::dir_entries(probeDir)) {
-        if (examined >= 8) break;
-        std::error_code fec;
-        if (!fs::is_regular_file(entry.path(), fec)) continue;
-        const auto fmt = executable_format_(entry.path());
-        if (fmt.empty()) continue;   // script, data, unrecognized
-        ++examined;
-        if (fmt == host_platform_tag()) return PayloadPlatform::Host;
-        sawForeign = true;
-    }
-    return sawForeign ? PayloadPlatform::Foreign : PayloadPlatform::Unknown;
-}
-
-PayloadPlatform classify_payload_platform(const std::filesystem::path& dir) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    if (!fs::is_directory(dir, ec)) return PayloadPlatform::Unknown;
-
-    // The stamp is authoritative when present.
-    if (auto stamp = dir / std::filesystem::path(kPayloadStampFile);
-        fs::is_regular_file(stamp, ec)) {
-        // Read as text rather than through the JSON parser: this function is
-        // the first thing in the module and instantiating the parser here
-        // trips a GCC 16 modules failure ("failed to load pendings for
-        // 'std::map'") whose error message names an unrelated module. The
-        // stamp is written by write_payload_stamp below and has exactly one
-        // shape, so a scan for the field is sufficient and total.
-        auto content = platform::read_file_to_string(stamp.string());
-        if (auto key = content.find("\"os\""); key != std::string::npos) {
-            auto colon = content.find(':', key);
-            auto open = colon == std::string::npos
-                ? std::string::npos : content.find('"', colon);
-            auto close = open == std::string::npos
-                ? std::string::npos : content.find('"', open + 1);
-            if (close != std::string::npos) {
-                const auto recorded =
-                    content.substr(open + 1, close - open - 1);
-                return recorded == host_platform_tag()
-                    ? PayloadPlatform::Host : PayloadPlatform::Foreign;
-            }
-        }
-        {
-            // Unreadable stamp: fall through to the heuristic rather than
-            // treating an unparseable file as a verdict.
-        }
-    }
-
-    // No stamp: sample the payload. Deliberately biased toward Unknown --
-    // a false Foreign costs a needless reinstall of a working package, so
-    // ONE file of the host's own format is enough to settle it, and a
-    // payload of scripts settles nothing.
-    return classify_payload_content(dir);
-}
+PayloadPlatform classify_payload_platform(const std::filesystem::path& dir);
 
 // How many xvm nodes the install that wrote this stamp registered.
 //
@@ -163,44 +69,9 @@ constexpr int kRegisteredUnrecorded = -1;
 // non-convergence this repo already has a postmortem about.
 //
 // So the moment we know -- the hook returned false -- we write it down.
-bool stamped_incomplete(const std::filesystem::path& dir) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    const auto stamp = dir / std::filesystem::path(kPayloadStampFile);
-    if (!fs::is_regular_file(stamp, ec)) return false;
-    const auto content = platform::read_file_to_string(stamp.string());
-    const auto key = content.find("\"incomplete\"");
-    if (key == std::string::npos) return false;
-    const auto colon = content.find(':', key);
-    if (colon == std::string::npos) return false;
-    return content.find("true", colon) != std::string::npos
-        && content.find("true", colon) < content.find('\n', colon);
-}
+bool stamped_incomplete(const std::filesystem::path& dir);
 
-int stamped_registration_count(const std::filesystem::path& dir) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    const auto stamp = dir / std::filesystem::path(kPayloadStampFile);
-    if (!fs::is_regular_file(stamp, ec)) return kRegisteredUnrecorded;
-    // Scanned by hand, like classify_payload_platform above and for the same
-    // reason: instantiating the JSON parser in this module trips a GCC 16
-    // modules failure that names an unrelated module.
-    const auto content = platform::read_file_to_string(stamp.string());
-    const auto key = content.find("\"registered\"");
-    if (key == std::string::npos) return kRegisteredUnrecorded;
-    const auto colon = content.find(':', key);
-    if (colon == std::string::npos) return kRegisteredUnrecorded;
-    std::size_t i = colon + 1;
-    while (i < content.size() && (content[i] == ' ' || content[i] == '\t')) ++i;
-    int value = 0;
-    bool any = false;
-    while (i < content.size() && content[i] >= '0' && content[i] <= '9') {
-        value = value * 10 + (content[i] - '0');
-        ++i;
-        any = true;
-    }
-    return any ? value : kRegisteredUnrecorded;
-}
+int stamped_registration_count(const std::filesystem::path& dir);
 
 // Record what this platform installed, so the next run does not have to guess.
 //
@@ -212,27 +83,7 @@ int stamped_registration_count(const std::filesystem::path& dir) {
 // among them. See .agents/docs/2026-08-11-five-issues-triage-and-plan.md.
 void write_payload_stamp(const std::filesystem::path& dir,
                          std::string_view version,
-                         int registered = kRegisteredUnrecorded) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    if (!fs::is_directory(dir, ec)) return;
-    // An empty install dir belongs to a wrapper package whose real payload
-    // lives elsewhere. Writing here would make it look non-empty, which is
-    // the very signal the installed-probe reads.
-    if (fs::is_empty(dir, ec) || ec) return;
-    // Written by hand for the same reason classify_payload_platform reads by
-    // hand (see there). No user input in any field.
-    auto text = std::format(
-        "{{\n  \"os\": \"{}\",\n  \"version\": \"{}\",\n"
-        "  \"xlings_version\": \"{}\"",
-        host_platform_tag(), version, Info::VERSION);
-    if (registered != kRegisteredUnrecorded) {
-        text += std::format(",\n  \"registered\": {}", registered);
-    }
-    text += "\n}\n";
-    platform::write_string_to_file(
-        (dir / std::filesystem::path(kPayloadStampFile)).string(), text);
-}
+                         int registered = kRegisteredUnrecorded);
 
 // Mark this payload as the residue of an install that did not finish.
 //
@@ -247,42 +98,6 @@ void write_payload_stamp(const std::filesystem::path& dir,
 // retryable, and it is the case that leaves nothing behind.
 void write_payload_failure_marker(const std::filesystem::path& dir,
                                   std::string_view version,
-                                  std::string_view reason) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    fs::create_directories(dir, ec);
-    if (!fs::is_directory(dir, ec)) return;
-    // Quotes and backslashes in the reason would break the hand-written
-    // reader; the field is diagnostic, so sanitising beats escaping.
-    //
-    // Bounded, and runs of whitespace collapsed. A hook failure carries the
-    // bounded hook transcript, and writing that verbatim produced a 4 KB
-    // marker whose `reason` was mostly one repeated padding character. The
-    // field exists to tell a human what went wrong at a glance; the full
-    // transcript already went to the log, where it belongs.
-    constexpr std::size_t kReasonLimit = 200;
-    std::string safe;
-    safe.reserve(std::min(reason.size(), kReasonLimit));
-    bool lastWasSpace = false;
-    for (const char c : reason) {
-        if (safe.size() >= kReasonLimit) { safe += " ..."; break; }
-        const bool space = c == '"' || c == '\\' || c == '\n' || c == '\r'
-                        || c == '\t' || c == ' ';
-        if (space) {
-            if (!lastWasSpace && !safe.empty()) safe.push_back(' ');
-            lastWasSpace = true;
-        } else {
-            safe.push_back(c);
-            lastWasSpace = false;
-        }
-    }
-    const auto text = std::format(
-        "{{\n  \"os\": \"{}\",\n  \"version\": \"{}\",\n"
-        "  \"xlings_version\": \"{}\",\n  \"incomplete\": true,\n"
-        "  \"reason\": \"{}\"\n}}\n",
-        host_platform_tag(), version, Info::VERSION, safe);
-    platform::write_string_to_file(
-        (dir / std::filesystem::path(kPayloadStampFile)).string(), text);
-}
+                                  std::string_view reason);
 
 }  // namespace xlings::xim
diff --git a/src/core/xim/repo.cpp b/src/core/xim/repo.cpp
new file mode 100644
index 00000000..bf861520
--- /dev/null
+++ b/src/core/xim/repo.cpp
@@ -0,0 +1,712 @@
+module;
+#include <ctime>
+
+module xlings.core.xim.repo;
+
+import std;
+import xlings.libs.json;
+import xlings.core.log;
+import xlings.core.compact;
+import xlings.platform;
+import xlings.core.config;
+import xlings.core.mirror;
+import xlings.core.xim.indexfetch;
+import xlings.libs.tinyhttps;
+
+namespace xlings::xim {
+
+namespace detail_ {
+
+bool ensure_local_repo_link_(const std::filesystem::path& localDir,
+                             const std::filesystem::path& sourceDir) {
+    namespace fs = std::filesystem;
+
+    std::error_code ec;
+    if (!fs::exists(sourceDir, ec) || !fs::exists(sourceDir / "pkgs", ec)) {
+        // #374: caller (syncRepos) now treats this as a best-effort skip and
+        // emits the user-facing warning naming the repo; keep this at debug
+        // so a tolerated missing-pkgs source is not reported as a hard error.
+        log::debug("local index repo missing pkgs/: {}", sourceDir.string());
+        return false;
+    }
+
+    if (fs::exists(localDir, ec) || fs::is_symlink(localDir, ec)) {
+        auto canonicalLocal = fs::weakly_canonical(localDir, ec);
+        ec.clear();
+        auto canonicalSource = fs::weakly_canonical(sourceDir, ec);
+        if (!ec && canonicalLocal == canonicalSource) {
+            return true;
+        }
+        ec.clear();
+        fs::remove_all(localDir, ec);
+        if (ec) {
+            log::error("failed to replace local index repo mapping {}: {}",
+                       localDir.string(), ec.message());
+            return false;
+        }
+    }
+
+    fs::create_directories(localDir.parent_path(), ec);
+    if (ec) {
+        log::error("failed to create repo parent directory {}: {}",
+                   localDir.parent_path().string(), ec.message());
+        return false;
+    }
+
+#if defined(_WIN32)
+    if (!platform::create_directory_link(localDir, sourceDir)) {
+        log::error("failed to create directory link: {} -> {}",
+                   localDir.string(), sourceDir.string());
+        return false;
+    }
+#else
+    fs::create_directory_symlink(sourceDir, localDir, ec);
+    if (ec) {
+        log::error("failed to create symlink: {} -> {} ({})",
+                   localDir.string(), sourceDir.string(), ec.message());
+        return false;
+    }
+#endif
+
+    log::debug("linked local index repo: {} -> {}", localDir.string(), sourceDir.string());
+    return true;
+}
+
+std::vector<IndexRepo> discover_sub_repos_(const std::filesystem::path& repoDir,
+                                            const std::string& mirror) {
+    namespace fs = std::filesystem;
+    auto luaFile = repoDir / "xim-indexrepos.lua";
+    if (!fs::exists(luaFile)) return {};
+
+    std::string content;
+    try {
+        content = platform::read_file_to_string(luaFile.string());
+    } catch (...) {
+        return {};
+    }
+
+    std::vector<IndexRepo> repos;
+    // Simple line-based parser to avoid std::regex in modules
+    // State machine: look for ["name"] = { blocks, then ["KEY"] = "url" inside
+    std::istringstream iss(content);
+    std::string line;
+    std::string currentName;
+    std::string globalUrl, mirrorUrl;
+    bool inBlock = false;
+
+    while (std::getline(iss, line)) {
+        // Trim leading whitespace
+        auto pos = line.find_first_not_of(" \t");
+        if (pos == std::string::npos) continue;
+        auto trimmed = line.substr(pos);
+
+        if (!inBlock) {
+            // Look for ["name"] = {
+            if (trimmed.starts_with("[\"")) {
+                auto endQuote = trimmed.find("\"]", 2);
+                if (endQuote != std::string::npos && trimmed.find("= {") != std::string::npos) {
+                    currentName = trimmed.substr(2, endQuote - 2);
+                    inBlock = true;
+                    globalUrl.clear();
+                    mirrorUrl.clear();
+                }
+            }
+        } else {
+            // Inside a block - look for closing } or ["KEY"] = "url"
+            if (trimmed.starts_with("}")) {
+                // End of block
+                // Mirror selection for sub-index repos happens here:
+                // prefer URL of current mirror key (e.g. CN), fallback to GLOBAL.
+                auto url = mirrorUrl.empty() ? globalUrl : mirrorUrl;
+                if (!url.empty()) {
+                    repos.push_back({currentName, url});
+                }
+                inBlock = false;
+            } else if (trimmed.starts_with("[\"")) {
+                auto endQuote = trimmed.find("\"]", 2);
+                if (endQuote != std::string::npos) {
+                    auto key = trimmed.substr(2, endQuote - 2);
+                    // Find the URL value: = "url"
+                    auto eqPos = trimmed.find("= \"", endQuote);
+                    if (eqPos != std::string::npos) {
+                        auto urlStart = eqPos + 3;
+                        auto urlEnd = trimmed.find('"', urlStart);
+                        if (urlEnd != std::string::npos) {
+                            auto val = trimmed.substr(urlStart, urlEnd - urlStart);
+                            if (key == "GLOBAL") globalUrl = val;
+                            if (key == mirror) mirrorUrl = val;
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    return repos;
+}
+
+std::string sync_repo_url_(const std::string& url, const std::string& mirror [[maybe_unused]]) {
+    // Repo URLs are already resolved by mirror in config/xim-indexrepos.lua.
+    return url;
+}
+
+}
+
+std::vector<IndexRepo> discover_sub_repos(const std::filesystem::path& repoDir,
+                                           const std::string& mirror) {
+    return detail_::discover_sub_repos_(repoDir, mirror);
+}
+
+std::string sync_repo_url(const std::string& url, const std::string& mirror) {
+    return detail_::sync_repo_url_(url, mirror);
+}
+
+std::vector<IndexRepo> merge_sub_repos(const std::vector<IndexRepo>& luaDefaults,
+                                       const std::vector<IndexRepo>& jsonRepos) {
+    std::unordered_map<std::string, IndexRepo> seen;
+    std::vector<IndexRepo> out;
+    out.reserve(luaDefaults.size() + jsonRepos.size());
+    for (auto& r : luaDefaults) {
+        if (seen.emplace(r.name, r).second) out.push_back(r);
+    }
+    for (auto& r : jsonRepos) {
+        if (seen.emplace(r.name, r).second) out.push_back(r);
+    }
+    return out;
+}
+
+bool main_should_attempt_artifact(bool isOfficialRemote,
+                                  const std::string& indexSource,
+                                  bool /*hasMarker*/, bool /*hasPkgs*/) {
+    if (indexSource == "artifact") return isOfficialRemote;
+    if (indexSource == "git")      return false;
+    return isOfficialRemote;
+}
+
+bool sub_should_attempt_artifact(bool isDefaultOfficial, const std::string& indexSource, bool subManaged, bool subHasPkgs, bool mainArtifactManaged, bool hasArtifactSource) {
+    if (indexSource == "artifact") return isDefaultOfficial || hasArtifactSource;
+    if (indexSource == "git")      return false;
+    return hasArtifactSource
+        || (isDefaultOfficial && (subManaged || !subHasPkgs || mainArtifactManaged));
+}
+
+bool is_local_repo_url(std::string_view u) {
+    return u.starts_with("file://")
+        || u.starts_with("/")
+        || u.starts_with("./")
+        || u.starts_with("../");
+}
+
+bool sync_repo(const std::filesystem::path& localDir, const std::string& url, bool force) {
+    namespace fs = std::filesystem;
+
+    if (!compact::git::ensure_available()) {
+        log::error("git is required to update package index: {}", url);
+        return false;
+    }
+
+    if (!fs::exists(localDir / ".git")) {
+        // ── Non-destructive guard (regression fix, see
+        // .agents/docs/2026-06-30-index-artifact-git-regression-analysis.md) ──
+        // A directory with pkgs/ but no .git is an artifact-managed index (or an
+        // extracted snapshot). The git-clone path below does fs::remove_all(localDir)
+        // before swapping the clone in — that wipes .xlings-index-version and strands
+        // the index on git PERMANENTLY. Never let a fallback clone destroy a usable
+        // artifact index: keep it (the caller's next artifact attempt migrates it
+        // atomically). An explicit XLINGS_INDEX_SOURCE=git opts out of this guard.
+        {
+            std::error_code gec;
+            bool indexSourceGit = false;
+            if (auto* e = std::getenv("XLINGS_INDEX_SOURCE"); e && *e)
+                indexSourceGit = std::string_view(e) == "git";
+            if (!indexSourceGit && fs::exists(localDir / "pkgs", gec)) {
+                log::warn("[index] keeping existing artifact-managed index at {} "
+                          "(refusing destructive git clone); will retry artifact next update",
+                          localDir.string());
+                return true;
+            }
+        }
+
+        // Build mirror fallback list for the index repo URL. Mirror::expand
+        // returns just [url] when mirror_fallback=off or url is non-github.
+        auto urls = mirror::expand(url, {.type = mirror::ResourceType::Git});
+        if (urls.empty()) urls.push_back(url);
+
+        std::string lastErr;
+        auto tmpDir = fs::path(localDir.string() + ".tmp." + std::to_string(platform::get_pid()));
+        std::error_code ec;
+        fs::remove_all(tmpDir, ec);
+        for (std::size_t i = 0; i < urls.size(); ++i) {
+            log::debug("cloning index repo attempt {}/{}: {}",
+                       i + 1, urls.size(), urls[i]);
+            // git has no connect timeout, so a firewalled host (e.g. github
+            // from a network that blocks it — common in CN / on Termux) stalls
+            // the clone on the OS TCP timeout (~127s) per URL. Probe reachability
+            // first with a short TCP connect; skip unreachable URLs so a
+            // github-only sub-index can't freeze `xlings update` for minutes.
+            constexpr int kReachMs = 3000;
+            if (!is_local_repo_url(urls[i])
+                && !std::isfinite(tinyhttps::probe_latency(urls[i], kReachMs))) {
+                log::debug("index repo host unreachable within {}ms, skipping: {}",
+                           kReachMs, urls[i]);
+                lastErr = "host unreachable: " + urls[i];
+                continue;
+            }
+            auto clone = compact::git::clone_shallow(urls[i], tmpDir, false);
+            if (clone.rc == 0) {
+                if (i > 0)
+                    log::info("[mirror] index repo fallback succeeded via {}", urls[i]);
+                fs::remove_all(localDir, ec);
+                if (ec) {
+                    log::error("failed to replace index repo {}: {}",
+                               localDir.string(), ec.message());
+                    fs::remove_all(tmpDir, ec);
+                    return false;
+                }
+                fs::rename(tmpDir, localDir, ec);
+                if (ec) {
+                    log::error("failed to move cloned index repo into place {}: {}",
+                               localDir.string(), ec.message());
+                    fs::remove_all(tmpDir, ec);
+                    return false;
+                }
+                return true;
+            }
+            lastErr = clone.output;
+            fs::remove_all(tmpDir, ec);
+        }
+        log::error("all index repo clone URLs failed: {}", lastErr);
+        return false;
+    }
+
+    // Check throttle: skip if pulled within 7 days (unless forced)
+    if (!force) {
+        auto stampFile = localDir / ".xlings-sync-stamp";
+        if (fs::exists(stampFile)) {
+            auto lastWrite = fs::last_write_time(stampFile);
+            auto now = fs::file_time_type::clock::now();
+            auto age = std::chrono::duration_cast<std::chrono::hours>(now - lastWrite);
+            if (age.count() < 7 * 24) {
+                log::debug("skipping sync for {} (last sync {}h ago)",
+                           localDir.string(), age.count());
+                return true;
+            }
+        }
+    }
+
+    log::debug("updating index repo: {}", localDir.filename().string());
+    // Same fast-fail as the clone path: skip the refresh if the origin is
+    // unreachable (firewalled github) rather than stalling git pull ~127s. The
+    // existing local copy stays valid, so this is non-fatal.
+    if (!is_local_repo_url(url)
+        && !std::isfinite(tinyhttps::probe_latency(url, 3000))) {
+        log::debug("index repo origin unreachable, keeping existing copy: {}", url);
+        return true;
+    }
+    auto setOrigin = compact::git::set_origin(localDir, url);
+    if (setOrigin.rc != 0) {
+        log::warn("failed to set index repo origin: {}", setOrigin.output);
+    }
+
+    auto pull = compact::git::pull_ff_only(localDir);
+    if (pull.rc != 0) {
+        log::warn("git pull failed, trying reset: {}", pull.output);
+        auto reset = compact::git::fetch_reset_origin_head(localDir);
+        if (reset.rc != 0) {
+            log::error("git reset failed: {}", reset.output);
+            return false;
+        }
+    }
+
+    // Update stamp file
+    auto stampFile = localDir / ".xlings-sync-stamp";
+    std::ofstream(stampFile).put('.');
+    return true;
+}
+
+bool sync_repo_with_artifact(const IndexRepo& repo,
+                             const std::filesystem::path& repoDir,
+                             const std::string& globalIndexSource,
+                             const std::function<bool()>& syncFallback) {
+    auto src = artifact_source_for(repo);
+    std::string mode = repo.source.empty() ? globalIndexSource : repo.source;
+    if (src && sub_should_attempt_artifact(false, mode, false, false, false, true)) {
+        std::string ferr;
+        if (fetch_index_artifact(repoDir, ferr, repo.name, &*src, repo.version)) return true;
+        if (mode == "artifact") {
+            log::error("[index] '{}' artifact fetch failed and git fallback disabled "
+                       "(source=artifact): {}", repo.name, ferr);
+            return false;
+        }
+        log::warn("[index] '{}' artifact fetch failed ({}); falling back to git",
+                  repo.name, ferr);
+    }
+    return syncFallback();
+}
+
+std::string url_to_dirname(const std::string& url) {
+    auto name = std::filesystem::path(url).stem().string();
+    if (name.empty()) {
+        // fallback: strip trailing .git and take last path component
+        auto tmp = url;
+        if (tmp.ends_with(".git")) tmp.resize(tmp.size() - 4);
+        auto pos = tmp.find_last_of('/');
+        name = pos != std::string::npos ? tmp.substr(pos + 1) : tmp;
+    }
+    return name;
+}
+
+std::vector<IndexRepo> load_sub_repos_json(const std::filesystem::path& jsonFile) {
+    namespace fs = std::filesystem;
+    if (!fs::exists(jsonFile)) return {};
+
+    try {
+        auto content = platform::read_file_to_string(jsonFile.string());
+        auto json = nlohmann::json::parse(content, nullptr, false);
+        if (json.is_discarded() || !json.is_object()) return {};
+
+        std::vector<IndexRepo> repos;
+        for (auto it = json.begin(); it != json.end(); ++it) {
+            IndexRepo repo;
+            repo.name = it.key();
+            if (it.value().is_string()) {
+                repo.url = it.value().get<std::string>();
+            } else if (it.value().is_object()) {
+                // #377: object form carries the artifact declaration.
+                auto& v = it.value();
+                if (v.contains("url") && v["url"].is_string())
+                    repo.url = v["url"].get<std::string>();
+                if (v.contains("artifact") && v["artifact"].is_string())
+                    repo.artifactBase = v["artifact"].get<std::string>();
+                if (v.contains("source") && v["source"].is_string())
+                    repo.source = v["source"].get<std::string>();
+            }
+            if (!repo.url.empty()) repos.push_back(std::move(repo));
+        }
+        return repos;
+    } catch (...) {
+        return {};
+    }
+}
+
+void save_sub_repos_json(const std::filesystem::path& jsonFile,
+                         const std::vector<IndexRepo>& repos) {
+    nlohmann::json json = nlohmann::json::object();
+    for (auto& repo : repos) {
+        if (repo.artifactBase.empty() && repo.source.empty()) {
+            json[repo.name] = repo.url;       // legacy string form
+        } else {
+            // #377: object form; old xlings skips non-string values gracefully.
+            nlohmann::json v;
+            v["url"] = repo.url;
+            if (!repo.artifactBase.empty()) v["artifact"] = repo.artifactBase;
+            if (!repo.source.empty())       v["source"]   = repo.source;
+            json[repo.name] = v;
+        }
+    }
+    try {
+        std::filesystem::create_directories(jsonFile.parent_path());
+        platform::write_string_to_file(jsonFile.string(), json.dump(2));
+    } catch (...) {
+        log::warn("failed to save sub-repos JSON: {}", jsonFile.string());
+    }
+}
+
+std::filesystem::path sub_repos_dir(bool projectScope) {
+    auto base = projectScope ? Config::project_data_dir() : Config::global_data_dir();
+    if (base.empty()) return {};
+    return base / "xim-index-repos";
+}
+
+std::filesystem::path sub_repos_json_path(bool projectScope) {
+    auto dir = sub_repos_dir(projectScope);
+    if (dir.empty()) return {};
+    return dir / "xim-indexrepos.json";
+}
+
+std::filesystem::path sub_repo_dir_for(const IndexRepo& repo, bool projectScope) {
+    return sub_repos_dir(projectScope) / url_to_dirname(repo.url);
+}
+
+std::vector<IndexRepo> discovered_global_sub_repos() {
+    return load_sub_repos_json(sub_repos_json_path(false));
+}
+
+std::vector<IndexRepo> discovered_project_sub_repos() {
+    auto path = sub_repos_json_path(true);
+    if (path.empty()) return {};
+    return load_sub_repos_json(path);
+}
+
+bool sub_indexes_initialized() {
+    auto p = sub_repos_json_path(false);
+    return !p.empty() && std::filesystem::exists(p);
+}
+
+std::filesystem::path main_repo_dir() {
+    auto& repos = Config::global_index_repos();
+    if (!repos.empty()) {
+        return Config::repo_dir_for(repos[0], false);
+    }
+    return Config::global_data_dir() / "xim-pkgindex";
+}
+
+bool sync_all_repos(bool force) {
+    namespace fs = std::filesystem;
+    auto mirror = Config::mirror();
+
+    auto mainDir = main_repo_dir();
+
+    // Heal leftovers from any crashed/killed run BEFORE deciding git-vs-artifact:
+    // restores an index dir orphaned by an interrupted swap and reclaims leaked
+    // staging dirs, so the gating below never sees a spurious "no index" gap.
+    if (auto dataDir = Config::global_data_dir(); !dataDir.empty()) {
+        reconcile_index_temps(dataDir);
+        reconcile_index_temps(sub_repos_dir());
+    }
+
+    // ── Index-as-Resource (Y-asset) ─────────────────────────────────
+    // Fetch the main index as a versioned artifact over the resource-server
+    // HTTP path (gains adaptive mirror reorder + stall watchdog; closes G2).
+    // git clone is the fallback. XLINGS_INDEX_SOURCE=git|artifact|auto (auto).
+    // An artifact-managed index has no .git, so once installed via artifact we
+    // must NOT let the git path try to clone it again — the .xlings-index-version
+    // marker records that state.
+    std::string indexSource = "auto";
+    if (auto* e = std::getenv("XLINGS_INDEX_SOURCE"); e && *e) indexSource = e;
+
+    bool mainArtifactManaged = fs::exists(mainDir / ".xlings-index-version");
+    bool mainHasIndex = fs::exists(mainDir / "pkgs");
+
+    // The artifact is the OFFICIAL xim index. In auto mode it applies ONLY when
+    // the configured main index is the official index from a *remote* source —
+    // never when the user points index_repos at a local path (file://, abs
+    // path: test fixtures, project-local indexes) or a custom fork URL, which
+    // must be managed by their own source (git/local).
+    auto globalRepos = Config::global_index_repos();
+    bool mainIsOfficialRemote =
+        !globalRepos.empty()
+        && !Config::is_local_repo_source(globalRepos.front(), false)
+        && (globalRepos.front().url.find("openxlings/xim-pkgindex") != std::string::npos
+            || globalRepos.front().url.find("sunrisepeak/xim-pkgindex") != std::string::npos);
+
+    // auto: the official remote main index always converges to artifact (a
+    // stranded git main self-heals; see main_should_attempt_artifact). git stays
+    // the fallback. XLINGS_INDEX_SOURCE=artifact forces it (power user / tests);
+    // =git disables. Non-official/local/fork mains are excluded upstream.
+    bool attemptArtifact = main_should_attempt_artifact(
+        mainIsOfficialRemote, indexSource, mainArtifactManaged, mainHasIndex);
+
+    if (attemptArtifact) {
+        std::string ferr;
+        // #476: the main index honours a pin the same way sub-indexes do. It is
+        // the first entry of index_repos (the primary), which is also the repo
+        // whose name namespaces bare package targets.
+        const std::string mainPin =
+            globalRepos.empty() ? std::string{} : globalRepos.front().version;
+        if (fetch_index_artifact(mainDir, ferr, {}, nullptr, mainPin)) {
+            mainArtifactManaged = true;
+        } else if (indexSource == "artifact") {
+            log::error("[index] artifact fetch failed and git fallback disabled "
+                       "(XLINGS_INDEX_SOURCE=artifact): {}", ferr);
+            return false;
+        } else {
+            log::warn("[index] artifact fetch failed ({}); falling back to git", ferr);
+        }
+    }
+
+    // #374: best-effort. A single degenerate/unreachable index repo (no
+    // pkgs/, empty default-namespace redirect target, dead URL) must NOT
+    // abort the whole sync and collapse the catalog — that is the exact
+    // ">=2 index_repos -> silent exit 1" trigger. Skip the bad repo with a
+    // warning and keep syncing the rest, mirroring the best-effort handling
+    // the sub-index loop below already has. Returns false only when NOTHING
+    // in a non-empty list could be synced; the catalog rebuild's load-gate
+    // is the real "nothing usable" safety net.
+    auto syncRepos = [&](const std::vector<IndexRepo>& repos, bool projectScope) {
+        auto rootDir = projectScope ? Config::project_data_dir() : Config::global_data_dir();
+        if (rootDir.empty()) return true;
+        fs::create_directories(rootDir);
+        int total = 0, ok = 0;
+        for (auto& repo : repos) {
+            ++total;
+            auto repoDir = Config::repo_dir_for(repo, projectScope);
+            // The main index is artifact-managed (no .git); never git-sync it.
+            if (!projectScope && mainArtifactManaged && repoDir == mainDir) { ++ok; continue; }
+
+            auto fallbackSync = [&]() -> bool {
+                if (Config::is_local_repo_source(repo, projectScope)) {
+                    auto sourceDir = Config::resolve_repo_source(repo, projectScope);
+                    if (!detail_::ensure_local_repo_link_(repoDir, sourceDir)) {
+                        log::warn("index repo '{}' skipped: local source has no pkgs/ ({})",
+                                  repo.name, sourceDir.string());
+                        return false;
+                    }
+                    return true;
+                }
+                auto url = detail_::sync_repo_url_(repo.url, mirror);
+                if (!sync_repo(repoDir, url, force)) {
+                    log::warn("index repo '{}' skipped: sync failed ({})", repo.name, url);
+                    return false;
+                }
+                return true;
+            };
+
+            // #377: a repo-declared artifact source is tried first; git/local
+            // remains the fallback (source:"artifact" disables it in the helper).
+            bool okOne = repo.artifactBase.empty()
+                ? fallbackSync()
+                : sync_repo_with_artifact(repo, repoDir, indexSource, fallbackSync);
+            if (okOne) ++ok;
+        }
+        return total == 0 || ok > 0;
+    };
+
+    if (!syncRepos(Config::global_index_repos(), false)) return false;
+
+    // Discover and sync sub-index repos from the main repo's xim-indexrepos.lua
+    auto luaSubRepos = detail_::discover_sub_repos_(mainDir, mirror.empty() ? "GLOBAL" : mirror);
+    auto jsonSubRepos = load_sub_repos_json(sub_repos_json_path());
+
+    // Merge: lua defaults are authoritative for their own names; json adds only
+    // user-added sub-indexes (names absent from the lua defaults). See
+    // merge_sub_repos for why json must NOT override lua defaults (an
+    // org-drifted default would otherwise stay pinned to a stale json URL and
+    // never migrate to the artifact path).
+    auto allSubRepos = merge_sub_repos(luaSubRepos, jsonSubRepos);
+    std::vector<IndexRepo> syncedSubRepos;
+
+    // Default sub-indexes — those provided by the main index's
+    // xim-indexrepos.lua at their declared (now-authoritative) URL and from a
+    // remote source — are fetched as artifacts, same model as the main index.
+    // User-added sub-indexes (in xim-indexrepos.json but NOT a lua default),
+    // URL-overridden ones, and local (file://) sources keep git.
+    //
+    // The signal is "name is a lua default AND its URL matches the lua default".
+    // Because merge_sub_repos makes lua authoritative, repo.url == luaUrl for
+    // every lua default, so this also recognises a default whose official org
+    // moved (the stale json copy no longer overrides it).
+    std::unordered_map<std::string, std::string> luaUrl;
+    for (auto& r : luaSubRepos) luaUrl[r.name] = r.url;
+
+    auto subReposRoot = sub_repos_dir();
+    fs::create_directories(subReposRoot);
+
+    for (auto& repo : allSubRepos) {
+        auto repoDir = sub_repo_dir_for(repo);
+        auto luaIt = luaUrl.find(repo.name);
+        bool subDefaultOfficial =
+            luaIt != luaUrl.end() && luaIt->second == repo.url
+            && !Config::is_local_repo_source(repo, false);
+        bool subManaged = fs::exists(repoDir / ".xlings-index-version");
+        // #377: user-added sub-indexes may declare their own artifact source.
+        std::optional<ArtifactSource> customSrc;
+        if (!subDefaultOfficial) customSrc = artifact_source_for(repo);
+        std::string subMode = repo.source.empty() ? indexSource : repo.source;
+        bool subAttemptArtifact = sub_should_attempt_artifact(
+            subDefaultOfficial, subMode, subManaged,
+            fs::exists(repoDir / "pkgs"), mainArtifactManaged, customSrc.has_value());
+
+        bool ok = false;
+        if (subAttemptArtifact) {
+            std::string ferr;
+            ok = fetch_index_artifact(repoDir, ferr, repo.name,
+                                      customSrc ? &*customSrc : nullptr,
+                                      repo.version);
+            if (!ok)
+                log::warn("[index] sub-index '{}' artifact fetch failed: {}", repo.name, ferr);
+        }
+        // git fallback (and the path for user-added / local sub-indexes), unless
+        // the sub was explicitly pinned to the artifact source.
+        if (!ok && !(subMode == "artifact" && (subDefaultOfficial || customSrc.has_value()))) {
+            ok = sync_repo(repoDir, repo.url, force);
+        }
+        if (ok) syncedSubRepos.push_back(repo);
+        else log::warn("failed to sync sub-index repo: {} ({})", repo.name, repo.url);
+    }
+
+    save_sub_repos_json(sub_repos_json_path(), syncedSubRepos);
+
+    if (Config::has_project_config() && !Config::project_index_repos().empty()) {
+        if (!syncRepos(Config::project_index_repos(), true)) return false;
+
+        // Discover and sync sub-index repos from project index repos
+        auto mirrorKey = mirror.empty() ? "GLOBAL" : mirror;
+        auto& projRepos = Config::project_index_repos();
+        std::unordered_map<std::string, IndexRepo> projMerged;
+        for (auto& repo : projRepos) {
+            auto repoDir = Config::repo_dir_for(repo, true);
+            for (auto& sub : detail_::discover_sub_repos_(repoDir, mirrorKey)) {
+                projMerged[sub.name] = sub;
+            }
+        }
+        auto projJsonSubs = load_sub_repos_json(sub_repos_json_path(true));
+        for (auto& repo : projJsonSubs) projMerged[repo.name] = repo;
+
+        std::vector<IndexRepo> projSyncedSubs;
+        auto projSubRoot = sub_repos_dir(true);
+        fs::create_directories(projSubRoot);
+        for (auto& [name, repo] : projMerged) {
+            auto repoDir = sub_repo_dir_for(repo, true);
+            // #377: project sub-indexes may declare artifact sources too.
+            auto fallbackSync = [&]{ return sync_repo(repoDir, repo.url, force); };
+            bool okOne = repo.artifactBase.empty()
+                ? fallbackSync()
+                : sync_repo_with_artifact(repo, repoDir, indexSource, fallbackSync);
+            if (okOne) {
+                projSyncedSubs.push_back(repo);
+            } else {
+                log::warn("failed to sync project sub-index repo: {} ({})", repo.name, repo.url);
+            }
+        }
+        save_sub_repos_json(sub_repos_json_path(true), projSyncedSubs);
+    }
+    return true;
+}
+
+std::string get_repo_head_hash(const std::filesystem::path& repoDir) {
+    namespace fs = std::filesystem;
+    auto headFile = repoDir / ".git" / "HEAD";
+    if (!fs::exists(headFile)) {
+        // Artifact-managed index (no .git): key the parsed-index cache
+        // (.xlings-index-cache.json) on the .xlings-index-version marker.
+        // Artifacts are version-unique, so the marker is a stable cache key
+        // that changes only on re-install. Without this the hash is empty and
+        // load_or_rebuild disables caching -> a full index rebuild (the noisy
+        // "[1/7] awesome::..." scan) on EVERY xlings install/search.
+        auto verFile = repoDir / ".xlings-index-version";
+        if (fs::exists(verFile)) {
+            try {
+                auto v = platform::read_file_to_string(verFile.string());
+                while (!v.empty() && (v.back() == '\n' || v.back() == '\r' || v.back() == ' '))
+                    v.pop_back();
+                if (!v.empty()) return "artifact:" + v;
+            } catch (...) {}
+        }
+        return {};
+    }
+
+    try {
+        auto content = platform::read_file_to_string(headFile.string());
+        // Trim trailing whitespace/newlines
+        while (!content.empty() && (content.back() == '\n' || content.back() == '\r' || content.back() == ' '))
+            content.pop_back();
+
+        // Direct hash (detached HEAD)
+        if (!content.starts_with("ref: ")) return content;
+
+        // Symbolic ref: read the referenced file
+        auto ref = content.substr(5);
+        auto refFile = repoDir / ".git" / ref;
+        if (!fs::exists(refFile)) return {};
+
+        auto hash = platform::read_file_to_string(refFile.string());
+        while (!hash.empty() && (hash.back() == '\n' || hash.back() == '\r' || hash.back() == ' '))
+            hash.pop_back();
+        return hash;
+    } catch (...) {
+        return {};
+    }
+}
+
+}
diff --git a/src/core/xim/repo.cppm b/src/core/xim/repo.cppm
index 9e3e6f1c..9e2104c6 100644
--- a/src/core/xim/repo.cppm
+++ b/src/core/xim/repo.cppm
@@ -4,10 +4,6 @@ module;
 export module xlings.core.xim.repo;
 
 import std;
-import xlings.libs.json;
-import xlings.core.log;
-import xlings.core.compact;
-import xlings.platform;
 import xlings.core.config;
 import xlings.core.mirror;
 import xlings.core.xim.indexfetch;
@@ -18,151 +14,22 @@ export namespace xlings::xim {
 namespace detail_ {
 
 bool ensure_local_repo_link_(const std::filesystem::path& localDir,
-                             const std::filesystem::path& sourceDir) {
-    namespace fs = std::filesystem;
-
-    std::error_code ec;
-    if (!fs::exists(sourceDir, ec) || !fs::exists(sourceDir / "pkgs", ec)) {
-        // #374: caller (syncRepos) now treats this as a best-effort skip and
-        // emits the user-facing warning naming the repo; keep this at debug
-        // so a tolerated missing-pkgs source is not reported as a hard error.
-        log::debug("local index repo missing pkgs/: {}", sourceDir.string());
-        return false;
-    }
-
-    if (fs::exists(localDir, ec) || fs::is_symlink(localDir, ec)) {
-        auto canonicalLocal = fs::weakly_canonical(localDir, ec);
-        ec.clear();
-        auto canonicalSource = fs::weakly_canonical(sourceDir, ec);
-        if (!ec && canonicalLocal == canonicalSource) {
-            return true;
-        }
-        ec.clear();
-        fs::remove_all(localDir, ec);
-        if (ec) {
-            log::error("failed to replace local index repo mapping {}: {}",
-                       localDir.string(), ec.message());
-            return false;
-        }
-    }
-
-    fs::create_directories(localDir.parent_path(), ec);
-    if (ec) {
-        log::error("failed to create repo parent directory {}: {}",
-                   localDir.parent_path().string(), ec.message());
-        return false;
-    }
-
-#if defined(_WIN32)
-    if (!platform::create_directory_link(localDir, sourceDir)) {
-        log::error("failed to create directory link: {} -> {}",
-                   localDir.string(), sourceDir.string());
-        return false;
-    }
-#else
-    fs::create_directory_symlink(sourceDir, localDir, ec);
-    if (ec) {
-        log::error("failed to create symlink: {} -> {} ({})",
-                   localDir.string(), sourceDir.string(), ec.message());
-        return false;
-    }
-#endif
-
-    log::debug("linked local index repo: {} -> {}", localDir.string(), sourceDir.string());
-    return true;
-}
+                             const std::filesystem::path& sourceDir);
 
 // Parse xim-indexrepos.lua to discover sub-index repositories.
 // Format: xim_indexrepos["name"] = { ["GLOBAL"] = "url", ["CN"] = "url" }
 std::vector<IndexRepo> discover_sub_repos_(const std::filesystem::path& repoDir,
-                                            const std::string& mirror) {
-    namespace fs = std::filesystem;
-    auto luaFile = repoDir / "xim-indexrepos.lua";
-    if (!fs::exists(luaFile)) return {};
-
-    std::string content;
-    try {
-        content = platform::read_file_to_string(luaFile.string());
-    } catch (...) {
-        return {};
-    }
+                                            const std::string& mirror);
 
-    std::vector<IndexRepo> repos;
-    // Simple line-based parser to avoid std::regex in modules
-    // State machine: look for ["name"] = { blocks, then ["KEY"] = "url" inside
-    std::istringstream iss(content);
-    std::string line;
-    std::string currentName;
-    std::string globalUrl, mirrorUrl;
-    bool inBlock = false;
-
-    while (std::getline(iss, line)) {
-        // Trim leading whitespace
-        auto pos = line.find_first_not_of(" \t");
-        if (pos == std::string::npos) continue;
-        auto trimmed = line.substr(pos);
-
-        if (!inBlock) {
-            // Look for ["name"] = {
-            if (trimmed.starts_with("[\"")) {
-                auto endQuote = trimmed.find("\"]", 2);
-                if (endQuote != std::string::npos && trimmed.find("= {") != std::string::npos) {
-                    currentName = trimmed.substr(2, endQuote - 2);
-                    inBlock = true;
-                    globalUrl.clear();
-                    mirrorUrl.clear();
-                }
-            }
-        } else {
-            // Inside a block - look for closing } or ["KEY"] = "url"
-            if (trimmed.starts_with("}")) {
-                // End of block
-                // Mirror selection for sub-index repos happens here:
-                // prefer URL of current mirror key (e.g. CN), fallback to GLOBAL.
-                auto url = mirrorUrl.empty() ? globalUrl : mirrorUrl;
-                if (!url.empty()) {
-                    repos.push_back({currentName, url});
-                }
-                inBlock = false;
-            } else if (trimmed.starts_with("[\"")) {
-                auto endQuote = trimmed.find("\"]", 2);
-                if (endQuote != std::string::npos) {
-                    auto key = trimmed.substr(2, endQuote - 2);
-                    // Find the URL value: = "url"
-                    auto eqPos = trimmed.find("= \"", endQuote);
-                    if (eqPos != std::string::npos) {
-                        auto urlStart = eqPos + 3;
-                        auto urlEnd = trimmed.find('"', urlStart);
-                        if (urlEnd != std::string::npos) {
-                            auto val = trimmed.substr(urlStart, urlEnd - urlStart);
-                            if (key == "GLOBAL") globalUrl = val;
-                            if (key == mirror) mirrorUrl = val;
-                        }
-                    }
-                }
-            }
-        }
-    }
-
-    return repos;
-}
-
-std::string sync_repo_url_(const std::string& url, const std::string& mirror [[maybe_unused]]) {
-    // Repo URLs are already resolved by mirror in config/xim-indexrepos.lua.
-    return url;
-}
+std::string sync_repo_url_(const std::string& url, const std::string& mirror [[maybe_unused]]);
 
 }  // namespace detail_
 
 // Exported wrapper for discover_sub_repos (used by catalog)
 std::vector<IndexRepo> discover_sub_repos(const std::filesystem::path& repoDir,
-                                           const std::string& mirror) {
-    return detail_::discover_sub_repos_(repoDir, mirror);
-}
+                                           const std::string& mirror);
 
-std::string sync_repo_url(const std::string& url, const std::string& mirror) {
-    return detail_::sync_repo_url_(url, mirror);
-}
+std::string sync_repo_url(const std::string& url, const std::string& mirror);
 
 // Merge the main index's lua-declared default sub-indexes with the
 // persisted / locally-added json list.
@@ -178,18 +45,7 @@ std::string sync_repo_url(const std::string& url, const std::string& mirror) {
 // classifying as default-official so it can migrate to the artifact path; a
 // json-overrides-lua merge would leave it stuck on git forever.
 std::vector<IndexRepo> merge_sub_repos(const std::vector<IndexRepo>& luaDefaults,
-                                       const std::vector<IndexRepo>& jsonRepos) {
-    std::unordered_map<std::string, IndexRepo> seen;
-    std::vector<IndexRepo> out;
-    out.reserve(luaDefaults.size() + jsonRepos.size());
-    for (auto& r : luaDefaults) {
-        if (seen.emplace(r.name, r).second) out.push_back(r);
-    }
-    for (auto& r : jsonRepos) {
-        if (seen.emplace(r.name, r).second) out.push_back(r);
-    }
-    return out;
-}
+                                       const std::vector<IndexRepo>& jsonRepos);
 
 // Decide whether the MAIN index should be fetched as a versioned artifact (vs
 // git clone/pull). The OFFICIAL remote index always converges to artifact in
@@ -209,11 +65,7 @@ std::vector<IndexRepo> merge_sub_repos(const std::vector<IndexRepo>& luaDefaults
 // cheap pointer fetch + sha match).
 bool main_should_attempt_artifact(bool isOfficialRemote,
                                   const std::string& indexSource,
-                                  bool /*hasMarker*/, bool /*hasPkgs*/) {
-    if (indexSource == "artifact") return isOfficialRemote;
-    if (indexSource == "git")      return false;
-    return isOfficialRemote;
-}
+                                  bool /*hasMarker*/, bool /*hasPkgs*/);
 
 // Decide whether a sub-index should be fetched as a versioned artifact (vs git
 // clone/pull). Mirrors the main index's gating:
@@ -233,155 +85,20 @@ bool sub_should_attempt_artifact(bool isDefaultOfficial,
                                  const std::string& indexSource,
                                  bool subManaged, bool subHasPkgs,
                                  bool mainArtifactManaged,
-                                 bool hasArtifactSource = false) {
-    if (indexSource == "artifact") return isDefaultOfficial || hasArtifactSource;
-    if (indexSource == "git")      return false;
-    return hasArtifactSource
-        || (isDefaultOfficial && (subManaged || !subHasPkgs || mainArtifactManaged));
-}
+                                 bool hasArtifactSource = false);
 
 // A local repo source (file:// URL or a filesystem path) has no network host,
 // so the TCP reachability probe below always reports it "unreachable" and would
 // wrongly skip it. Local sources are always reachable — let git clone/pull
 // validate the path instead. (Fixes e2e sub-index file:// fixtures being
 // "host unreachable within 3000ms" and never synced.)
-bool is_local_repo_url(std::string_view u) {
-    return u.starts_with("file://")
-        || u.starts_with("/")
-        || u.starts_with("./")
-        || u.starts_with("../");
-}
+bool is_local_repo_url(std::string_view u);
 
 // Sync a single git repository (clone or pull)
 // Returns true on success
 bool sync_repo(const std::filesystem::path& localDir,
                const std::string& url,
-               bool force = false) {
-    namespace fs = std::filesystem;
-
-    if (!compact::git::ensure_available()) {
-        log::error("git is required to update package index: {}", url);
-        return false;
-    }
-
-    if (!fs::exists(localDir / ".git")) {
-        // ── Non-destructive guard (regression fix, see
-        // .agents/docs/2026-06-30-index-artifact-git-regression-analysis.md) ──
-        // A directory with pkgs/ but no .git is an artifact-managed index (or an
-        // extracted snapshot). The git-clone path below does fs::remove_all(localDir)
-        // before swapping the clone in — that wipes .xlings-index-version and strands
-        // the index on git PERMANENTLY. Never let a fallback clone destroy a usable
-        // artifact index: keep it (the caller's next artifact attempt migrates it
-        // atomically). An explicit XLINGS_INDEX_SOURCE=git opts out of this guard.
-        {
-            std::error_code gec;
-            bool indexSourceGit = false;
-            if (auto* e = std::getenv("XLINGS_INDEX_SOURCE"); e && *e)
-                indexSourceGit = std::string_view(e) == "git";
-            if (!indexSourceGit && fs::exists(localDir / "pkgs", gec)) {
-                log::warn("[index] keeping existing artifact-managed index at {} "
-                          "(refusing destructive git clone); will retry artifact next update",
-                          localDir.string());
-                return true;
-            }
-        }
-
-        // Build mirror fallback list for the index repo URL. Mirror::expand
-        // returns just [url] when mirror_fallback=off or url is non-github.
-        auto urls = mirror::expand(url, {.type = mirror::ResourceType::Git});
-        if (urls.empty()) urls.push_back(url);
-
-        std::string lastErr;
-        auto tmpDir = fs::path(localDir.string() + ".tmp." + std::to_string(platform::get_pid()));
-        std::error_code ec;
-        fs::remove_all(tmpDir, ec);
-        for (std::size_t i = 0; i < urls.size(); ++i) {
-            log::debug("cloning index repo attempt {}/{}: {}",
-                       i + 1, urls.size(), urls[i]);
-            // git has no connect timeout, so a firewalled host (e.g. github
-            // from a network that blocks it — common in CN / on Termux) stalls
-            // the clone on the OS TCP timeout (~127s) per URL. Probe reachability
-            // first with a short TCP connect; skip unreachable URLs so a
-            // github-only sub-index can't freeze `xlings update` for minutes.
-            constexpr int kReachMs = 3000;
-            if (!is_local_repo_url(urls[i])
-                && !std::isfinite(tinyhttps::probe_latency(urls[i], kReachMs))) {
-                log::debug("index repo host unreachable within {}ms, skipping: {}",
-                           kReachMs, urls[i]);
-                lastErr = "host unreachable: " + urls[i];
-                continue;
-            }
-            auto clone = compact::git::clone_shallow(urls[i], tmpDir, false);
-            if (clone.rc == 0) {
-                if (i > 0)
-                    log::info("[mirror] index repo fallback succeeded via {}", urls[i]);
-                fs::remove_all(localDir, ec);
-                if (ec) {
-                    log::error("failed to replace index repo {}: {}",
-                               localDir.string(), ec.message());
-                    fs::remove_all(tmpDir, ec);
-                    return false;
-                }
-                fs::rename(tmpDir, localDir, ec);
-                if (ec) {
-                    log::error("failed to move cloned index repo into place {}: {}",
-                               localDir.string(), ec.message());
-                    fs::remove_all(tmpDir, ec);
-                    return false;
-                }
-                return true;
-            }
-            lastErr = clone.output;
-            fs::remove_all(tmpDir, ec);
-        }
-        log::error("all index repo clone URLs failed: {}", lastErr);
-        return false;
-    }
-
-    // Check throttle: skip if pulled within 7 days (unless forced)
-    if (!force) {
-        auto stampFile = localDir / ".xlings-sync-stamp";
-        if (fs::exists(stampFile)) {
-            auto lastWrite = fs::last_write_time(stampFile);
-            auto now = fs::file_time_type::clock::now();
-            auto age = std::chrono::duration_cast<std::chrono::hours>(now - lastWrite);
-            if (age.count() < 7 * 24) {
-                log::debug("skipping sync for {} (last sync {}h ago)",
-                           localDir.string(), age.count());
-                return true;
-            }
-        }
-    }
-
-    log::debug("updating index repo: {}", localDir.filename().string());
-    // Same fast-fail as the clone path: skip the refresh if the origin is
-    // unreachable (firewalled github) rather than stalling git pull ~127s. The
-    // existing local copy stays valid, so this is non-fatal.
-    if (!is_local_repo_url(url)
-        && !std::isfinite(tinyhttps::probe_latency(url, 3000))) {
-        log::debug("index repo origin unreachable, keeping existing copy: {}", url);
-        return true;
-    }
-    auto setOrigin = compact::git::set_origin(localDir, url);
-    if (setOrigin.rc != 0) {
-        log::warn("failed to set index repo origin: {}", setOrigin.output);
-    }
-
-    auto pull = compact::git::pull_ff_only(localDir);
-    if (pull.rc != 0) {
-        log::warn("git pull failed, trying reset: {}", pull.output);
-        auto reset = compact::git::fetch_reset_origin_head(localDir);
-        if (reset.rc != 0) {
-            log::error("git reset failed: {}", reset.output);
-            return false;
-        }
-    }
-
-    // Update stamp file
-    auto stampFile = localDir / ".xlings-sync-stamp";
-    std::ofstream(stampFile).put('.');
-    return true;
-}
+               bool force = false);
 
 // #377: sync one CUSTOM repo that declares its own artifact source: artifact
 // first (per the repo's effective source mode), then the repo's pre-existing
@@ -390,405 +107,50 @@ bool sync_repo(const std::filesystem::path& localDir,
 bool sync_repo_with_artifact(const IndexRepo& repo,
                              const std::filesystem::path& repoDir,
                              const std::string& globalIndexSource,
-                             const std::function<bool()>& syncFallback) {
-    auto src = artifact_source_for(repo);
-    std::string mode = repo.source.empty() ? globalIndexSource : repo.source;
-    if (src && sub_should_attempt_artifact(false, mode, false, false, false, true)) {
-        std::string ferr;
-        if (fetch_index_artifact(repoDir, ferr, repo.name, &*src, repo.version)) return true;
-        if (mode == "artifact") {
-            log::error("[index] '{}' artifact fetch failed and git fallback disabled "
-                       "(source=artifact): {}", repo.name, ferr);
-            return false;
-        }
-        log::warn("[index] '{}' artifact fetch failed ({}); falling back to git",
-                  repo.name, ferr);
-    }
-    return syncFallback();
-}
+                             const std::function<bool()>& syncFallback);
 
 // Extract repo directory name from URL (matches Lua _to_repodir behavior)
 // e.g. "https://github.com/d2learn/xim-pkgindex-d2x.git" -> "xim-pkgindex-d2x"
-std::string url_to_dirname(const std::string& url) {
-    auto name = std::filesystem::path(url).stem().string();
-    if (name.empty()) {
-        // fallback: strip trailing .git and take last path component
-        auto tmp = url;
-        if (tmp.ends_with(".git")) tmp.resize(tmp.size() - 4);
-        auto pos = tmp.find_last_of('/');
-        name = pos != std::string::npos ? tmp.substr(pos + 1) : tmp;
-    }
-    return name;
-}
+std::string url_to_dirname(const std::string& url);
 
 // Load sub-repos from the JSON file (written by sync or Lua RepoManager)
-std::vector<IndexRepo> load_sub_repos_json(const std::filesystem::path& jsonFile) {
-    namespace fs = std::filesystem;
-    if (!fs::exists(jsonFile)) return {};
-
-    try {
-        auto content = platform::read_file_to_string(jsonFile.string());
-        auto json = nlohmann::json::parse(content, nullptr, false);
-        if (json.is_discarded() || !json.is_object()) return {};
-
-        std::vector<IndexRepo> repos;
-        for (auto it = json.begin(); it != json.end(); ++it) {
-            IndexRepo repo;
-            repo.name = it.key();
-            if (it.value().is_string()) {
-                repo.url = it.value().get<std::string>();
-            } else if (it.value().is_object()) {
-                // #377: object form carries the artifact declaration.
-                auto& v = it.value();
-                if (v.contains("url") && v["url"].is_string())
-                    repo.url = v["url"].get<std::string>();
-                if (v.contains("artifact") && v["artifact"].is_string())
-                    repo.artifactBase = v["artifact"].get<std::string>();
-                if (v.contains("source") && v["source"].is_string())
-                    repo.source = v["source"].get<std::string>();
-            }
-            if (!repo.url.empty()) repos.push_back(std::move(repo));
-        }
-        return repos;
-    } catch (...) {
-        return {};
-    }
-}
+std::vector<IndexRepo> load_sub_repos_json(const std::filesystem::path& jsonFile);
 
 // Save sub-repos to JSON file
 void save_sub_repos_json(const std::filesystem::path& jsonFile,
-                         const std::vector<IndexRepo>& repos) {
-    nlohmann::json json = nlohmann::json::object();
-    for (auto& repo : repos) {
-        if (repo.artifactBase.empty() && repo.source.empty()) {
-            json[repo.name] = repo.url;       // legacy string form
-        } else {
-            // #377: object form; old xlings skips non-string values gracefully.
-            nlohmann::json v;
-            v["url"] = repo.url;
-            if (!repo.artifactBase.empty()) v["artifact"] = repo.artifactBase;
-            if (!repo.source.empty())       v["source"]   = repo.source;
-            json[repo.name] = v;
-        }
-    }
-    try {
-        std::filesystem::create_directories(jsonFile.parent_path());
-        platform::write_string_to_file(jsonFile.string(), json.dump(2));
-    } catch (...) {
-        log::warn("failed to save sub-repos JSON: {}", jsonFile.string());
-    }
-}
+                         const std::vector<IndexRepo>& repos);
 
 // Get the sub-repos index directory (global or project-local)
-std::filesystem::path sub_repos_dir(bool projectScope = false) {
-    auto base = projectScope ? Config::project_data_dir() : Config::global_data_dir();
-    if (base.empty()) return {};
-    return base / "xim-index-repos";
-}
+std::filesystem::path sub_repos_dir(bool projectScope = false);
 
 // Get the sub-repos JSON file path
-std::filesystem::path sub_repos_json_path(bool projectScope = false) {
-    auto dir = sub_repos_dir(projectScope);
-    if (dir.empty()) return {};
-    return dir / "xim-indexrepos.json";
-}
+std::filesystem::path sub_repos_json_path(bool projectScope = false);
 
 // Get directory for a sub-repo
-std::filesystem::path sub_repo_dir_for(const IndexRepo& repo, bool projectScope = false) {
-    return sub_repos_dir(projectScope) / url_to_dirname(repo.url);
-}
+std::filesystem::path sub_repo_dir_for(const IndexRepo& repo, bool projectScope = false);
 
 // Return all discovered global sub-repos (for use by PackageCatalog)
-std::vector<IndexRepo> discovered_global_sub_repos() {
-    return load_sub_repos_json(sub_repos_json_path(false));
-}
+std::vector<IndexRepo> discovered_global_sub_repos();
 
 // Return all discovered project-local sub-repos
-std::vector<IndexRepo> discovered_project_sub_repos() {
-    auto path = sub_repos_json_path(true);
-    if (path.empty()) return {};
-    return load_sub_repos_json(path);
-}
+std::vector<IndexRepo> discovered_project_sub_repos();
 
 // #366: true once the default/global sub-indexes have been synced at least
 // once (the persisted xim-indexrepos.json marker exists). On a fresh machine
 // this is false even though the main index rebuilds fine, which is exactly why
 // get_catalog() must force a first-run sync — otherwise sub-index packages
 // (scode/awesome/d2x) never resolve until the user runs `xlings update`.
-bool sub_indexes_initialized() {
-    auto p = sub_repos_json_path(false);
-    return !p.empty() && std::filesystem::exists(p);
-}
+bool sub_indexes_initialized();
 
 // Get the main index repo directory path (always global)
-std::filesystem::path main_repo_dir() {
-    auto& repos = Config::global_index_repos();
-    if (!repos.empty()) {
-        return Config::repo_dir_for(repos[0], false);
-    }
-    return Config::global_data_dir() / "xim-pkgindex";
-}
+std::filesystem::path main_repo_dir();
 
 // Sync all configured repos.
 // Global repos live under XLINGS_HOME/data, project repos under project .xlings/data.
-bool sync_all_repos(bool force = false) {
-    namespace fs = std::filesystem;
-    auto mirror = Config::mirror();
-
-    auto mainDir = main_repo_dir();
-
-    // Heal leftovers from any crashed/killed run BEFORE deciding git-vs-artifact:
-    // restores an index dir orphaned by an interrupted swap and reclaims leaked
-    // staging dirs, so the gating below never sees a spurious "no index" gap.
-    if (auto dataDir = Config::global_data_dir(); !dataDir.empty()) {
-        reconcile_index_temps(dataDir);
-        reconcile_index_temps(sub_repos_dir());
-    }
-
-    // ── Index-as-Resource (Y-asset) ─────────────────────────────────
-    // Fetch the main index as a versioned artifact over the resource-server
-    // HTTP path (gains adaptive mirror reorder + stall watchdog; closes G2).
-    // git clone is the fallback. XLINGS_INDEX_SOURCE=git|artifact|auto (auto).
-    // An artifact-managed index has no .git, so once installed via artifact we
-    // must NOT let the git path try to clone it again — the .xlings-index-version
-    // marker records that state.
-    std::string indexSource = "auto";
-    if (auto* e = std::getenv("XLINGS_INDEX_SOURCE"); e && *e) indexSource = e;
-
-    bool mainArtifactManaged = fs::exists(mainDir / ".xlings-index-version");
-    bool mainHasIndex = fs::exists(mainDir / "pkgs");
-
-    // The artifact is the OFFICIAL xim index. In auto mode it applies ONLY when
-    // the configured main index is the official index from a *remote* source —
-    // never when the user points index_repos at a local path (file://, abs
-    // path: test fixtures, project-local indexes) or a custom fork URL, which
-    // must be managed by their own source (git/local).
-    auto globalRepos = Config::global_index_repos();
-    bool mainIsOfficialRemote =
-        !globalRepos.empty()
-        && !Config::is_local_repo_source(globalRepos.front(), false)
-        && (globalRepos.front().url.find("openxlings/xim-pkgindex") != std::string::npos
-            || globalRepos.front().url.find("sunrisepeak/xim-pkgindex") != std::string::npos);
-
-    // auto: the official remote main index always converges to artifact (a
-    // stranded git main self-heals; see main_should_attempt_artifact). git stays
-    // the fallback. XLINGS_INDEX_SOURCE=artifact forces it (power user / tests);
-    // =git disables. Non-official/local/fork mains are excluded upstream.
-    bool attemptArtifact = main_should_attempt_artifact(
-        mainIsOfficialRemote, indexSource, mainArtifactManaged, mainHasIndex);
-
-    if (attemptArtifact) {
-        std::string ferr;
-        // #476: the main index honours a pin the same way sub-indexes do. It is
-        // the first entry of index_repos (the primary), which is also the repo
-        // whose name namespaces bare package targets.
-        const std::string mainPin =
-            globalRepos.empty() ? std::string{} : globalRepos.front().version;
-        if (fetch_index_artifact(mainDir, ferr, {}, nullptr, mainPin)) {
-            mainArtifactManaged = true;
-        } else if (indexSource == "artifact") {
-            log::error("[index] artifact fetch failed and git fallback disabled "
-                       "(XLINGS_INDEX_SOURCE=artifact): {}", ferr);
-            return false;
-        } else {
-            log::warn("[index] artifact fetch failed ({}); falling back to git", ferr);
-        }
-    }
-
-    // #374: best-effort. A single degenerate/unreachable index repo (no
-    // pkgs/, empty default-namespace redirect target, dead URL) must NOT
-    // abort the whole sync and collapse the catalog — that is the exact
-    // ">=2 index_repos -> silent exit 1" trigger. Skip the bad repo with a
-    // warning and keep syncing the rest, mirroring the best-effort handling
-    // the sub-index loop below already has. Returns false only when NOTHING
-    // in a non-empty list could be synced; the catalog rebuild's load-gate
-    // is the real "nothing usable" safety net.
-    auto syncRepos = [&](const std::vector<IndexRepo>& repos, bool projectScope) {
-        auto rootDir = projectScope ? Config::project_data_dir() : Config::global_data_dir();
-        if (rootDir.empty()) return true;
-        fs::create_directories(rootDir);
-        int total = 0, ok = 0;
-        for (auto& repo : repos) {
-            ++total;
-            auto repoDir = Config::repo_dir_for(repo, projectScope);
-            // The main index is artifact-managed (no .git); never git-sync it.
-            if (!projectScope && mainArtifactManaged && repoDir == mainDir) { ++ok; continue; }
-
-            auto fallbackSync = [&]() -> bool {
-                if (Config::is_local_repo_source(repo, projectScope)) {
-                    auto sourceDir = Config::resolve_repo_source(repo, projectScope);
-                    if (!detail_::ensure_local_repo_link_(repoDir, sourceDir)) {
-                        log::warn("index repo '{}' skipped: local source has no pkgs/ ({})",
-                                  repo.name, sourceDir.string());
-                        return false;
-                    }
-                    return true;
-                }
-                auto url = detail_::sync_repo_url_(repo.url, mirror);
-                if (!sync_repo(repoDir, url, force)) {
-                    log::warn("index repo '{}' skipped: sync failed ({})", repo.name, url);
-                    return false;
-                }
-                return true;
-            };
-
-            // #377: a repo-declared artifact source is tried first; git/local
-            // remains the fallback (source:"artifact" disables it in the helper).
-            bool okOne = repo.artifactBase.empty()
-                ? fallbackSync()
-                : sync_repo_with_artifact(repo, repoDir, indexSource, fallbackSync);
-            if (okOne) ++ok;
-        }
-        return total == 0 || ok > 0;
-    };
-
-    if (!syncRepos(Config::global_index_repos(), false)) return false;
-
-    // Discover and sync sub-index repos from the main repo's xim-indexrepos.lua
-    auto luaSubRepos = detail_::discover_sub_repos_(mainDir, mirror.empty() ? "GLOBAL" : mirror);
-    auto jsonSubRepos = load_sub_repos_json(sub_repos_json_path());
-
-    // Merge: lua defaults are authoritative for their own names; json adds only
-    // user-added sub-indexes (names absent from the lua defaults). See
-    // merge_sub_repos for why json must NOT override lua defaults (an
-    // org-drifted default would otherwise stay pinned to a stale json URL and
-    // never migrate to the artifact path).
-    auto allSubRepos = merge_sub_repos(luaSubRepos, jsonSubRepos);
-    std::vector<IndexRepo> syncedSubRepos;
-
-    // Default sub-indexes — those provided by the main index's
-    // xim-indexrepos.lua at their declared (now-authoritative) URL and from a
-    // remote source — are fetched as artifacts, same model as the main index.
-    // User-added sub-indexes (in xim-indexrepos.json but NOT a lua default),
-    // URL-overridden ones, and local (file://) sources keep git.
-    //
-    // The signal is "name is a lua default AND its URL matches the lua default".
-    // Because merge_sub_repos makes lua authoritative, repo.url == luaUrl for
-    // every lua default, so this also recognises a default whose official org
-    // moved (the stale json copy no longer overrides it).
-    std::unordered_map<std::string, std::string> luaUrl;
-    for (auto& r : luaSubRepos) luaUrl[r.name] = r.url;
-
-    auto subReposRoot = sub_repos_dir();
-    fs::create_directories(subReposRoot);
-
-    for (auto& repo : allSubRepos) {
-        auto repoDir = sub_repo_dir_for(repo);
-        auto luaIt = luaUrl.find(repo.name);
-        bool subDefaultOfficial =
-            luaIt != luaUrl.end() && luaIt->second == repo.url
-            && !Config::is_local_repo_source(repo, false);
-        bool subManaged = fs::exists(repoDir / ".xlings-index-version");
-        // #377: user-added sub-indexes may declare their own artifact source.
-        std::optional<ArtifactSource> customSrc;
-        if (!subDefaultOfficial) customSrc = artifact_source_for(repo);
-        std::string subMode = repo.source.empty() ? indexSource : repo.source;
-        bool subAttemptArtifact = sub_should_attempt_artifact(
-            subDefaultOfficial, subMode, subManaged,
-            fs::exists(repoDir / "pkgs"), mainArtifactManaged, customSrc.has_value());
-
-        bool ok = false;
-        if (subAttemptArtifact) {
-            std::string ferr;
-            ok = fetch_index_artifact(repoDir, ferr, repo.name,
-                                      customSrc ? &*customSrc : nullptr,
-                                      repo.version);
-            if (!ok)
-                log::warn("[index] sub-index '{}' artifact fetch failed: {}", repo.name, ferr);
-        }
-        // git fallback (and the path for user-added / local sub-indexes), unless
-        // the sub was explicitly pinned to the artifact source.
-        if (!ok && !(subMode == "artifact" && (subDefaultOfficial || customSrc.has_value()))) {
-            ok = sync_repo(repoDir, repo.url, force);
-        }
-        if (ok) syncedSubRepos.push_back(repo);
-        else log::warn("failed to sync sub-index repo: {} ({})", repo.name, repo.url);
-    }
-
-    save_sub_repos_json(sub_repos_json_path(), syncedSubRepos);
-
-    if (Config::has_project_config() && !Config::project_index_repos().empty()) {
-        if (!syncRepos(Config::project_index_repos(), true)) return false;
-
-        // Discover and sync sub-index repos from project index repos
-        auto mirrorKey = mirror.empty() ? "GLOBAL" : mirror;
-        auto& projRepos = Config::project_index_repos();
-        std::unordered_map<std::string, IndexRepo> projMerged;
-        for (auto& repo : projRepos) {
-            auto repoDir = Config::repo_dir_for(repo, true);
-            for (auto& sub : detail_::discover_sub_repos_(repoDir, mirrorKey)) {
-                projMerged[sub.name] = sub;
-            }
-        }
-        auto projJsonSubs = load_sub_repos_json(sub_repos_json_path(true));
-        for (auto& repo : projJsonSubs) projMerged[repo.name] = repo;
-
-        std::vector<IndexRepo> projSyncedSubs;
-        auto projSubRoot = sub_repos_dir(true);
-        fs::create_directories(projSubRoot);
-        for (auto& [name, repo] : projMerged) {
-            auto repoDir = sub_repo_dir_for(repo, true);
-            // #377: project sub-indexes may declare artifact sources too.
-            auto fallbackSync = [&]{ return sync_repo(repoDir, repo.url, force); };
-            bool okOne = repo.artifactBase.empty()
-                ? fallbackSync()
-                : sync_repo_with_artifact(repo, repoDir, indexSource, fallbackSync);
-            if (okOne) {
-                projSyncedSubs.push_back(repo);
-            } else {
-                log::warn("failed to sync project sub-index repo: {} ({})", repo.name, repo.url);
-            }
-        }
-        save_sub_repos_json(sub_repos_json_path(true), projSyncedSubs);
-    }
-    return true;
-}
+bool sync_all_repos(bool force = false);
 
 // Read the git HEAD hash for a repo directory.
 // Returns empty string for non-git repos or on any error.
-std::string get_repo_head_hash(const std::filesystem::path& repoDir) {
-    namespace fs = std::filesystem;
-    auto headFile = repoDir / ".git" / "HEAD";
-    if (!fs::exists(headFile)) {
-        // Artifact-managed index (no .git): key the parsed-index cache
-        // (.xlings-index-cache.json) on the .xlings-index-version marker.
-        // Artifacts are version-unique, so the marker is a stable cache key
-        // that changes only on re-install. Without this the hash is empty and
-        // load_or_rebuild disables caching -> a full index rebuild (the noisy
-        // "[1/7] awesome::..." scan) on EVERY xlings install/search.
-        auto verFile = repoDir / ".xlings-index-version";
-        if (fs::exists(verFile)) {
-            try {
-                auto v = platform::read_file_to_string(verFile.string());
-                while (!v.empty() && (v.back() == '\n' || v.back() == '\r' || v.back() == ' '))
-                    v.pop_back();
-                if (!v.empty()) return "artifact:" + v;
-            } catch (...) {}
-        }
-        return {};
-    }
-
-    try {
-        auto content = platform::read_file_to_string(headFile.string());
-        // Trim trailing whitespace/newlines
-        while (!content.empty() && (content.back() == '\n' || content.back() == '\r' || content.back() == ' '))
-            content.pop_back();
-
-        // Direct hash (detached HEAD)
-        if (!content.starts_with("ref: ")) return content;
-
-        // Symbolic ref: read the referenced file
-        auto ref = content.substr(5);
-        auto refFile = repoDir / ".git" / ref;
-        if (!fs::exists(refFile)) return {};
-
-        auto hash = platform::read_file_to_string(refFile.string());
-        while (!hash.empty() && (hash.back() == '\n' || hash.back() == '\r' || hash.back() == ' '))
-            hash.pop_back();
-        return hash;
-    } catch (...) {
-        return {};
-    }
-}
+std::string get_repo_head_hash(const std::filesystem::path& repoDir);
 
 } // namespace xlings::xim
diff --git a/src/core/xim/resolver.cpp b/src/core/xim/resolver.cpp
new file mode 100644
index 00000000..f067c470
--- /dev/null
+++ b/src/core/xim/resolver.cpp
@@ -0,0 +1,242 @@
+module xlings.core.xim.resolver;
+
+import std;
+import mcpplibs.xpkg;
+import xlings.core.xim.libxpkg.types.type;
+import xlings.core.xim.index;
+import xlings.core.xim.catalog;
+import xlings.core.xim.install_state;
+import xlings.core.config;
+import xlings.core.xim.compatibility;
+import xlings.core.log;
+import xlings.core.semver;
+import xlings.platform;
+
+namespace xlings::xim {
+
+std::pair<std::string, std::string> parse_target_(const std::string& target) {
+    auto at = target.find('@');
+    if (at == std::string::npos) return { target, "" };
+    return { target.substr(0, at), target.substr(at + 1) };
+}
+
+std::string node_key_(std::string_view canonicalName, std::string_view version) {
+    if (version.empty()) return std::string(canonicalName);
+    return std::string(canonicalName) + "@" + std::string(version);
+}
+
+std::string node_key_(const PackageMatch& match) {
+    return node_key_(match.canonicalName, match.version);
+}
+
+std::string pin_target_to_active(const std::string& target,
+                                 const ActiveVersionFn& activeOf) {
+    if (!activeOf) return target;
+    auto [namePart, versionHint] = parse_target_(target);
+    if (namePart.empty()) return target;
+    auto bareName = namePart.substr(namePart.rfind(':') + 1);
+    auto active = activeOf(bareName);
+    if (active.empty()) return target;
+    if (!semver::satisfies_expr(active, versionHint)) return target;
+    return namePart + "@" + active;
+}
+
+std::expected<InstallPlan, std::string>
+resolve(PackageCatalog& catalog, std::span<const std::string> targets, const std::string& platform, const ActiveVersionFn& activeOf, const std::string& hostArch) {
+
+    InstallPlan plan;
+
+    // Built once for the whole resolution. Nothing registers while a plan is
+    // being computed, so one snapshot is correct for every node in it -- and
+    // the question it answers is about what a PREVIOUS run left behind.
+    const LedgerIndex ledgerIndex(
+        Config::versions(), Config::paths().homeDir.string());
+
+    std::unordered_map<std::string, Color_> color;
+    std::unordered_map<std::string, PlanNode> nodeMap;
+
+    std::function<bool(const std::string&, std::vector<std::string>&, DepKind)> expand =
+        [&](const std::string& target, std::vector<std::string>& path, DepKind kind) -> bool {
+        // Pin before resolving, and fall back to the unpinned target if the
+        // pinned one no longer exists in the catalog -- an active version can
+        // outlive its declaration, and that must degrade to "resolve normally"
+        // rather than to "package not found".
+        const auto pinned = pin_target_to_active(target, activeOf);
+        auto resolved = catalog.resolve_target(pinned, platform);
+        if (!resolved && pinned != target) {
+            resolved = catalog.resolve_target(target, platform);
+        }
+        if (!resolved) {
+            plan.errors.push_back(resolved.error());
+            return false;
+        }
+
+        auto match = *resolved;
+        auto key = node_key_(match);
+
+        auto it = color.find(key);
+        if (it != color.end()) {
+            if (it->second == Color_::Gray) {
+                std::string cycle;
+                for (auto& p : path) cycle += p + " -> ";
+                cycle += key;
+                plan.errors.push_back(std::format("cyclic dependency detected: {}", cycle));
+                return false;
+            }
+            // Already processed. If we're encountering this node via a
+            // Runtime walk this time but it was first seen as Build,
+            // upgrade its kind so the installer activates it. Build does
+            // NOT downgrade Runtime — Runtime always wins.
+            if (kind == DepKind::Runtime) {
+                auto nit = nodeMap.find(key);
+                if (nit != nodeMap.end() && nit->second.kind == DepKind::Build)
+                    nit->second.kind = DepKind::Runtime;
+            }
+            return true;
+        }
+
+        color[key] = Color_::Gray;
+        path.push_back(key);
+
+        PlanNode node;
+        node.rawName = match.rawName;
+        node.name = match.name;
+        node.version = match.version;
+        node.namespaceName = match.namespaceName;
+        node.canonicalName = match.canonicalName;
+        node.repoName = match.repoName;
+        node.pkgFile = match.pkgFile;
+        node.storeRoot = match.storeRoot;
+        node.scope = match.scope;
+        // Foreign payloads plan as NOT installed, so the artifact is
+        // downloaded and the install hook has something to unpack.
+        //
+        // An INCOMPLETE payload plans as not installed for the same reason,
+        // and the planner has to agree with the installer here or the two
+        // contradict each other on screen: the installer re-runs the hook of
+        // an incomplete payload, while a planner that still called it
+        // installed printed "nothing to do" and then "already installed" in
+        // the same run that reinstalled it. Same predicate, both places.
+        node.alreadyInstalled = match.installed && !match.payloadForeign
+            && !installation_state(
+                   ledgerIndex, match.namespaceName, match.name, match.version,
+                   match.storeRoot
+                       / package_store_name(match.namespaceName, match.name)
+                       / match.version)
+                   .is_incomplete();
+        node.kind = kind;
+
+        auto pkg = catalog.load_package(match);
+        if (pkg) {
+            // Evidence-graded, and asked of the entry this node would
+            // download. Refusing here keeps the "zero requests for an
+            // unsupported target" contract, but only for a resource that
+            // enumerates its architectures and does not list this one -- a
+            // package-level `archs` union is never enough to stop a plan.
+            const auto* entry = find_entry(*pkg, platform, node.version);
+            const auto compatibility = check_target_compatibility(
+                *pkg, entry, platform, hostArch);
+            if (!compatibility.supported) {
+                std::string chain;
+                for (const auto& item : path) {
+                    if (!chain.empty()) chain += " -> ";
+                    chain += item;
+                }
+                plan.errors.push_back(std::format("{}: {}", chain,
+                    compatibility_error(match.canonicalName, compatibility)));
+                color[key] = Color_::Black;
+                path.pop_back();
+                return false;
+            }
+            node.pkgType = static_cast<int>(pkg->type);
+
+            auto rtIt = pkg->xpm.runtime_deps.find(platform);
+            if (rtIt != pkg->xpm.runtime_deps.end()) node.runtime_deps = rtIt->second;
+            auto bdIt = pkg->xpm.build_deps.find(platform);
+            if (bdIt != pkg->xpm.build_deps.end()) node.build_deps = bdIt->second;
+            auto depsIt = pkg->xpm.deps.find(platform);
+            if (depsIt != pkg->xpm.deps.end()) node.deps = depsIt->second;
+
+            // Pull the package's own exports for this platform (parsed from
+            // xpm.<platform>.exports.runtime by the libxpkg loader). An empty
+            // `loader` means "this package doesn't provide a dynamic linker";
+            // predicate-driven elfpatch reads this.
+            auto exIt = pkg->xpm.exports.find(platform);
+            if (exIt != pkg->xpm.exports.end()) {
+                node.exports.loader  = exIt->second.runtime.loader;
+                node.exports.libdirs = exIt->second.runtime.libdirs;
+                node.exports.abi     = exIt->second.runtime.abi;
+            }
+
+            // What the recipe promises this package provides. Verified after
+            // the whole install completes -- not here -- because a package may
+            // legitimately delegate its registration to a deferred install
+            // (gcc on Windows hands off to mingw-w64).
+            node.programs = pkg->programs;
+
+            DepKind rt_kind = (kind == DepKind::Build) ? DepKind::Build
+                                                       : DepKind::Runtime;
+            for (auto& dep : node.runtime_deps) {
+                if (!expand(dep, path, rt_kind)) { /* keep collecting */ }
+            }
+            for (auto& dep : node.build_deps) {
+                if (!expand(dep, path, DepKind::Build)) { /* keep collecting */ }
+            }
+        } else {
+            log::warn("failed to load package {}: {}", key, pkg.error());
+        }
+
+        nodeMap[key] = std::move(node);
+        color[key] = Color_::Black;
+        path.pop_back();
+        return true;
+    };
+
+    for (auto& target : targets) {
+        std::vector<std::string> path;
+        expand(target, path, DepKind::Runtime);
+    }
+
+    if (plan.has_errors()) {
+        return plan;
+    }
+
+    std::vector<std::string> topoOrder;
+    std::unordered_set<std::string> visited;
+
+    std::function<void(const std::string&)> topoVisit =
+        [&](const std::string& key) {
+        if (visited.count(key)) return;
+        visited.insert(key);
+
+        auto it = nodeMap.find(key);
+        if (it == nodeMap.end()) return;
+
+        for (auto& dep : it->second.deps) {
+            // Pin exactly as expand() did, or this recomputes a key the node
+            // map does not have and the edge is silently dropped.
+            const auto pinned = pin_target_to_active(dep, activeOf);
+            auto depMatch = catalog.resolve_target(pinned, platform);
+            if (!depMatch && pinned != dep) {
+                depMatch = catalog.resolve_target(dep, platform);
+            }
+            if (depMatch) topoVisit(node_key_(*depMatch));
+        }
+        topoOrder.push_back(key);
+    };
+
+    for (auto& [key, _] : nodeMap) {
+        topoVisit(key);
+    }
+
+    for (auto& key : topoOrder) {
+        auto it = nodeMap.find(key);
+        if (it != nodeMap.end()) {
+            plan.nodes.push_back(std::move(it->second));
+        }
+    }
+
+    return plan;
+}
+
+}
diff --git a/src/core/xim/resolver.cppm b/src/core/xim/resolver.cppm
index 0379a275..ed80fb7d 100644
--- a/src/core/xim/resolver.cppm
+++ b/src/core/xim/resolver.cppm
@@ -8,8 +8,6 @@ import xlings.core.xim.catalog;
 import xlings.core.xim.install_state;
 import xlings.core.config;
 import xlings.core.xim.compatibility;
-import xlings.core.log;
-import xlings.core.semver;
 import xlings.platform;
 
 export namespace xlings::xim {
@@ -18,20 +16,11 @@ export namespace xlings::xim {
 enum class Color_ { White, Gray, Black };
 
 // Parse a target like "gcc@15" into (name, version_hint)
-std::pair<std::string, std::string> parse_target_(const std::string& target) {
-    auto at = target.find('@');
-    if (at == std::string::npos) return { target, "" };
-    return { target.substr(0, at), target.substr(at + 1) };
-}
+std::pair<std::string, std::string> parse_target_(const std::string& target);
 
-std::string node_key_(std::string_view canonicalName, std::string_view version) {
-    if (version.empty()) return std::string(canonicalName);
-    return std::string(canonicalName) + "@" + std::string(version);
-}
+std::string node_key_(std::string_view canonicalName, std::string_view version);
 
-std::string node_key_(const PackageMatch& match) {
-    return node_key_(match.canonicalName, match.version);
-}
+std::string node_key_(const PackageMatch& match);
 
 // What version of `name` is active in the caller's workspace, if any.
 // Injected rather than read here so the resolver stays free of Config/xvm.
@@ -52,16 +41,7 @@ using ActiveVersionFn = std::function<std::string(const std::string&)>;
 // active or the active version does not satisfy: a pin is an optimisation,
 // never a way to end up with a version the target excluded.
 std::string pin_target_to_active(const std::string& target,
-                                 const ActiveVersionFn& activeOf) {
-    if (!activeOf) return target;
-    auto [namePart, versionHint] = parse_target_(target);
-    if (namePart.empty()) return target;
-    auto bareName = namePart.substr(namePart.rfind(':') + 1);
-    auto active = activeOf(bareName);
-    if (active.empty()) return target;
-    if (!semver::satisfies_expr(active, versionHint)) return target;
-    return namePart + "@" + active;
-}
+                                 const ActiveVersionFn& activeOf);
 
 // Resolve targets into a full install plan.
 //
@@ -81,201 +61,6 @@ resolve(PackageCatalog& catalog,
         std::span<const std::string> targets,
         const std::string& platform,
         const ActiveVersionFn& activeOf = {},
-        const std::string& hostArch = host_architecture()) {
-
-    InstallPlan plan;
-
-    // Built once for the whole resolution. Nothing registers while a plan is
-    // being computed, so one snapshot is correct for every node in it -- and
-    // the question it answers is about what a PREVIOUS run left behind.
-    const LedgerIndex ledgerIndex(
-        Config::versions(), Config::paths().homeDir.string());
-
-    std::unordered_map<std::string, Color_> color;
-    std::unordered_map<std::string, PlanNode> nodeMap;
-
-    std::function<bool(const std::string&, std::vector<std::string>&, DepKind)> expand =
-        [&](const std::string& target, std::vector<std::string>& path, DepKind kind) -> bool {
-        // Pin before resolving, and fall back to the unpinned target if the
-        // pinned one no longer exists in the catalog -- an active version can
-        // outlive its declaration, and that must degrade to "resolve normally"
-        // rather than to "package not found".
-        const auto pinned = pin_target_to_active(target, activeOf);
-        auto resolved = catalog.resolve_target(pinned, platform);
-        if (!resolved && pinned != target) {
-            resolved = catalog.resolve_target(target, platform);
-        }
-        if (!resolved) {
-            plan.errors.push_back(resolved.error());
-            return false;
-        }
-
-        auto match = *resolved;
-        auto key = node_key_(match);
-
-        auto it = color.find(key);
-        if (it != color.end()) {
-            if (it->second == Color_::Gray) {
-                std::string cycle;
-                for (auto& p : path) cycle += p + " -> ";
-                cycle += key;
-                plan.errors.push_back(std::format("cyclic dependency detected: {}", cycle));
-                return false;
-            }
-            // Already processed. If we're encountering this node via a
-            // Runtime walk this time but it was first seen as Build,
-            // upgrade its kind so the installer activates it. Build does
-            // NOT downgrade Runtime — Runtime always wins.
-            if (kind == DepKind::Runtime) {
-                auto nit = nodeMap.find(key);
-                if (nit != nodeMap.end() && nit->second.kind == DepKind::Build)
-                    nit->second.kind = DepKind::Runtime;
-            }
-            return true;
-        }
-
-        color[key] = Color_::Gray;
-        path.push_back(key);
-
-        PlanNode node;
-        node.rawName = match.rawName;
-        node.name = match.name;
-        node.version = match.version;
-        node.namespaceName = match.namespaceName;
-        node.canonicalName = match.canonicalName;
-        node.repoName = match.repoName;
-        node.pkgFile = match.pkgFile;
-        node.storeRoot = match.storeRoot;
-        node.scope = match.scope;
-        // Foreign payloads plan as NOT installed, so the artifact is
-        // downloaded and the install hook has something to unpack.
-        //
-        // An INCOMPLETE payload plans as not installed for the same reason,
-        // and the planner has to agree with the installer here or the two
-        // contradict each other on screen: the installer re-runs the hook of
-        // an incomplete payload, while a planner that still called it
-        // installed printed "nothing to do" and then "already installed" in
-        // the same run that reinstalled it. Same predicate, both places.
-        node.alreadyInstalled = match.installed && !match.payloadForeign
-            && !installation_state(
-                   ledgerIndex, match.namespaceName, match.name, match.version,
-                   match.storeRoot
-                       / package_store_name(match.namespaceName, match.name)
-                       / match.version)
-                   .is_incomplete();
-        node.kind = kind;
-
-        auto pkg = catalog.load_package(match);
-        if (pkg) {
-            // Evidence-graded, and asked of the entry this node would
-            // download. Refusing here keeps the "zero requests for an
-            // unsupported target" contract, but only for a resource that
-            // enumerates its architectures and does not list this one -- a
-            // package-level `archs` union is never enough to stop a plan.
-            const auto* entry = find_entry(*pkg, platform, node.version);
-            const auto compatibility = check_target_compatibility(
-                *pkg, entry, platform, hostArch);
-            if (!compatibility.supported) {
-                std::string chain;
-                for (const auto& item : path) {
-                    if (!chain.empty()) chain += " -> ";
-                    chain += item;
-                }
-                plan.errors.push_back(std::format("{}: {}", chain,
-                    compatibility_error(match.canonicalName, compatibility)));
-                color[key] = Color_::Black;
-                path.pop_back();
-                return false;
-            }
-            node.pkgType = static_cast<int>(pkg->type);
-
-            auto rtIt = pkg->xpm.runtime_deps.find(platform);
-            if (rtIt != pkg->xpm.runtime_deps.end()) node.runtime_deps = rtIt->second;
-            auto bdIt = pkg->xpm.build_deps.find(platform);
-            if (bdIt != pkg->xpm.build_deps.end()) node.build_deps = bdIt->second;
-            auto depsIt = pkg->xpm.deps.find(platform);
-            if (depsIt != pkg->xpm.deps.end()) node.deps = depsIt->second;
-
-            // Pull the package's own exports for this platform (parsed from
-            // xpm.<platform>.exports.runtime by the libxpkg loader). An empty
-            // `loader` means "this package doesn't provide a dynamic linker";
-            // predicate-driven elfpatch reads this.
-            auto exIt = pkg->xpm.exports.find(platform);
-            if (exIt != pkg->xpm.exports.end()) {
-                node.exports.loader  = exIt->second.runtime.loader;
-                node.exports.libdirs = exIt->second.runtime.libdirs;
-                node.exports.abi     = exIt->second.runtime.abi;
-            }
-
-            // What the recipe promises this package provides. Verified after
-            // the whole install completes -- not here -- because a package may
-            // legitimately delegate its registration to a deferred install
-            // (gcc on Windows hands off to mingw-w64).
-            node.programs = pkg->programs;
-
-            DepKind rt_kind = (kind == DepKind::Build) ? DepKind::Build
-                                                       : DepKind::Runtime;
-            for (auto& dep : node.runtime_deps) {
-                if (!expand(dep, path, rt_kind)) { /* keep collecting */ }
-            }
-            for (auto& dep : node.build_deps) {
-                if (!expand(dep, path, DepKind::Build)) { /* keep collecting */ }
-            }
-        } else {
-            log::warn("failed to load package {}: {}", key, pkg.error());
-        }
-
-        nodeMap[key] = std::move(node);
-        color[key] = Color_::Black;
-        path.pop_back();
-        return true;
-    };
-
-    for (auto& target : targets) {
-        std::vector<std::string> path;
-        expand(target, path, DepKind::Runtime);
-    }
-
-    if (plan.has_errors()) {
-        return plan;
-    }
-
-    std::vector<std::string> topoOrder;
-    std::unordered_set<std::string> visited;
-
-    std::function<void(const std::string&)> topoVisit =
-        [&](const std::string& key) {
-        if (visited.count(key)) return;
-        visited.insert(key);
-
-        auto it = nodeMap.find(key);
-        if (it == nodeMap.end()) return;
-
-        for (auto& dep : it->second.deps) {
-            // Pin exactly as expand() did, or this recomputes a key the node
-            // map does not have and the edge is silently dropped.
-            const auto pinned = pin_target_to_active(dep, activeOf);
-            auto depMatch = catalog.resolve_target(pinned, platform);
-            if (!depMatch && pinned != dep) {
-                depMatch = catalog.resolve_target(dep, platform);
-            }
-            if (depMatch) topoVisit(node_key_(*depMatch));
-        }
-        topoOrder.push_back(key);
-    };
-
-    for (auto& [key, _] : nodeMap) {
-        topoVisit(key);
-    }
-
-    for (auto& key : topoOrder) {
-        auto it = nodeMap.find(key);
-        if (it != nodeMap.end()) {
-            plan.nodes.push_back(std::move(it->second));
-        }
-    }
-
-    return plan;
-}
+        const std::string& hostArch = host_architecture());
 
 } // namespace xlings::xim
diff --git a/src/core/xself.cpp b/src/core/xself.cpp
new file mode 100644
index 00000000..73834cb6
--- /dev/null
+++ b/src/core/xself.cpp
@@ -0,0 +1,199 @@
+// xlings.core.xself — top-level module entry for the `xlings self ...`
+// command family.
+//
+// All actual command implementations live in partition files under
+// src/core/xself/. This file's only job is to (a) re-export the public
+// surface from those partitions and (b) route subcommand names to them.
+//
+// Layout:
+//   xself.cppm                  — this file (router + help)
+//   xself/init.cppm             — home layout helpers + `self init`
+//   xself/install.cppm          — `self install` (bootstrap from release tarball)
+//   xself/uninstall.cppm        — `self uninstall [-y] [--keep-data] [--dry-run]`
+//   xself/update.cppm           — `self update`
+//   xself/config.cppm           — `self config`
+//   xself/clean.cppm            — `self clean [--dry-run]`
+//   xself/migrate.cppm          — `self migrate`
+//   xself/doctor.cppm           — `self doctor [--deep] [--scope PKG] [--fix]`
+//   compact/xself.cppm          — cross-version compat shims, organized
+//                                 into vX_Y_Z sub-namespaces. See its
+//                                 header for the removal procedure when
+//                                 a compat block expires.
+
+module xlings.core.xself;
+
+import std;
+import xlings.core.xself.init;
+import xlings.core.xself.install;
+import xlings.core.xself.uninstall;
+import xlings.core.xself.update;
+import xlings.core.xself.config;
+import xlings.core.xself.clean;
+import xlings.core.xself.migrate;
+import xlings.core.xself.doctor;
+import xlings.core.xself.compat;
+import xlings.libs.json;
+import xlings.runtime;
+import xlings.cli.spec;
+
+namespace xlings::xself {
+
+int cmd_help(EventStream& stream) {
+    nlohmann::json payload;
+    payload["name"] = "self";
+    payload["description"] = "Manage xlings itself";
+    payload["args"] = nlohmann::json::array();
+    payload["opts"] = nlohmann::json::array({
+        {{"name", "install"},   {"desc", "Install xlings from release package"}},
+        {{"name", "uninstall"}, {"desc", "Remove this xlings install entirely (-y / --keep-data / --dry-run)"}},
+        {{"name", "init"},      {"desc", "Create home/data/subos dirs"}},
+        {{"name", "update"},    {"desc", "Update index + install latest xlings"}},
+        {{"name", "config"},    {"desc", "Show configuration details"}},
+        {{"name", "clean"},     {"desc", "Remove cache + gc orphaned packages (--dry-run)"}},
+        {{"name", "migrate"},   {"desc", "Migrate old layout to subos/default"}},
+        {{"name", "doctor"},    {"desc", "Verify workspace/shim consistency (--deep for payload/runtime audits, optionally --scope PACKAGE[@VERSION]; --fix implies deep, --dry-run previews repairs, --all lists non-defects, --reset-metadata discards unreadable release metadata)"}},
+    });
+    stream.emit(DataEvent{"help", payload.dump()});
+    return 0;
+}
+
+int run(int argc, char* argv[], EventStream& stream) {
+    std::string action = (argc >= 3) ? argv[2] : "help";
+
+    // Drop the options root publishes as valid on every command before any
+    // action inspects argv. `xlings self doctor --yes` names a documented
+    // global flag on a command that has nothing to confirm: the right answer
+    // is to ignore it, not to exit 2 and make `xlings --help` a liar. Doing
+    // it once here also keeps every action's loop free of the same skip.
+    std::vector<std::string> args;
+    for (int i = 3; i < argc; ++i) {
+        if (cli::spec::is_global_option(argv[i])) continue;
+        args.emplace_back(argv[i]);
+    }
+    const auto reject = [&](std::string_view command, const std::string& arg) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = std::format("unknown option for `xlings self {}`: {}",
+                                   command, arg),
+            .recoverable = false,
+        });
+        return 2;
+    };
+    const auto reject_surplus = [&](std::string_view command) {
+        return args.empty() ? 0 : reject(command, args.front());
+    };
+    if (action == "install") {
+        if (auto rc = reject_surplus(action); rc != 0) return rc;
+        return cmd_install();
+    }
+    if (action == "uninstall") {
+        UninstallOpts opts;
+        // `-y`/`--yes` is global and already stripped above; uninstall is the
+        // one action that has to look at it, so it reads the flag from the
+        // shared predicate rather than from its own argv scan.
+        for (int i = 3; i < argc; ++i) {
+            const std::string a = argv[i];
+            if (a == "-y" || a == "--yes") opts.yes = true;
+        }
+        for (const auto& a : args) {
+            if      (a == "--keep-data") opts.keepData = true;
+            else if (a == "--dry-run")   opts.dryRun   = true;
+            else return reject("uninstall", a);
+        }
+        return cmd_uninstall(opts);
+    }
+    if (action == "init") {
+        if (auto rc = reject_surplus(action); rc != 0) return rc;
+        return cmd_init();
+    }
+    if (action == "update") {
+        if (auto rc = reject_surplus(action); rc != 0) return rc;
+        return cmd_update();
+    }
+    if (action == "config") {
+        if (auto rc = reject_surplus(action); rc != 0) return rc;
+        return cmd_config(stream);
+    }
+    if (action == "clean") {
+        bool dryRun = false;
+        for (const auto& arg : args) {
+            if (arg == "--dry-run") dryRun = true;
+            else return reject("clean", arg);
+        }
+        return cmd_clean(dryRun);
+    }
+    if (action == "migrate") {
+        if (auto rc = reject_surplus(action); rc != 0) return rc;
+        return cmd_migrate();
+    }
+    if (action == "doctor") {
+        bool fix = false;
+        bool resetMetadata = false;
+        bool dryRun = false;
+        bool verbose = false;
+        bool deep = false;
+        std::optional<std::string> scope;
+        for (std::size_t i = 0; i < args.size(); ++i) {
+            const auto& arg = args[i];
+            if (arg == "--fix") fix = true;
+            // Discards unreadable binding metadata, so it is opt-in on top
+            // of --fix rather than part of it.
+            else if (arg == "--reset-metadata") resetMetadata = true;
+            // Show the repair plan without running it. Only meaningful
+            // with --fix, which is the flag that can now touch the network.
+            else if (arg == "--dry-run") dryRun = true;
+            // List the findings that are not defects -- release anchors,
+            // aliases that are probably system commands, notices about state
+            // the upgrade inherited. They are summarised to one counted line
+            // by default because there are dozens of them on a real home and
+            // they buried the handful that mattered.
+            //
+            // NOT `--verbose`: that one is a GLOBAL flag (cli.cppm raises the
+            // log level with it) and is STRIPPED from argv before this
+            // dispatch ever runs, so a `--verbose` here would be documented in
+            // the help text and silently do nothing.
+            else if (arg == "--all") verbose = true;
+            else if (arg == "--deep") deep = true;
+            else if (arg == "--scope") {
+                if (i + 1 >= args.size() || args[i + 1].starts_with('-')) {
+                    stream.emit(ErrorEvent{
+                        .code = ErrorCode::InvalidInput,
+                        .message = "missing value for option: --scope",
+                        .recoverable = false,
+                    });
+                    return 2;
+                }
+                scope = args[++i];
+            } else if (arg.starts_with("--scope=")) {
+                const auto value = arg.substr(std::string("--scope=").size());
+                if (value.empty()) {
+                    stream.emit(ErrorEvent{
+                        .code = ErrorCode::InvalidInput,
+                        .message = "missing value for option: --scope",
+                        .recoverable = false,
+                    });
+                    return 2;
+                }
+                scope = value;
+            } else {
+                return reject("doctor", arg);
+            }
+        }
+        return cmd_doctor(stream, fix, resetMetadata, dryRun, verbose,
+                          deep, std::move(scope));
+    }
+    // help / unknown-action handling. Distinguish a deliberate help
+    // request (no action / -h / --help) from a typo / made-up action so
+    // `xlings self bogus` exits non-zero instead of pretending success.
+    if (action == "help" || action == "-h" || action == "--help" || action.empty()) {
+        return cmd_help(stream);
+    }
+    stream.emit(ErrorEvent{
+        .code = ErrorCode::InvalidInput,
+        .message = "unknown 'self' action: " + action,
+        .recoverable = false,
+    });
+    return 2;
+}
+
+}
diff --git a/src/core/xself.cppm b/src/core/xself.cppm
index cd0fcd71..eeeaca6f 100644
--- a/src/core/xself.cppm
+++ b/src/core/xself.cppm
@@ -37,171 +37,13 @@ export import xlings.core.xself.doctor;
 // module without depending on the compact-managed module file directly.
 export import xlings.core.xself.compat;
 
-import xlings.libs.json;
 import xlings.runtime;
 // Leaf module (std + json only). `self` needs the same answer to "is this a
 // global option" that the CLI's own validator uses; importing the spec is what
 // stops the two from drifting into disagreeing about `--yes`.
-import xlings.cli.spec;
 
 namespace xlings::xself {
 
-static int cmd_help(EventStream& stream) {
-    nlohmann::json payload;
-    payload["name"] = "self";
-    payload["description"] = "Manage xlings itself";
-    payload["args"] = nlohmann::json::array();
-    payload["opts"] = nlohmann::json::array({
-        {{"name", "install"},   {"desc", "Install xlings from release package"}},
-        {{"name", "uninstall"}, {"desc", "Remove this xlings install entirely (-y / --keep-data / --dry-run)"}},
-        {{"name", "init"},      {"desc", "Create home/data/subos dirs"}},
-        {{"name", "update"},    {"desc", "Update index + install latest xlings"}},
-        {{"name", "config"},    {"desc", "Show configuration details"}},
-        {{"name", "clean"},     {"desc", "Remove cache + gc orphaned packages (--dry-run)"}},
-        {{"name", "migrate"},   {"desc", "Migrate old layout to subos/default"}},
-        {{"name", "doctor"},    {"desc", "Verify workspace/shim consistency (--deep for payload/runtime audits, optionally --scope PACKAGE[@VERSION]; --fix implies deep, --dry-run previews repairs, --all lists non-defects, --reset-metadata discards unreadable release metadata)"}},
-    });
-    stream.emit(DataEvent{"help", payload.dump()});
-    return 0;
-}
-
-export int run(int argc, char* argv[], EventStream& stream) {
-    std::string action = (argc >= 3) ? argv[2] : "help";
-
-    // Drop the options root publishes as valid on every command before any
-    // action inspects argv. `xlings self doctor --yes` names a documented
-    // global flag on a command that has nothing to confirm: the right answer
-    // is to ignore it, not to exit 2 and make `xlings --help` a liar. Doing
-    // it once here also keeps every action's loop free of the same skip.
-    std::vector<std::string> args;
-    for (int i = 3; i < argc; ++i) {
-        if (cli::spec::is_global_option(argv[i])) continue;
-        args.emplace_back(argv[i]);
-    }
-    const auto reject = [&](std::string_view command, const std::string& arg) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = std::format("unknown option for `xlings self {}`: {}",
-                                   command, arg),
-            .recoverable = false,
-        });
-        return 2;
-    };
-    const auto reject_surplus = [&](std::string_view command) {
-        return args.empty() ? 0 : reject(command, args.front());
-    };
-    if (action == "install") {
-        if (auto rc = reject_surplus(action); rc != 0) return rc;
-        return cmd_install();
-    }
-    if (action == "uninstall") {
-        UninstallOpts opts;
-        // `-y`/`--yes` is global and already stripped above; uninstall is the
-        // one action that has to look at it, so it reads the flag from the
-        // shared predicate rather than from its own argv scan.
-        for (int i = 3; i < argc; ++i) {
-            const std::string a = argv[i];
-            if (a == "-y" || a == "--yes") opts.yes = true;
-        }
-        for (const auto& a : args) {
-            if      (a == "--keep-data") opts.keepData = true;
-            else if (a == "--dry-run")   opts.dryRun   = true;
-            else return reject("uninstall", a);
-        }
-        return cmd_uninstall(opts);
-    }
-    if (action == "init") {
-        if (auto rc = reject_surplus(action); rc != 0) return rc;
-        return cmd_init();
-    }
-    if (action == "update") {
-        if (auto rc = reject_surplus(action); rc != 0) return rc;
-        return cmd_update();
-    }
-    if (action == "config") {
-        if (auto rc = reject_surplus(action); rc != 0) return rc;
-        return cmd_config(stream);
-    }
-    if (action == "clean") {
-        bool dryRun = false;
-        for (const auto& arg : args) {
-            if (arg == "--dry-run") dryRun = true;
-            else return reject("clean", arg);
-        }
-        return cmd_clean(dryRun);
-    }
-    if (action == "migrate") {
-        if (auto rc = reject_surplus(action); rc != 0) return rc;
-        return cmd_migrate();
-    }
-    if (action == "doctor") {
-        bool fix = false;
-        bool resetMetadata = false;
-        bool dryRun = false;
-        bool verbose = false;
-        bool deep = false;
-        std::optional<std::string> scope;
-        for (std::size_t i = 0; i < args.size(); ++i) {
-            const auto& arg = args[i];
-            if (arg == "--fix") fix = true;
-            // Discards unreadable binding metadata, so it is opt-in on top
-            // of --fix rather than part of it.
-            else if (arg == "--reset-metadata") resetMetadata = true;
-            // Show the repair plan without running it. Only meaningful
-            // with --fix, which is the flag that can now touch the network.
-            else if (arg == "--dry-run") dryRun = true;
-            // List the findings that are not defects -- release anchors,
-            // aliases that are probably system commands, notices about state
-            // the upgrade inherited. They are summarised to one counted line
-            // by default because there are dozens of them on a real home and
-            // they buried the handful that mattered.
-            //
-            // NOT `--verbose`: that one is a GLOBAL flag (cli.cppm raises the
-            // log level with it) and is STRIPPED from argv before this
-            // dispatch ever runs, so a `--verbose` here would be documented in
-            // the help text and silently do nothing.
-            else if (arg == "--all") verbose = true;
-            else if (arg == "--deep") deep = true;
-            else if (arg == "--scope") {
-                if (i + 1 >= args.size() || args[i + 1].starts_with('-')) {
-                    stream.emit(ErrorEvent{
-                        .code = ErrorCode::InvalidInput,
-                        .message = "missing value for option: --scope",
-                        .recoverable = false,
-                    });
-                    return 2;
-                }
-                scope = args[++i];
-            } else if (arg.starts_with("--scope=")) {
-                const auto value = arg.substr(std::string("--scope=").size());
-                if (value.empty()) {
-                    stream.emit(ErrorEvent{
-                        .code = ErrorCode::InvalidInput,
-                        .message = "missing value for option: --scope",
-                        .recoverable = false,
-                    });
-                    return 2;
-                }
-                scope = value;
-            } else {
-                return reject("doctor", arg);
-            }
-        }
-        return cmd_doctor(stream, fix, resetMetadata, dryRun, verbose,
-                          deep, std::move(scope));
-    }
-    // help / unknown-action handling. Distinguish a deliberate help
-    // request (no action / -h / --help) from a typo / made-up action so
-    // `xlings self bogus` exits non-zero instead of pretending success.
-    if (action == "help" || action == "-h" || action == "--help" || action.empty()) {
-        return cmd_help(stream);
-    }
-    stream.emit(ErrorEvent{
-        .code = ErrorCode::InvalidInput,
-        .message = "unknown 'self' action: " + action,
-        .recoverable = false,
-    });
-    return 2;
-}
+export int run(int argc, char* argv[], EventStream& stream);
 
 } // namespace xlings::xself
diff --git a/src/core/xself/clean.cpp b/src/core/xself/clean.cpp
new file mode 100644
index 00000000..ef162b13
--- /dev/null
+++ b/src/core/xself/clean.cpp
@@ -0,0 +1,35 @@
+module xlings.core.xself.clean;
+
+import std;
+import xlings.core.config;
+import xlings.core.log;
+import xlings.core.profile;
+
+namespace xlings::xself {
+
+int cmd_clean(bool dryRun) {
+    namespace fs = std::filesystem;
+    auto& p = Config::paths();
+
+    auto cachedir = p.homeDir / ".xlings";
+    if (fs::exists(cachedir) && fs::is_directory(cachedir)) {
+        if (dryRun) {
+            log::println("  would remove cache: {}", cachedir.string());
+        } else {
+            std::error_code ec;
+            fs::remove_all(cachedir, ec);
+            if (ec) {
+                log::error("failed to remove {}: {}", cachedir.string(), ec.message());
+                return 1;
+            }
+            log::debug("cleaned cache: {}", cachedir.string());
+        }
+    }
+
+    profile::gc(p.homeDir, dryRun);
+
+    if (!dryRun) log::info("clean ok");
+    return 0;
+}
+
+}
diff --git a/src/core/xself/clean.cppm b/src/core/xself/clean.cppm
index 156d804b..566a7a39 100644
--- a/src/core/xself/clean.cppm
+++ b/src/core/xself/clean.cppm
@@ -2,37 +2,11 @@ export module xlings.core.xself.clean;
 
 import std;
 
-import xlings.core.config;
-import xlings.core.log;
-import xlings.core.profile;
 
 namespace xlings::xself {
 
 // `xlings self clean [--dry-run]` — remove the cache directory and run
 // the profile-level GC of orphaned packages.
-export int cmd_clean(bool dryRun) {
-    namespace fs = std::filesystem;
-    auto& p = Config::paths();
-
-    auto cachedir = p.homeDir / ".xlings";
-    if (fs::exists(cachedir) && fs::is_directory(cachedir)) {
-        if (dryRun) {
-            log::println("  would remove cache: {}", cachedir.string());
-        } else {
-            std::error_code ec;
-            fs::remove_all(cachedir, ec);
-            if (ec) {
-                log::error("failed to remove {}: {}", cachedir.string(), ec.message());
-                return 1;
-            }
-            log::debug("cleaned cache: {}", cachedir.string());
-        }
-    }
-
-    profile::gc(p.homeDir, dryRun);
-
-    if (!dryRun) log::info("clean ok");
-    return 0;
-}
+export int cmd_clean(bool dryRun);
 
 } // namespace xlings::xself
diff --git a/src/core/xself/config.cpp b/src/core/xself/config.cpp
new file mode 100644
index 00000000..ae106991
--- /dev/null
+++ b/src/core/xself/config.cpp
@@ -0,0 +1,47 @@
+module xlings.core.xself.config;
+
+import std;
+import xlings.core.config;
+import xlings.libs.json;
+import xlings.runtime;
+
+namespace xlings::xself {
+
+int cmd_config(EventStream& stream) {
+    auto& p = Config::paths();
+    nlohmann::json fieldsJson = nlohmann::json::array();
+    auto addField = [&](const std::string& label, const std::string& value, bool hl = false) {
+        fieldsJson.push_back({{"label", label}, {"value", value}, {"highlight", hl}});
+    };
+    addField("XLINGS_HOME", p.homeDir.string());
+    addField("XLINGS_DATA", p.dataDir.string());
+    addField("XLINGS_SUBOS", p.subosDir.string());
+    addField("active subos", p.activeSubos, true);
+    addField("bin", p.binDir.string());
+
+    auto mirror = Config::mirror();
+    if (!mirror.empty()) addField("mirror", mirror);
+    auto lang = Config::lang();
+    if (!lang.empty()) addField("lang", lang);
+
+    auto& repos = Config::global_index_repos();
+    for (auto& repo : repos) {
+        addField("index-repo", repo.name + " : " + repo.url);
+    }
+
+    if (Config::has_project_config()) {
+        addField("project data", Config::project_data_dir().string());
+        auto& projectRepos = Config::project_index_repos();
+        for (auto& repo : projectRepos) {
+            addField("project repo", repo.name + " : " + repo.url);
+        }
+    }
+
+    nlohmann::json payload;
+    payload["title"] = "xlings config";
+    payload["fields"] = std::move(fieldsJson);
+    stream.emit(DataEvent{"info_panel", payload.dump()});
+    return 0;
+}
+
+}
diff --git a/src/core/xself/config.cppm b/src/core/xself/config.cppm
index 586ff2dc..08e2e6f3 100644
--- a/src/core/xself/config.cppm
+++ b/src/core/xself/config.cppm
@@ -2,49 +2,12 @@ export module xlings.core.xself.config;
 
 import std;
 
-import xlings.core.config;
-import xlings.libs.json;
 import xlings.runtime;
 
 namespace xlings::xself {
 
 // `xlings self config` — render the active config (paths, mirror, lang,
 // index repos, project overrides) as a TUI info panel via EventStream.
-export int cmd_config(EventStream& stream) {
-    auto& p = Config::paths();
-    nlohmann::json fieldsJson = nlohmann::json::array();
-    auto addField = [&](const std::string& label, const std::string& value, bool hl = false) {
-        fieldsJson.push_back({{"label", label}, {"value", value}, {"highlight", hl}});
-    };
-    addField("XLINGS_HOME", p.homeDir.string());
-    addField("XLINGS_DATA", p.dataDir.string());
-    addField("XLINGS_SUBOS", p.subosDir.string());
-    addField("active subos", p.activeSubos, true);
-    addField("bin", p.binDir.string());
-
-    auto mirror = Config::mirror();
-    if (!mirror.empty()) addField("mirror", mirror);
-    auto lang = Config::lang();
-    if (!lang.empty()) addField("lang", lang);
-
-    auto& repos = Config::global_index_repos();
-    for (auto& repo : repos) {
-        addField("index-repo", repo.name + " : " + repo.url);
-    }
-
-    if (Config::has_project_config()) {
-        addField("project data", Config::project_data_dir().string());
-        auto& projectRepos = Config::project_index_repos();
-        for (auto& repo : projectRepos) {
-            addField("project repo", repo.name + " : " + repo.url);
-        }
-    }
-
-    nlohmann::json payload;
-    payload["title"] = "xlings config";
-    payload["fields"] = std::move(fieldsJson);
-    stream.emit(DataEvent{"info_panel", payload.dump()});
-    return 0;
-}
+export int cmd_config(EventStream& stream);
 
 } // namespace xlings::xself
diff --git a/src/core/xself/doctor.cpp b/src/core/xself/doctor.cpp
new file mode 100644
index 00000000..72a14254
--- /dev/null
+++ b/src/core/xself/doctor.cpp
@@ -0,0 +1,3373 @@
+module;
+
+// The NSS cell needs the caller's effective uid. `import std;` does not pull
+// POSIX in, and a named module's purview forbids including it there, so it
+// goes in the global module fragment -- same arrangement as subos/sandbox.cppm.
+#if !defined(_WIN32)
+#include <unistd.h>
+#endif
+module xlings.core.xself.doctor;
+
+import std;
+import xlings.core.xself.init;
+import xlings.core.xself.compat;
+import xlings.core.config;
+import xlings.core.glyph;
+import xlings.libs.json;
+import xlings.core.log;
+import xlings.platform;
+import xlings.runtime;
+import xlings.core.elf_same_source;
+import xlings.core.entry_binary;
+import xlings.core.version_order;
+import xlings.core.xvm.types;
+import xlings.core.xvm.bindings;
+import xlings.core.xvm.db;
+import xlings.core.xvm.shim;
+import xlings.core.xvm.inspect;
+import xlings.core.xvm.switch_plan;
+import xlings.core.xvm.lock;
+import xlings.core.xvm.owner;
+import xlings.core.xself.repair;
+import xlings.core.xim.catalog;
+import xlings.core.xim.payload;
+import xlings.core.xim.install_state;
+import xlings.core.profile;
+import xlings.core.subos.manifest;
+import xlings.platform.target;
+
+namespace xlings::xself {
+
+#ifdef _WIN32
+
+#else
+
+#endif
+
+std::string shim_filename_(const std::string& name) {
+    std::string fn = name;
+    if (!shim_ext_.empty() && !fn.ends_with(shim_ext_)) fn += shim_ext_;
+    return fn;
+}
+
+DoctorState load_state_() {
+    auto& p = Config::paths();
+    DoctorState st;
+    st.db          = Config::versions();
+    st.ws          = Config::effective_workspace();
+    st.wsInstalled = Config::workspace_installed();
+    st.homeStr     = p.homeDir.string();
+
+    // The other subos of this home.
+    //
+    // Everything doctor checks above the DB layer is scoped to the subos it
+    // runs in -- its binDir, its sysroot, its workspace. The versions DB and
+    // the payload store below are shared by every subos. Identified by
+    // directory, not by name: a project subos may be named the same as one
+    // under the home, and excluding the wrong one would make this subos audit
+    // itself as a foreigner.
+    std::error_code cec;
+    const auto here = fs::weakly_canonical(p.subosDir, cec);
+    for (auto& snapshot : profile::load_subos_snapshots(p.homeDir)) {
+        std::error_code sec;
+        if (fs::weakly_canonical(snapshot.dir, sec) == here) continue;
+        st.otherSubos.push_back(xvm::SubosRef{
+            .subos     = snapshot.name,
+            .active    = snapshot.workspace.active,
+            .installed = snapshot.workspace.installed,
+        });
+        st.otherSnapshots.push_back(std::move(snapshot));
+    }
+
+#ifdef _WIN32
+    st.xlingsBin = p.homeDir / "bin" / "xlings.exe";
+#else
+    st.xlingsBin = p.homeDir / "bin" / "xlings";
+#endif
+    if (!fs::exists(st.xlingsBin)) st.xlingsBin = p.homeDir / "xlings";
+    return st;
+}
+
+// Does this payload ship ANY executable?
+//
+// The discriminator between "a library-only package that xvm typed as a
+// program" and "a program whose binary went missing". `is_binding_root` was
+// doing that job and cannot: it skips the entry itself, so a package that is
+// the sole member of its own release comes back false and gets reported as
+// broken. Reinstalling it can never help, because nothing is wrong.
+//
+// Scanning is confined to the failure path, and shallow: the payload root and
+// bin/, which is where a recipe puts programs.
+bool payload_has_any_executable_(const fs::path& dir) {
+    auto scan = [](const fs::path& d) {
+        std::error_code ec;
+        if (!fs::is_directory(d, ec)) return false;
+        for (auto& e : platform::dir_entries(d)) {
+            std::error_code fec;
+            if (!e.is_regular_file(fec) && !e.is_symlink(fec)) continue;
+#if defined(_WIN32)
+            auto ext = e.path().extension().string();
+            if (ext == ".exe" || ext == ".bat" || ext == ".cmd") return true;
+#else
+            auto st = fs::status(e.path(), fec);
+            if (!fec && (st.permissions() & (fs::perms::owner_exec
+                                             | fs::perms::group_exec
+                                             | fs::perms::others_exec))
+                        != fs::perms::none) {
+                return true;
+            }
+#endif
+        }
+        return false;
+    };
+    return scan(dir) || scan(dir / "bin");
+}
+
+// An alias as the runtime would actually read it.
+//
+// Two things had to be stripped before the "is this an absolute path outside
+// the payload" question could be answered, and neither was:
+//   - surrounding quotes. A recipe that quotes a path containing spaces stores
+//     `"/home/…/claude.exe"`, whose first character is `"`, so is_absolute()
+//     said no and every such entry was reported as an unresolvable alias. Five
+//     of the nine warnings on the measured home were this.
+//   - ${XLINGS_HOME} / @xlings placeholders, which expand to an absolute path
+//     and until then look relative.
+std::string alias_program_(const std::string& aliasCmd,
+                           const std::string& homeStr) {
+    auto sp = aliasCmd.find(' ');
+    std::string prog = (sp == std::string::npos)
+        ? aliasCmd : aliasCmd.substr(0, sp);
+    if (prog.size() >= 2
+        && ((prog.front() == '"'  && prog.back() == '"')
+         || (prog.front() == '\'' && prog.back() == '\''))) {
+        prog = prog.substr(1, prog.size() - 2);
+    }
+    return xvm::expand_path(prog, homeStr);
+}
+
+fs::path audit_payload_dir_(const xim::PackageMatch& match) {
+    return match.storeRoot
+        / xim::package_store_name(match.namespaceName, match.name)
+        / match.version;
+}
+
+// The command that repairs a broken entry, or nothing.
+//
+// A finding names an xvm TARGET; every remedy is a PACKAGE. `xlings install
+// nm@20.1.7` cannot succeed, because no package is called `nm` -- it is a
+// program the llvm package registers. The same goes for `xim-musl-gnu-gcc`
+// (package: `musl-gcc`) and `VBoxHeadless` (package: `virtualbox`). Printing
+// twenty such commands is worse than printing none, because they get run.
+//
+// Candidates come from xvm/owner.cppm in descending order of confidence and
+// each is confirmed against the index before use. Nothing is offered on a
+// guess, and when nothing confirms, the finding says so instead of inventing
+// a command.
+std::optional<xvm::InstallCoordinate>
+owning_coordinate_(const xvm::VersionDB& db,
+                   const std::string& target,
+                   const std::string& version,
+                   const CoordinateProbe& probe) {
+    for (const auto& candidate : xvm::owner_candidates(db, target, version)) {
+        if (probe(candidate)) return candidate;
+    }
+    return std::nullopt;
+}
+
+// Would activating this release be undone by the repair that runs next?
+//
+// `--fix` is a sequence of repairs, and two of them want opposite things. The
+// activation repair makes an unreachable release reachable; the deactivation
+// repair (repair_state_ → plan_incoherent_deactivation) takes down releases
+// whose members disagree about which release they are. Activating a release
+// that shares program names with an ACTIVE one produces exactly that
+// disagreement, so the second repair tears down what the first just built --
+// and the wreckage reads as a fresh crop of "installed but inactive" entries,
+// which the next run tries to activate again. Measured on 2026.8.1.1: `--fix`
+// ended with more issues than it started with and left `gcc` and `ld` with no
+// active version at all.
+//
+// The answer does not need new machinery. Both halves already exist and are
+// exported: `plan_use_switch` computes the member map activation would write,
+// and `plan_incoherent_deactivation` IS the teardown. So the question is
+// answered by asking the second repair about the first repair's result --
+// simulate, then consult. Detection calls the function the repair calls, the
+// same rule the baked-subos-path check follows, so the two cannot drift.
+//
+// Returns the reason to refuse, or empty when the activation is safe.
+std::string activation_conflict_(const DoctorState& st,
+                                 const std::string& rootTarget,
+                                 const std::string& rootVersion) {
+    auto plan = xvm::plan_use_switch(st.db, st.ws, rootTarget, rootVersion);
+    if (!plan) {
+        // Unresolvable release: `use` would fail too. Refusing here means the
+        // user gets the finding and the command, rather than `--fix` running
+        // something that cannot work.
+        return "the release does not resolve";
+    }
+
+    auto simulated = st.ws;
+    for (const auto& [target, version] : plan->members) {
+        simulated[target] = version;
+    }
+
+    const auto teardown = xvm::plan_incoherent_deactivation(st.db, simulated);
+    if (teardown.targets.empty()) return {};
+
+    // Name the releases that would come down and a few of the programs they
+    // would take with them -- "there is a conflict" is not actionable, "this
+    // takes `ar` away from llvm" is.
+    std::map<std::string, std::vector<std::string>> byRelease;
+    for (const auto& [target, label] : teardown.targets) {
+        byRelease[label].push_back(target);
+    }
+    std::string reason;
+    for (auto& [label, targets] : byRelease) {
+        std::ranges::sort(targets);
+        std::string names;
+        constexpr std::size_t kShown = 4;
+        for (std::size_t i = 0; i < targets.size() && i < kShown; ++i) {
+            if (!names.empty()) names += ", ";
+            names += targets[i];
+        }
+        if (targets.size() > kShown) {
+            names += std::format(", … (+{})", targets.size() - kShown);
+        }
+        if (!reason.empty()) reason += "; ";
+        reason += std::format("it would take {} from the active {}", names,
+                              label);
+    }
+    return reason;
+}
+
+// D1–D5 over the active subos's `subos_info`.
+//
+// One function, called by detection and again by the repair pass. The repair
+// acts on what this returns rather than on its own reading of the rules --
+// a reporter and a repairer that each describe the criteria end up describing
+// them differently, and then fight.
+//
+// Nothing here needs XVM state except D2 and D5, which take the database and
+// already-parsed active workspace as arguments, so the manifest leaf itself
+// stays independent of VersionDB.
+std::vector<Finding> detect_subos_manifest_(const xvm::VersionDB& db,
+                                            const xvm::Workspace& workspace,
+                                            const fs::path& subosDir,
+                                            const std::string& subosName) {
+    namespace mf = xlings::subos::manifest;
+    std::vector<Finding> out;
+
+    // D1 — structure. Anything wrong here makes the rest unreadable, so it is
+    // the only finding produced when it fires.
+    if (auto structural = mf::validate(subosDir); !structural.empty()) {
+        std::string detail;
+        for (const auto& f : structural) {
+            if (!detail.empty()) detail += "; ";
+            detail += std::string(mf::describe(f.kind));
+            if (!f.detail.empty()) detail += " (" + f.detail + ")";
+        }
+        const bool unreadable = std::ranges::any_of(
+            structural, [](const auto& f) {
+                return f.kind == mf::Defect::ConfigUnreadable;
+            });
+        out.push_back({
+            .kind    = FindingKind::SubosManifest,
+            .level   = FindingLevel::Error,
+            .target  = subosName,
+            .detail  = detail,
+            // An unreadable file is not repaired: rewriting it would discard a
+            // workspace no one has managed to parse. Everything else is a
+            // missing or unusable block, which `--fix` can add.
+            .remedy  = unreadable
+                ? std::format("inspect {}",
+                              Config::display_path(mf::config_path(subosDir)))
+                : "xlings self doctor --fix",
+        });
+        return out;
+    }
+
+    auto doc = mf::read_document(subosDir);
+    if (!doc) return out;                      // D1 already covered this
+    const auto info = mf::parse(*doc);
+
+    const auto installed = [&](std::string_view binding) {
+        const auto at = binding.find('@');
+        if (at == std::string_view::npos) return false;
+        const std::string name(binding.substr(0, at));
+        const std::string version(binding.substr(at + 1));
+        const auto* vi = xvm::get_vinfo(db, name);
+        if (!vi) return false;
+        // Namespaced installs record `<ns>:<version>`, so a bare match is not
+        // enough -- compare the version tail.
+        return std::ranges::any_of(vi->versions, [&](const auto& entry) {
+            const auto& key = entry.first;
+            if (key == version) return true;
+            const auto colon = key.find(':');
+            return colon != std::string::npos && key.substr(colon + 1) == version;
+        });
+    };
+
+    // D2 — an envs section whose owner is not installed here.
+    for (const auto& provider : info.envs) {
+        if (installed(provider.binding)) continue;
+        out.push_back({
+            .kind    = FindingKind::SubosEnvOrphan,
+            .level   = FindingLevel::Error,
+            .target  = subosName,
+            .version = provider.binding,
+            .detail  = std::format(
+                "subos '{}' exports {} variable(s) for '{}', which is not "
+                "installed here", subosName, provider.decls.size(),
+                provider.binding),
+            .remedy  = "xlings self doctor --fix",
+        });
+    }
+
+    // D3/D4 — over the resolved set, so both see exactly what activation will.
+    //
+    // select_effective first, for the same reason: a dormant provider (a second
+    // version whose sibling is the active one) contributes nothing, so
+    // reporting that it "would export an unexpanded path" describes an export
+    // that will not happen. D2 above deliberately stays over the FULL set --
+    // "recorded here but not installed here" is true of a dormant section too.
+    const auto effective = mf::select_effective(info, mf::active_versions(*doc));
+    const auto resolved = mf::resolve(effective, mf::Placeholders{
+        .subosdir    = subosDir,
+        .home        = platform::get_home_dir(),
+        .xlings_home = Config::paths().homeDir,
+        .pkgdir_of   = [](std::string_view binding) -> fs::path {
+            const auto at = binding.find('@');
+            if (at == std::string_view::npos) return {};
+            const std::string name(binding.substr(0, at));
+            const std::string version(binding.substr(at + 1));
+            const auto store = Config::paths().dataDir / "xpkgs";
+            std::error_code ec;
+            if (auto direct = store / name / version;
+                fs::is_directory(direct, ec)) {
+                return direct;
+            }
+            if (!fs::is_directory(store, ec)) return {};
+            const auto suffix = "-x-" + name;
+            for (const auto& entry : platform::dir_entries(store)) {
+                if (!entry.is_directory(ec)) continue;
+                if (!entry.path().filename().string().ends_with(suffix)) continue;
+                if (auto candidate = entry.path() / version;
+                    fs::is_directory(candidate, ec)) {
+                    return candidate;
+                }
+            }
+            return {};
+        },
+    });
+
+    for (const auto& v : resolved) {
+        if (v.unresolved) {
+            out.push_back({
+                .kind    = FindingKind::SubosEnvUnresolved,
+                .level   = FindingLevel::Error,
+                .target  = subosName,
+                .version = v.var,
+                .detail  = std::format(
+                    "{} would export an unexpanded path; its provider's "
+                    "payload is missing", v.var),
+                // Reinstalling the provider is what puts the payload back.
+                // Only one is named even when several declared the variable:
+                // a remedy the user can paste beats an exhaustive one.
+                .remedy  = v.providers.empty() ? std::string{}
+                    : std::format("xlings install {}", v.providers.front()),
+            });
+        }
+        if (v.conflicted) {
+            std::string names;
+            for (const auto& b : v.providers) {
+                if (!names.empty()) names += ", ";
+                names += b;
+            }
+            out.push_back({
+                .kind    = FindingKind::SubosEnvConflict,
+                // A warning, not an error: resolution is deterministic and the
+                // subos works. What is wrong is that one of these packages is
+                // silently not getting what it asked for.
+                .level   = FindingLevel::Warning,
+                .target  = subosName,
+                .version = v.var,
+                .detail  = std::format("{} is claimed by {}", v.var, names),
+            });
+        }
+    }
+
+    // D6 — a package bound at several versions with nothing able to say which.
+    //
+    // Not every duplicate: two versions where one is active is ordinary, and
+    // the dormant section is exactly what lets `xlings use pkg@<older>` restore
+    // an environment without reinstalling. Activation already drops it
+    // (manifest::select_effective).
+    //
+    // What is reportable is the subset with NO active version -- `xvm.add(name)`
+    // with no version registers a root without one, which is what mesa,
+    // libglvnd and nvidia-gl-host-link do. For those every provider
+    // contributes, so a second version really does export every variable twice.
+    // That is the state that enumerated one GPU as two.
+    //
+    // The predicate is mf::contested_bindings, and --fix calls that same
+    // function rather than an equivalent one written here. Three report/repair
+    // pairs in this repo have drifted, each showing up as a finding that
+    // repairing does not clear.
+    const auto activeInSubos = mf::active_versions(*doc);
+    for (const auto& dup : mf::contested_bindings(info, activeInSubos)) {
+        std::string names;
+        for (const auto& b : dup.bindings) {
+            if (!names.empty()) names += ", ";
+            names += b;
+        }
+        out.push_back({
+            .kind    = FindingKind::SubosDoubleBinding,
+            // Error: the observable effect -- a device enumerated twice, a
+            // search path with two of everything -- is a wrong result, not a
+            // cosmetic one.
+            .level   = FindingLevel::Error,
+            .target  = subosName,
+            .version = dup.name,
+            .detail  = std::format(
+                "'{}' is bound {} times in subos '{}' ({}) and has no active "
+                "version, so every one of them contributes",
+                dup.name, dup.bindings.size(), subosName, names),
+            // Naming the versions in the remedy: the user is otherwise left
+            // choosing between two strings with nothing to tell them apart.
+            .remedy  = std::format("xlings use {}@<one of: {}>", dup.name, [&] {
+                std::string vs;
+                for (const auto& b : dup.bindings) {
+                    if (!vs.empty()) vs += ", ";
+                    vs += std::string(mf::binding_version(b));
+                }
+                return vs;
+            }()),
+        });
+    }
+
+    // D5 — the manifest and this SubOS's active XVM runtime must agree
+    // exactly. Finding the declared version elsewhere in the global DB is not
+    // enough: many payload versions coexist globally by design, while one
+    // SubOS has one active core runtime.
+    const auto runtimePayloadExists = [&](std::string_view binding) {
+        if (!mf::is_binding(binding)) return false;
+        const std::string name(mf::binding_name(binding));
+        const auto wanted = mf::binding_version(binding);
+        const auto* vi = xvm::get_vinfo(db, name);
+        if (!vi) return false;
+        for (const auto& [version, data] : vi->versions) {
+            if (!mf::version_is_active(wanted, version) || data.path.empty()) {
+                continue;
+            }
+            std::error_code ec;
+            const auto expanded = xvm::expand_path(
+                data.path, Config::paths().homeDir.string());
+            if (fs::exists(expanded, ec) && !ec) return true;
+        }
+        return false;
+    };
+
+    if (mf::is_binding(info.runtime)) {
+        const auto runtimeName = std::string(mf::binding_name(info.runtime));
+        const auto activeIt = workspace.find(runtimeName);
+        const std::string activeVersion = activeIt == workspace.end()
+            ? std::string{} : activeIt->second;
+        const auto mismatch = mf::check_runtime_activation(
+            info, activeVersion, runtimePayloadExists(info.runtime));
+        if (!mismatch) return out;
+
+        // A cold default SubOS records its runtime authority before that
+        // payload is materialized, while `self install` intentionally stays
+        // lightweight and does not download it. There is no split state until an
+        // active runtime exists. Keep the declaration visible as a warning;
+        // an active mismatch or an active runtime whose payload disappeared
+        // remains an error.
+        const bool unmaterializedDeclaration =
+            activeVersion.empty() && mismatch->payloadMissing;
+
+        const auto active = mismatch->active.empty()
+            ? std::string("<none>") : mismatch->active;
+        std::string detail = std::format(
+            "subos '{}' declares runtime {}, but its active XVM runtime is {}",
+            subosName, mismatch->declared, active);
+        if (mismatch->payloadMissing) {
+            detail += std::format("; declared runtime payload {} is missing",
+                                  mismatch->declared);
+        }
+
+        // Two ways out, and "create a new SubOS" is neither of them.
+        //
+        //   adopt   -- record what this subos is actually running. `--fix`
+        //              does this, and it is what a home upgraded from before
+        //              `subos_info` existed needs: the declaration was written
+        //              by the upgrade, not chosen by anyone.
+        //   migrate -- install the declared runtime and activate it. That path
+        //              already works, because activating the DECLARED version
+        //              is exactly what the use guard permits.
+        //
+        // Naming only "create a new SubOS" made this a dead end it never was.
+        const bool differentActive = !mismatch->active.empty()
+            && mismatch->active != mismatch->declared;
+        if (differentActive) {
+            detail += std::format(
+                "; nothing here was ever activated against {}",
+                mismatch->declared);
+        }
+        out.push_back({
+            .kind    = FindingKind::SubosRuntimeMissing,
+            .level   = unmaterializedDeclaration
+                ? FindingLevel::Warning : FindingLevel::Error,
+            .target  = subosName,
+            .version = mismatch->declared,
+            .detail  = std::move(detail),
+            .remedy  = differentActive
+                ? std::format(
+                    "xlings self doctor --fix   (adopt {}; or migrate with "
+                    "`xlings install {}` then `xlings use {} {}`)",
+                    mismatch->active, mismatch->declared,
+                    mf::binding_name(mismatch->declared),
+                    mf::binding_version(mismatch->declared))
+                : std::format("xlings install {}", mismatch->declared),
+        });
+    }
+    return out;
+}
+
+// Is the file every shim dispatches through the xlings this home says it runs?
+//
+// TWO SHAPES, ONE FINDING. Reported separately because the user's next move
+// differs, and because each is evidence the other cannot supply:
+//
+//   * the active binding names a version, the FILE reports another. Provable
+//     divergence -- the writer is `use`/`install` of the xlings package, so
+//     the only ways to reach this state are a hand-copied binary or a failed
+//     replacement. Live on a real home while this was written: the binding
+//     said `local:0.4.51` and the file was 2026.8.11.1.
+//   * the file is behind a version this home already has on disk. Directional
+//     on purpose -- "not equal" would fire on every deliberately pinned entry,
+//     and the half that bites is only ever "the entry is older".
+//
+// The version comes from RUNNING the binary (entry_binary::version_of), not
+// from a record. Checking a record against another record is what let the
+// original divergence stand: `.xlings.json` and the versions DB agreed with
+// each other and neither described the file. ~60ms, measured, once per run.
+//
+// An unreadable entry produces NOTHING. No observation is not a verdict --
+// the same rule `registered`/`kRegisteredUnrecorded` follows one module over.
+std::vector<Finding> detect_entry_binary_(const DoctorState& st) {
+    std::vector<Finding> out;
+    auto& p = Config::paths();
+
+    const auto entry = entry_binary::path_of(p.homeDir);
+    const auto actual = entry_binary::version_of(entry);
+    if (actual.empty()) return out;   // absent, or would not answer
+
+    // What the home says is active for the `xlings` program, in this subos.
+    if (auto it = st.ws.find("xlings");
+        it != st.ws.end() && !it->second.empty()) {
+        // The binding may be namespace-qualified (`local:0.4.51`); compare on
+        // the version alone, since the file cannot report a namespace.
+        std::string boundVersion = it->second;
+        if (auto colon = boundVersion.rfind(':'); colon != std::string::npos) {
+            boundVersion = boundVersion.substr(colon + 1);
+        }
+        // A binding that is not a version at all -- a sentinel like `latest`,
+        // or anything a future client writes -- is NO OBSERVATION, not a
+        // mismatch. Comparing it against the file would report drift on every
+        // home that spells its binding that way. Same first-digit rule
+        // entry_binary::version_of applies to the binary's own answer, so the
+        // two sides of the comparison are qualified identically.
+        const bool boundIsAVersion =
+            !boundVersion.empty()
+            && std::isdigit(static_cast<unsigned char>(boundVersion[0]));
+        if (boundIsAVersion && boundVersion != actual) {
+            // Reconcile toward the NEWER of the two, whichever side it is on.
+            //
+            // The obvious remedy -- "make the file match the binding" -- is
+            // actively harmful in the case that produced this check: the
+            // binding was a June `local:` build and the file was current, so
+            // that command would have recreated the outage it is meant to
+            // report. `use` rewrites the entry either way, so choosing the
+            // newer side re-aligns the binding at no cost when the file is
+            // ahead, and upgrades the file when the binding is ahead.
+            const bool bindingIsNewer =
+                version_order::compare(boundVersion, actual) > 0;
+            const auto toward = bindingIsNewer ? it->second : actual;
+            out.push_back({
+                .kind    = FindingKind::EntryBinaryDrift,
+                .level   = FindingLevel::Notice,
+                .target  = "xlings",
+                .version = actual,
+                .detail  = std::format(
+                    "bin/xlings reports {}, but this subos has {} active -- "
+                    "every shim in the home dispatches through the file, not "
+                    "the binding",
+                    actual, it->second),
+                .remedy  = std::format("xlings use xlings {}", toward),
+            });
+        }
+    }
+
+    // Something newer sitting in the store. Payload dirs, not the versions DB:
+    // the question is what this home COULD dispatch through, and a payload
+    // with a binary in it is the direct evidence of that.
+    std::string newest;
+    std::string newestCoordinate;
+    const auto xpkgs = Config::global_data_dir() / "xpkgs";
+    std::error_code ec;
+    if (fs::is_directory(xpkgs, ec)) {
+        for (const auto& pkgDir : platform::dir_entries(xpkgs)) {
+            if (!pkgDir.is_directory()) continue;
+            const auto storeName = pkgDir.path().filename().string();
+            const auto sep = storeName.find("-x-");
+            const auto name = sep == std::string::npos
+                ? storeName : storeName.substr(sep + 3);
+            if (name != "xlings") continue;
+            const auto ns = sep == std::string::npos
+                ? std::string{} : storeName.substr(0, sep);
+            for (const auto& verDir : platform::dir_entries(pkgDir.path())) {
+                if (!verDir.is_directory()) continue;
+                const auto version = verDir.path().filename().string();
+                // Positive evidence only: a payload that failed to install is
+                // not something this home can dispatch through.
+                if (xim::stamped_incomplete(verDir.path())) continue;
+                if (!fs::exists(verDir.path() / "bin"
+                                / shim_filename_("xlings"), ec)) continue;
+                // A payload built for another platform cannot become this
+                // home's entry, and the remedy this finding prints would fail
+                // against it. Only a PROVABLE mismatch is excluded -- Unknown
+                // stays eligible, the same rule PackageMatch::payloadForeign
+                // follows.
+                if (xim::classify_payload_platform(verDir.path())
+                        == xim::PayloadPlatform::Foreign) continue;
+                if (version_order::compare(version, actual) <= 0) continue;
+                if (!newest.empty()
+                    && version_order::compare(version, newest) <= 0) continue;
+                newest = version;
+                newestCoordinate = ns.empty()
+                    ? std::format("xlings@{}", version)
+                    : std::format("{}:xlings@{}", ns, version);
+            }
+        }
+    }
+    if (!newest.empty()) {
+        out.push_back({
+            .kind    = FindingKind::EntryBinaryDrift,
+            .level   = FindingLevel::Notice,
+            .target  = "xlings",
+            .version = actual,
+            .detail  = std::format(
+                "bin/xlings is {}, and {} is already installed here -- an "
+                "older entry may not expand records a newer index wrote",
+                actual, newestCoordinate),
+            .remedy  = std::format("xlings use xlings {}", newest),
+        });
+    }
+    return out;
+}
+
+Scan detect_(const DoctorState& st, const CoordinateProbe& probe,
+             const AuditSelection& audit) {
+    auto& p = Config::paths();
+    Scan scan;
+    const auto add = [&](Finding f) { scan.findings.push_back(std::move(f)); };
+
+    // The subos this run is actually in. Other subos are not inspected from
+    // here for the same reason their payloads are not repaired: a second
+    // shell may be inside one right now.
+    for (auto&& f : detect_subos_manifest_(st.db, st.ws, p.subosDir,
+                                           p.activeSubos.empty() ? "default"
+                                                                 : p.activeSubos)) {
+        add(std::move(f));
+    }
+
+    for (auto&& f : detect_entry_binary_(st)) add(std::move(f));
+
+    // The PATH an aliased command would inherit. Read once, and read from
+    // THIS process: doctor is normally started from the user's shell, so this
+    // is the same PATH the shim would get. It is not guaranteed to be -- a
+    // stripped environment sees fewer host commands than the user does -- so
+    // it can only ever downgrade a finding from "satisfied by the host" to
+    // "resolves to nothing", never the reverse. That direction is the safe
+    // one to be wrong in: it over-reports in a sandbox instead of staying
+    // silent on a real break.
+    const std::string hostPath =
+        std::getenv("PATH") ? std::getenv("PATH") : std::string{};
+
+    // Check 1: every workspace program has its shim.
+    for (const auto& [name, version] : st.ws) {
+        if (version.empty()) continue;
+        const auto* vi = xvm::get_vinfo(st.db, name);
+        if (!vi || xvm::effective_kind_of(st.db, name, version) != "program")
+            continue;
+
+        auto shimPath = p.binDir / shim_filename_(name);
+        if (fs::exists(shimPath) || fs::is_symlink(shimPath)) continue;
+        add({
+            .kind    = FindingKind::MissingShim,
+            .level   = FindingLevel::Error,
+            .target  = name,
+            .version = version,
+            .detail  = std::format("workspace[{}]={} but {} missing",
+                                   name, version,
+                                   Config::display_path(shimPath)),
+            .shimPath = shimPath,
+        });
+    }
+
+    // Does this name exist only to anchor releases? Check 3 asks the same
+    // question per (name, version) and answers it with a `release anchor`
+    // notice; Check 2 has no version to ask about -- nothing is active, that
+    // is the finding -- so it asks about every registered version instead.
+    //
+    // All of them, not any: a name with one real program version and one
+    // anchor version is a program whose shim genuinely has no active version.
+    const auto anchor_only_target_ = [&](const std::string& name,
+                                         const xvm::VInfo& vi) {
+        if (vi.versions.empty()) return false;
+        return std::ranges::all_of(
+            vi.versions, [&](const auto& entry) {
+                return xvm::is_binding_root(st.db, name, entry.first);
+            });
+    };
+
+    // Check 2: orphan shims (program shim file present, workspace doesn't know
+    // about it). Only names registered as type "program" count -- random files
+    // under binDir aren't ours.
+    if (fs::exists(p.binDir)) {
+        for (auto& entry : platform::dir_entries(p.binDir)) {
+            std::error_code ec;
+            if (!entry.is_regular_file(ec) && !entry.is_symlink(ec)) continue;
+            auto fname = entry.path().filename().string();
+            std::string base = fname;
+            if (!shim_ext_.empty() && base.ends_with(shim_ext_)) {
+                base = base.substr(0, base.size() - shim_ext_.size());
+            }
+            // Only a shim file name is in hand here, so the question is
+            // widened to "any version of this name is a program".
+            const auto* vi = xvm::get_vinfo(st.db, base);
+            if (!vi || !xvm::has_program_kind(st.db, base)) continue;
+
+            auto wit = st.ws.find(base);
+            if (wit != st.ws.end() && !wit->second.empty()) continue;
+
+            // A binding root is not a program anyone runs -- it names the
+            // release its members belong to. Installs before 2026.7.29.2
+            // wrote a shim for one whenever registration withheld activation
+            // from the release (installer.cppm, the ProgramShim effect), so
+            // this file is on existing homes through no act of the user's.
+            // `--fix` still removes it; it is no longer an error that it is
+            // there.
+            const bool anchor = anchor_only_target_(base, *vi);
+            add({
+                .kind   = FindingKind::OrphanShim,
+                .level  = anchor ? FindingLevel::Notice : FindingLevel::Error,
+                .target = base,
+                .detail = anchor
+                    ? std::format(
+                        "{} anchors a release and has no active version; "
+                        "nothing dispatches through it",
+                        Config::display_path(entry.path()))
+                    : std::format(
+                        "{} exists but workspace has no active version for {}",
+                        Config::display_path(entry.path()), base),
+                .shimPath = entry.path(),
+            });
+        }
+    }
+
+    // COMPAT(0.4.8 → drop in 0.6.0): Check 2.5 — legacy alias shims
+    // (xim/xvm/xself/xsubos/xinstall). Names + predicate are owned by
+    // xself::compat. When the compat module is removed, delete this block.
+    if (fs::exists(p.binDir)) {
+        std::error_code bec;
+        auto canonicalBootstrap = fs::weakly_canonical(st.xlingsBin, bec);
+        for (auto alias : compat::v0_4_8::LEGACY_ALIAS_NAMES) {
+            auto path = p.binDir / shim_filename_(std::string(alias));
+            if (!compat::v0_4_8::is_legacy_alias_symlink_to_bootstrap(
+                    path, canonicalBootstrap)) continue;
+            add({
+                .kind   = FindingKind::LegacyAliasShim,
+                .level  = FindingLevel::Error,
+                .target = std::string(alias),
+                .detail = std::format(
+                    "{} is a leftover symlink from older xlings (alias `{}` "
+                    "removed in 0.4.8)",
+                    Config::display_path(path), alias),
+                .shimPath = path,
+            });
+        }
+    }
+
+    // Check 2.7: installed here, and nothing active.
+    //
+    // The gap between Check 1 and Check 2. Check 1 asks "does every ACTIVE
+    // program have a shim" and never sees a name with no active version;
+    // Check 2 asks "does every shim have an active version" and never sees a
+    // name with no shim. A package that is installed and inactive is missing
+    // from both tables at once, so both loops skip it and the payload loop
+    // below finds it perfectly healthy -- which it is. What is broken is the
+    // selection, and until now nothing looked at the selection.
+    //
+    // Reported per RELEASE, not per program.
+    //
+    // Activation is a release-level act -- `use` moves a whole binding group
+    // at once -- so one inactive release is one problem no matter how many
+    // names it registers. On the measured home the per-program shape printed
+    // fifty lines for three releases: `clang`, `clang++`, `clang-22`,
+    // `llvm-ar` … each with its own identical remedy. That is the same burial
+    // the broken-payload grouping exists to prevent (see Finding::groupKey),
+    // and it would have hidden `node` in the middle of it.
+    // Keyed by ROOT TARGET, not by (root, version).
+    //
+    // F3: a package can have several installed releases with none of them
+    // active, and keying by version produced one finding per release, each
+    // with a remedy contradicting the others -- `xim-gnu-gcc@15.1.0` and
+    // `@16.1.0` side by side, both saying "run me". There is one problem here
+    // ("nothing of this package is selected") and one decision to make, so
+    // there is one finding, and it names the versions to choose from.
+    struct InactiveRelease {
+        std::string rootTarget;
+        std::string rootVersion;   // the one the remedy proposes
+        std::set<std::string> members;
+    };
+    std::map<std::string, InactiveRelease> inactiveReleases;
+
+    for (const auto& [name, versions] : st.wsInstalled) {
+        if (versions.empty()) continue;
+        if (auto wit = st.ws.find(name);
+            wit != st.ws.end() && !wit->second.empty()) continue;
+
+        const auto* vi = xvm::get_vinfo(st.db, name);
+        if (!vi || !xvm::has_program_kind(st.db, name)) continue;
+
+        // Only versions this subos actually has, highest first: the same
+        // ordering removal.cppm:390-393 uses to pick a replacement release,
+        // so doctor's remedy and remove's automatic choice cannot disagree.
+        std::vector<std::string> candidates;
+        for (const auto& version : versions) {
+            if (!vi->versions.contains(version)) continue;
+            if (xvm::effective_kind_of(st.db, name, version) != "program")
+                continue;
+            candidates.push_back(version);
+        }
+        if (candidates.empty()) continue;
+        std::ranges::sort(candidates, xvm::version_key_greater);
+
+        // Would activating it actually produce a working command?
+        //
+        // This is the whole filter, and `is_binding_root` deliberately is not
+        // part of it. A name that exists only to anchor a release has no
+        // executable and drops out here -- activating one is issue #452 in the
+        // other direction, where the shim can only ever print "no active
+        // version". But asking `is_binding_root` first would have thrown out
+        // the real cases too: a group's root is usually its main program.
+        // `node` roots the release that owns `npm` and `npx`, so it answers
+        // true to that question while being exactly the program the user is
+        // missing. Only the payload can tell the two apart, so only the
+        // payload is asked -- the same order Check 3 uses.
+        //
+        // A version whose payload is gone is skipped as well: Check 3 already
+        // reports that as a broken payload with an install remedy, and
+        // offering `xlings use` on top of it would name a command that cannot
+        // succeed.
+        const auto usable = std::ranges::find_if(
+            candidates, [&](const std::string& version) {
+                const auto* vd = xvm::get_vdata(st.db, name, version);
+                if (!vd || vd->path.empty()) return false;
+                if (!vd->alias.empty() && !vd->alias[0].empty()) return true;
+                return !xvm::resolve_executable(name, vd->path, st.homeStr)
+                            .empty();
+            });
+        if (usable == candidates.end()) continue;
+
+        // The release this program belongs to, which is what `use` takes as
+        // an argument. A legacy entry carries no group and is its own root --
+        // that is not a fallback, it is what a single-program package is.
+        const auto* vd = xvm::get_vdata(st.db, name, *usable);
+        const std::string rootTarget =
+            vd && vd->bindingGroup ? vd->bindingGroup->rootTarget : name;
+        const std::string rootVersion =
+            vd && vd->bindingGroup ? vd->bindingGroup->rootVersion : *usable;
+
+        // Both guards run BEFORE the map is touched: `operator[]` would insert
+        // a default-constructed release and the `continue` would leave it
+        // there, which renders as a finding with an empty name and zero
+        // programs.
+        //
+        // F1 — is this release the one you did not pick, rather than one you
+        // cannot reach?
+        //
+        // `llvm` installed at 20.1.7 and 22.1.8, active at 22.1.8, is a normal
+        // home. But 20.1.7 registers names 22.1.8 does not, and those names
+        // have no active version, so the release came back as a finding whose
+        // remedy -- `xlings use llvm@20.1.7` -- would DOWNGRADE the toolchain
+        // the user is actually using. Two releases of one package were
+        // reported as two mutually contradictory defects.
+        //
+        // The root target answers it. If some version of the root is active,
+        // the user has chosen a release of this package and the others are
+        // alternatives, not breakage. When no version of the root is active,
+        // nothing of the package is reachable -- which is exactly the `node`
+        // case this check was written for.
+        if (const auto rootIt = st.ws.find(rootTarget);
+            rootIt != st.ws.end() && !rootIt->second.empty()) {
+            continue;
+        }
+
+        // F2 — a payload built for another platform has no programs to put on
+        // PATH here, ever.
+        //
+        // The measured home carried a May-era WINDOWS llvm@20.1.7 in a Linux
+        // store; it registered `clang.exe` … `libomp.dll` as programs (the
+        // case payload.cppm's header documents), and this check dutifully
+        // reported 29 of them as "not on PATH". They cannot be. The classifier
+        // that answers this already exists and the installer already uses it
+        // (installer.cppm) -- this check simply never asked.
+        if (vd && !vd->path.empty()
+            && xim::classify_payload_platform(
+                   fs::path(xvm::expand_path(vd->path, st.homeStr)))
+                   == xim::PayloadPlatform::Foreign) {
+            continue;
+        }
+
+        auto& release = inactiveReleases[rootTarget];
+        release.rootTarget = rootTarget;
+        // Highest wins the remedy, by version rather than by iteration order.
+        if (release.rootVersion.empty()
+            || xvm::version_key_greater(rootVersion, release.rootVersion)) {
+            release.rootVersion = rootVersion;
+        }
+        release.members.insert(name);
+    }
+
+    for (const auto& [key, release] : inactiveReleases) {
+        // Names, not a count. "30 programs" tells the user nothing they can
+        // check; `clang, clang++, ld.lld …` is how they recognise what they
+        // have been missing. The list is capped because a release with thirty
+        // members would otherwise take the terminal apart -- `--all` prints it
+        // whole.
+        constexpr std::size_t kShown = 6;
+        std::string names;
+        std::size_t shown = 0;
+        for (const auto& member : release.members) {
+            if (shown++ >= kShown) break;
+            if (!names.empty()) names += ", ";
+            names += member;
+        }
+        if (release.members.size() > kShown) {
+            names += std::format(", … (+{})", release.members.size() - kShown);
+        }
+
+        // When several releases are installed and none chosen, the versions
+        // ARE the decision. Naming only the one the remedy proposes would hide
+        // that there was a choice.
+        //
+        // Read from installed[], not from the versions the members happened to
+        // resolve to: every member picks the same highest release, so
+        // accumulating those yields one version and the choice stays invisible
+        // -- which is what it did until this was measured.
+        std::string otherVersions;
+        if (const auto rootInstalled = st.wsInstalled.find(release.rootTarget);
+            rootInstalled != st.wsInstalled.end()) {
+            std::vector<std::string> others;
+            for (const auto& version : rootInstalled->second) {
+                if (version == release.rootVersion) continue;
+                others.push_back(version);
+            }
+            std::ranges::sort(others, xvm::version_key_greater);
+            for (const auto& version : others) {
+                if (!otherVersions.empty()) otherVersions += ", ";
+                otherVersions += version;
+            }
+            if (!otherVersions.empty()) {
+                otherVersions = std::format("  —  also installed: {}",
+                                            otherVersions);
+            }
+        }
+
+        // What the repair will ALSO do.
+        //
+        // The remedy is `use`, and `use` moves a whole release. A name that
+        // another package currently owns -- node's release registers `npm`,
+        // and a standalone npm package may hold it -- changes hands when the
+        // release is activated. That is correct for `use` and it is what the
+        // user gets whether they run the command themselves or let `--fix`
+        // run it, but it must not be something they discover afterwards:
+        // finding out later that a selection moved is the same silent-change
+        // shape this whole check exists to end.
+        std::string alsoMoves;
+        if (const auto selection = xvm::resolve_binding_selection(
+                st.db, release.rootTarget, release.rootVersion)) {
+            for (const auto& [memberTarget, memberVersion]
+                     : selection->members) {
+                const auto activeIt = st.ws.find(memberTarget);
+                if (activeIt == st.ws.end() || activeIt->second.empty()) continue;
+                if (activeIt->second == memberVersion) continue;
+                if (!alsoMoves.empty()) alsoMoves += ", ";
+                alsoMoves += std::format("{} ({} → {})", memberTarget,
+                                         activeIt->second, memberVersion);
+            }
+        }
+
+        add({
+            .kind    = FindingKind::InactiveInstalled,
+            .level   = FindingLevel::Error,
+            .target  = release.rootTarget,
+            .version = release.rootVersion,
+            .detail  = std::format(
+                "{} is installed in this subos but no version is active, so no "
+                "shim was written and {} program(s) are not on PATH: {}{}",
+                xvm::display_coordinate(release.rootTarget,
+                                        release.rootVersion),
+                release.members.size(), names,
+                otherVersions
+                    + (alsoMoves.empty()
+                           ? std::string{}
+                           : std::format(
+                                 "  —  activating it also moves {}",
+                                 alsoMoves))),
+            .remedy  = std::format("xlings use {}@{}", release.rootTarget,
+                                   release.rootVersion),
+            .conflict = activation_conflict_(st, release.rootTarget,
+                                             release.rootVersion),
+            .groupKey = key,
+        });
+    }
+
+    // Check 2.6: shim ownership anchoring (0.4.48). Warning-only: the usual
+    // cause is a hand-copied shim file or a damaged home layout, and the right
+    // fix depends on which it is. Scoped to bin dirs physically inside the
+    // home -- a project subos binDir lives in the project tree, where shims
+    // intentionally anchor to the global home.
+    // See .agents/docs/2026-06-04-shim-owner-anchoring-design.md.
+    std::error_code relEc;
+    auto binRel = fs::relative(p.binDir, p.homeDir, relEc);
+    const bool binDirInsideHome = !relEc && !binRel.empty()
+        && binRel.string().rfind("..", 0) != 0;
+    if (binDirInsideHome && fs::exists(p.binDir)) {
+        std::error_code hec;
+        auto homeCanon = fs::weakly_canonical(p.homeDir, hec);
+        for (auto& entry : platform::dir_entries(p.binDir)) {
+            std::error_code ec;
+            if (!entry.is_regular_file(ec) && !entry.is_symlink(ec)) continue;
+            auto fname = entry.path().filename().string();
+            std::string base = fname;
+            if (!shim_ext_.empty() && base.ends_with(shim_ext_)) {
+                base = base.substr(0, base.size() - shim_ext_.size());
+            }
+            if (xvm::is_xlings_binary(base)) continue;
+            if (!xvm::has_program_kind(st.db, base)) continue;
+
+            auto owner = xvm::resolve_owner_home(entry.path());
+            std::error_code oec;
+            if (owner && fs::weakly_canonical(*owner, oec) == homeCanon) {
+                continue;
+            }
+            add({
+                .kind   = FindingKind::ShimAnchor,
+                .level  = FindingLevel::Warning,
+                .target = base,
+                .detail = std::format(
+                    "{} anchors to {} (expected this home); it will dispatch "
+                    "against that home's versions DB",
+                    Config::display_path(entry.path()),
+                    owner ? Config::display_path(*owner)
+                          : std::string("no home (orphan)")),
+            });
+        }
+    }
+
+    // Check 3: payload existence + executability for every (name, version) in
+    // the versions DB. Reuses the same `resolve_executable` helper that
+    // shim_dispatch uses at runtime, so doctor's verdict matches what the user
+    // will actually experience when they invoke the shim.
+    //
+    // Scope: ALL versions (active + inactive) — heads-up before users
+    // `xlings use` an inactive version that's already broken.
+    const auto reportBrokenPayload =
+        [&](const std::string& name, const std::string& version,
+            const fs::path& expanded, std::string detail) {
+        // Whose entry is this? The finding is home-wide -- the loop walks the
+        // shared DB -- but the repair is not: `xlings install` re-runs
+        // config(), and config() registers into whichever subos is current.
+        //
+        // Unclaimed entries are still repaired here. On a home written before
+        // installed[] existed, every inactive version is unclaimed, and that
+        // cohort is exactly who the repair ladder was built for.
+        const auto owner = xvm::subos_ownership(
+            st.ws, st.wsInstalled, st.otherSubos, name, version);
+        if (!owner.ownedHere && !owner.otherSubos.empty()) {
+            add({
+                .kind    = FindingKind::ForeignPayload,
+                .level   = FindingLevel::Warning,
+                .target  = name,
+                .version = version,
+                .detail  = std::move(detail),
+                .remedy  = std::format(
+                    "xlings subos use {} && xlings self doctor --fix",
+                    owner.otherSubos.front()),
+                .groupKey = std::format("{}|{}", expanded.string(), version),
+                .subos   = owner.otherSubos,
+            });
+            return;
+        }
+        const auto wit = st.ws.find(name);
+        std::string remedy;
+        if (audit.deep) {
+            if (auto coord = owning_coordinate_(st.db, name, version, probe)) {
+                remedy = coord->install_command();
+            }
+        }
+        add({
+            .kind     = FindingKind::BrokenPayload,
+            .level    = FindingLevel::Error,
+            .target   = name,
+            .version  = version,
+            .detail   = std::move(detail),
+            .remedy   = std::move(remedy),
+            .groupKey = std::format("{}|{}", expanded.string(), version),
+            .active   = wit != st.ws.end() && wit->second == version,
+        });
+    };
+
+    for (const auto& [name, vinfo] : st.db) {
+        for (const auto& [version, vdata] : vinfo.versions) {
+            // Per version, not per target: one target can hold versions of
+            // different kinds, and skipping the whole target on the
+            // target-level fallback discards the ones that are programs.
+            if (xvm::effective_kind(vinfo, vdata) != "program") continue;
+            if (vdata.path.empty()) continue;  // type-only stub
+
+            auto expanded = xvm::expand_path(vdata.path, st.homeStr);
+            std::error_code ec;
+
+            // L4: payload directory must exist.
+            if (!fs::is_directory(expanded, ec)) {
+                reportBrokenPayload(name, version, expanded, std::format(
+                    "{} path {} missing",
+                    xvm::display_coordinate(name, version),
+                    Config::display_path(expanded)));
+                continue;
+            }
+
+            // An install-time subos path recorded in the alias or an env
+            // value. Detected before the alias/no-alias split because envs
+            // carry it too, and a package with no alias at all still can.
+            if (const auto activeSubos =
+                    Config::xvm_artifact_subos_dir().string();
+                !activeSubos.empty()) {
+                std::vector<std::string> baked;
+                // A subos path stored in a database every subos shares.
+                //
+                // Alias and envs are asked the SAME question -- "does this
+                // pin one subos?" -- because they have the same fix and the
+                // same cause. The defect is a property of the VALUE, not of
+                // any argument syntax, which is why an earlier shape that
+                // looked for a `--sysroot` flag could do nothing for envs.
+                //
+                // Detection calls the function the repair calls, so the two
+                // cannot drift, and after the repair there is nothing left to
+                // rewrite: the finding goes away permanently instead of
+                // moving to whichever subos runs doctor next.
+                const auto note_if_baked = [&](std::string_view what,
+                                               const std::string& value) {
+                    if (xvm::pin_subos_paths(value, st.homeStr) != value) {
+                        baked.push_back(std::format("{} '{}'", what, value));
+                    }
+                };
+                if (!vdata.alias.empty()) {
+                    note_if_baked("alias", vdata.alias[0]);
+                }
+                for (const auto& [key, value] : vdata.envs) {
+                    note_if_baked(std::format("env {}", key), value);
+                }
+                if (!baked.empty()) {
+                    std::string list;
+                    for (const auto& b : baked) {
+                        if (!list.empty()) list += ", ";
+                        list += b;
+                    }
+                    add({
+                        .kind    = FindingKind::SubosPathBaked,
+                        .level   = FindingLevel::Warning,
+                        .target  = name,
+                        .version = version,
+                        .detail  = std::format(
+                            "{} records an install-time subos path: {} — "
+                            "execution already follows the active subos; "
+                            "`--fix` rewrites the record",
+                            xvm::display_coordinate(name, version), list),
+                    });
+                }
+            }
+
+            const bool aliasMode =
+                !vdata.alias.empty() && !vdata.alias[0].empty();
+            if (!aliasMode) {
+                // L5: the executable shim_dispatch would exec must resolve.
+                if (!xvm::resolve_executable(name, vdata.path, st.homeStr)
+                         .empty()) {
+                    continue;
+                }
+                // A name that exists only to anchor a release is not a broken
+                // payload. Library-only packages have no program of their own,
+                // and with `type` unset that entry defaults to "program" and
+                // then fails this check forever.
+                if (xvm::is_binding_root(st.db, name, version)
+                    || !payload_has_any_executable_(expanded)) {
+                    add({
+                        .kind    = FindingKind::ReleaseAnchor,
+                        .level   = FindingLevel::Notice,
+                        .target  = name,
+                        .version = version,
+                        .detail  = std::format(
+                            "{} registers no program of its own; it names the "
+                            "release its libraries belong to",
+                            xvm::display_coordinate(name, version)),
+                    });
+                    continue;
+                }
+                reportBrokenPayload(name, version, expanded, std::format(
+                    "{} executable '{}' not found in {}",
+                    xvm::display_coordinate(name, version), name,
+                    Config::display_path(expanded)));
+                continue;
+            }
+
+            // Alias mode: ask the question the runtime answers.
+            //
+            // This used to call resolve_executable, which searches the
+            // package's own payload and nothing else, and report every miss as
+            // one warning. But the alias branch of shim_dispatch prepends the
+            // payload, the payload's bin, AND the subos bin dir to PATH before
+            // handing the command to a shell, so two whole tiers of the real
+            // search were invisible here. A package whose only job is to give
+            // thirty short names to a sibling package's `mcpp` resolves on
+            // every invocation and was reported broken on every doctor run --
+            // thirty-four such warnings on one measured home, all of them
+            // false, and one warning level for "runs fine via a sibling",
+            // "runs fine via the host" and "nothing to exec at all".
+            //
+            // resolve_alias_program lives next to the dispatcher so the two
+            // cannot drift, the same reason the baked-path check calls the
+            // function its repair calls.
+            //
+            // TODO(self-doctor): only alias[0] is inspected — matches the
+            // runtime today; if multi-element fallback chains ever land they
+            // should be covered too.
+            const auto aliasProg = alias_program_(vdata.alias[0], st.homeStr);
+            const auto resolution = xvm::resolve_alias_program(
+                aliasProg, vdata.path, st.homeStr, p.binDir, hostPath);
+            // Its own payload, a sibling shim in this subos, or a full path
+            // that is there. Nothing to report.
+            //
+            // The absolute case used to be skipped BEFORE anything was
+            // checked, so an absolute alias pointing at a path that no longer
+            // existed was the one alias shape doctor could never report. It
+            // is checked now, and only its absence is a finding.
+            if (resolution.origin == xvm::AliasOrigin::Absolute
+                || resolution.origin == xvm::AliasOrigin::Payload
+                || resolution.origin == xvm::AliasOrigin::SubosBin) {
+                continue;
+            }
+            if (resolution.origin == xvm::AliasOrigin::SystemPath) {
+                // Works, and is allowed to: a recipe may deliberately wrap a
+                // host tool. Worth saying once because it is the difference
+                // between a home that is portable and one that is not, but it
+                // is not a defect and must not touch the exit code.
+                add({
+                    .kind    = FindingKind::AliasUnresolved,
+                    .level   = FindingLevel::Notice,
+                    .target  = name,
+                    .version = version,
+                    .detail  = std::format(
+                        "{} alias '{}' is satisfied by a host command ({}), "
+                        "not by anything xlings installed",
+                        xvm::display_coordinate(name, version), aliasProg,
+                        resolution.path.string()),
+                });
+                continue;
+            }
+
+            // Nothing to exec, anywhere the runtime would look.
+            //
+            // Now an error, because it now means what it says. If the alias
+            // names a target xlings knows about, the honest finding is that
+            // the target has no active version -- Check 2.7 already reported
+            // it against the release, with a remedy that fixes both -- and
+            // repeating it here as an alias defect would send the user after
+            // the wrong thing.
+            if (const auto* aliasVi = xvm::get_vinfo(st.db, aliasProg);
+                aliasVi && xvm::has_program_kind(st.db, aliasProg)) {
+                continue;
+            }
+            add({
+                .kind    = FindingKind::AliasUnresolved,
+                .level   = FindingLevel::Error,
+                .target  = name,
+                .version = version,
+                .detail  = std::format(
+                    "{} alias '{}' resolves to nothing — not in {}, not a "
+                    "sibling command in {}, not on PATH",
+                    xvm::display_coordinate(name, version), aliasProg,
+                    Config::display_path(expanded),
+                    Config::display_path(p.binDir)),
+            });
+        }
+    }
+
+    // Check 4: the binding state itself.
+    //
+    // Everything above looks at shims and payloads. None of it can see a
+    // release whose members disagree about which release they are, or an
+    // active toolchain whose members drifted apart -- and those are exactly the
+    // states that make `xlings use` refuse.
+    auto bindingFindings = xvm::inspect_binding_state(st.db, st.ws);
+
+    // Sysroot ownership. Reported only for destinations a package declares,
+    // not for the whole tree: the subos carries the host image, so listing
+    // every unmanaged entry would bury the two or three that matter.
+    {
+        std::vector<xvm::SysrootEntry> entries;
+        for (const auto& [target, version] : st.ws) {
+            auto infoIt = st.db.find(target);
+            if (infoIt == st.db.end()) continue;
+            auto dataIt = infoIt->second.versions.find(version);
+            if (dataIt == infoIt->second.versions.end()) continue;
+            const auto& dst = dataIt->second.fileDst;
+            if (dst.empty()) continue;
+            const auto abs = p.subosDir / dst;
+            std::error_code ec;
+            if (!fs::exists(abs, ec) && !fs::is_symlink(abs, ec)) continue;
+            xvm::SysrootEntry entry{.path = dst};
+            if (fs::is_symlink(abs, ec)) {
+                entry.linkTarget = fs::read_symlink(abs, ec).string();
+                if (ec) entry.linkTarget.clear();
+            }
+            entries.push_back(std::move(entry));
+        }
+        // Dangling links, scanned rather than derived from the workspace.
+        //
+        // The loop above only visits destinations the ACTIVE selection
+        // declares, and the links that matter here are precisely the ones
+        // nothing declares any more: the package was removed, or was
+        // installed by a run whose payload store is gone. Scanning is cheap
+        // (the header farm is one link per top-level entry) and it is the
+        // only way to see them at all.
+        //
+        // Every subos, not just the active one. The damage that produces
+        // these links is not something the user does from inside the subos it
+        // lands in -- the measured case was an isolated run that materialized
+        // headers into the real home's `dev-hello` while the user was working
+        // in `default` -- so "only look where you happen to be standing"
+        // guarantees the report misses it. Repair still only touches the
+        // active subos (the multi-subos boundary: another subos may be live
+        // in another shell); the others get named, with the command that
+        // fixes them.
+        struct SysrootScanRoot {
+            std::string name;      // empty => the active selection
+            fs::path    root;
+        };
+        std::vector<SysrootScanRoot> sysrootRoots{{{}, p.subosDir}};
+        {
+            std::error_code sec;
+            const auto activeRoot = fs::weakly_canonical(p.subosDir, sec);
+            for (const auto& name : Config::list_subos_names()) {
+                auto root = p.homeDir / "subos" / name;
+                std::error_code rec;
+                if (fs::weakly_canonical(root, rec) == activeRoot) continue;
+                sysrootRoots.push_back({name, std::move(root)});
+            }
+        }
+
+        // Payloads whose files and whose records disagree.
+        //
+        // Walks the STORE, not the version database -- which is the whole
+        // point. Every other check here starts from a DB entry and asks
+        // whether the files behind it are sound; this one starts from files
+        // that no DB entry mentions. A package that registered nothing is
+        // invisible to a DB walk by construction, and invisible is exactly how
+        // it presented: `xlings info` said `installed`, `xlings list` agreed,
+        // and no subos held one of its libraries.
+        //
+        // Runs WITHOUT `--deep`. It reads one small file per version directory
+        // and opens no payload, so it costs a few hundred stats on a large
+        // home -- the deep audit's price is readelf per binary, and this is
+        // nothing like it. Putting it behind `--deep` would hide the finding
+        // from the default command, which is the command people run.
+        {
+            const xim::LedgerIndex ledgerIndex(st.db, st.homeStr);
+            std::error_code sec;
+            for (const auto& storeRoot : {Config::global_data_dir() / "xpkgs",
+                                          Config::project_data_dir() / "xpkgs"}) {
+                if (!fs::is_directory(storeRoot, sec)) continue;
+                for (const auto& pkgDir : platform::dir_entries(storeRoot)) {
+                    if (!pkgDir.is_directory()) continue;
+                    const auto storeName = pkgDir.path().filename().string();
+                    const auto sep = storeName.find("-x-");
+                    const auto ns = sep == std::string::npos
+                        ? std::string{} : storeName.substr(0, sep);
+                    const auto name = sep == std::string::npos
+                        ? storeName : storeName.substr(sep + 3);
+                    for (const auto& verDir :
+                            platform::dir_entries(pkgDir.path())) {
+                        if (!verDir.is_directory()) continue;
+                        const auto version =
+                            verDir.path().filename().string();
+                        const auto coordinate = ns.empty()
+                            ? std::format("{}@{}", name, version)
+                            : std::format("{}:{}@{}", ns, name, version);
+                        const auto remedy =
+                            std::format("xlings install {}", coordinate);
+
+                        if (xim::stamped_incomplete(verDir.path())) {
+                            add({
+                                .kind    = FindingKind::IncompletePayload,
+                                .level   = FindingLevel::Error,
+                                .target  = name,
+                                .version = version,
+                                .detail  = std::format(
+                                    "{} did not finish installing; its payload "
+                                    "is on disk and nothing registered it",
+                                    coordinate),
+                                .remedy  = remedy,
+                            });
+                            continue;
+                        }
+                        if (xim::unverifiable_stamped_payload(
+                                ledgerIndex, ns, name, version,
+                                verDir.path())) {
+                            add({
+                                .kind    = FindingKind::UnverifiedPayload,
+                                .level   = FindingLevel::Notice,
+                                .target  = name,
+                                .version = version,
+                                .detail  = std::format(
+                                    "{} is installed but the version database "
+                                    "references none of it -- it may register "
+                                    "nothing by design, or its install may "
+                                    "have registered nothing",
+                                    coordinate),
+                                .remedy  = remedy,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+
+        struct PayloadAuditRoot {
+            fs::path path;
+            std::string target;
+            std::string storeName;
+            std::string version;
+        };
+        std::vector<PayloadAuditRoot> payloadAuditRoots;
+        if (audit.deep) {
+            if (audit.scope) {
+                const auto& match = *audit.scope;
+                const auto storeName = xim::package_store_name(
+                    match.namespaceName, match.name);
+                const auto path = audit_payload_dir_(match);
+                std::error_code sec;
+                if (fs::is_directory(path, sec)) {
+                    payloadAuditRoots.push_back({
+                        .path = path,
+                        .target = match.canonicalName,
+                        .storeName = storeName,
+                        .version = match.version,
+                    });
+                }
+            } else {
+                std::error_code sec;
+                const auto store = Config::paths().dataDir / "xpkgs";
+                if (fs::is_directory(store, sec)) {
+                    for (const auto& pkgDir : platform::dir_entries(store)) {
+                        if (!pkgDir.is_directory()) continue;
+                        const auto storeName = pkgDir.path().filename().string();
+                        for (const auto& verDir :
+                                platform::dir_entries(pkgDir.path())) {
+                            if (!verDir.is_directory()) continue;
+                            payloadAuditRoots.push_back({
+                                .path = verDir.path(),
+                                .target = storeName,
+                                .storeName = storeName,
+                                .version = verDir.path().filename().string(),
+                            });
+                        }
+                    }
+                }
+            }
+        }
+
+        // Loader and libc from one payload, over what is already on disk.
+        //
+        // The install path refuses to create a split, so anything found here
+        // predates that check or was written by hand. Scanned per payload
+        // rather than per subos because the fault lives in the payload: one
+        // bad binary is bad in every subos that uses it.
+        //
+        // Same implementation the installer asserts with -- deliberately.
+        // Report and repair have drifted three times in this repo, and it
+        // always looks the same from outside: doctor keeps reporting what
+        // `--fix` claims to have fixed.
+        // Progress, because this loop is the reason `--fix` looks dead.
+        //
+        // Measured on a 124-payload / 71 GB home: 145 seconds between the line
+        // announcing the audit and the first result, with nothing in between.
+        // A user cannot tell scanning from hung from dead, and this repo's
+        // usual failure is the reverse -- failure that looks like success --
+        // so the reflex to distrust silence is not there.
+        //
+        // RATE-LIMITED BY TIME, NOT BY COUNT, and silent for the first
+        // seconds. A home small enough to finish quickly prints nothing extra;
+        // only a run long enough to be mistaken for a hang starts reporting.
+        // Tying it to the payload count instead would put a line per payload on
+        // a home that finished in two seconds, and none on the one that needed
+        // them.
+        //
+        // GRANULARITY LIMIT, measured and not hidden: the tick fires between
+        // payloads, so a single large payload still produces one silent
+        // stretch as long as its own scan. On the home this was written
+        // against that was 26 seconds for one payload, down from 145 for the
+        // whole run. Going finer means a progress callback inside
+        // `elfcheck::scan_payload`, which is a shared module and a wider
+        // change; the name of the payload being scanned is emitted BEFORE the
+        // wait, so the remaining silence is at least attributed.
+        //
+        // Both event kinds: the plain CLI renders LogEvent and ignores
+        // ProgressEvent, while the TUI and the agent protocol consume
+        // ProgressEvent. Emitting only one leaves the other silent.
+        {
+        using audit_clock_ = std::chrono::steady_clock;
+        const auto auditStarted = audit_clock_::now();
+        auto auditLastSpoke = auditStarted;
+        std::size_t auditDone = 0;
+        const auto auditTotal = payloadAuditRoots.size();
+        auto auditTick = [&](const auto& root) {
+            if (!audit.onProgress) return;
+            const auto now = audit_clock_::now();
+            using namespace std::chrono;
+            if (duration_cast<seconds>(now - auditStarted).count() < 1) return;
+            if (duration_cast<seconds>(now - auditLastSpoke).count() < 2) return;
+            auditLastSpoke = now;
+            audit.onProgress(auditDone, auditTotal, root.target, root.version);
+        };
+        for (const auto& root : payloadAuditRoots) {
+            auditTick(root);
+            ++auditDone;
+            for (const auto& f : elfcheck::scan_payload(root.path)) {
+                add({
+                    .kind   = FindingKind::LoaderLibcSplit,
+                    .level  = FindingLevel::Error,
+                    .target = root.target,
+                    .version = root.version,
+                    .detail = elfcheck::describe(f),
+                    .remedy = std::format(
+                        "xlings install {}@{} --force",
+                        root.target, root.version),
+                });
+            }
+        }
+        }
+
+        // Name resolution under our own glibc.
+        //
+        // Run for real rather than inferred, and this is the one place where
+        // that distinction is cheap: the glibc payload ships `bin/getent`, so
+        // executing it under its own loader exercises the exact dlopen path a
+        // switched payload will take. Reading the module list off disk would
+        // only tell us which files exist.
+        //
+        // Doing it in-process was the obvious shortcut and it is wrong: this
+        // binary has its own libc (a static musl build has no NSS at all), so
+        // an in-process getpwuid answers a question about xlings rather than
+        // about the payload every other package is about to depend on.
+        //
+        // Notice, not Error, when it works: this is the cell that is supposed
+        // to be boring. When it fails it is an Error, because a home whose
+        // packages resolve no users is broken in a way nothing else reports.
+#ifdef __linux__
+        for (const auto& root : payloadAuditRoots) {
+            const auto& storeName = root.storeName;
+            // `<ns>-x-glibc`, any namespace.
+            if (!storeName.ends_with("-x-glibc")) continue;
+            std::error_code sec;
+            const auto lib64  = root.path / "lib64";
+            const auto loader = lib64 / "ld-linux-x86-64.so.2";
+            const auto getent = root.path / "bin" / "getent";
+            if (!fs::is_regular_file(loader, sec)) continue;
+            if (!fs::is_regular_file(getent, sec)) continue;
+
+            const auto& version = root.version;
+            const auto cmd = std::format(
+                "\"{}\" --library-path \"{}\" \"{}\" passwd {} 2>/dev/null",
+                loader.string(), lib64.string(), getent.string(),
+                ::geteuid());
+            auto [rc, out] = platform::run_command_capture(cmd);
+
+            if (rc == 0 && !out.empty()) {
+                add({
+                    .kind    = FindingKind::NssResolution,
+                    .level   = FindingLevel::Notice,
+                    .target  = storeName,
+                    .version = version,
+                    .detail  = std::format(
+                        "glibc {}: resolves the current user "
+                        "(getent passwd {} under our loader)",
+                        version, ::geteuid()),
+                });
+                continue;
+            }
+
+            // Which backends this host asks for that we do not ship. Part of
+            // the finding, not a separate check: it is the only actionable
+            // thing about the failure.
+            std::string missing;
+            {
+                std::ifstream nss("/etc/nsswitch.conf");
+                std::set<std::string> seen;
+                for (std::string line; std::getline(nss, line);) {
+                    if (auto h = line.find('#'); h != std::string::npos)
+                        line.resize(h);
+                    auto colon = line.find(':');
+                    if (colon == std::string::npos) continue;
+                    auto rest = line.substr(colon + 1);
+                    // `[NOTFOUND=return]` is control flow, not a module.
+                    while (true) {
+                        auto ob = rest.find('[');
+                        if (ob == std::string::npos) break;
+                        auto cb = rest.find(']', ob);
+                        if (cb == std::string::npos) {
+                            rest.resize(ob);
+                            break;
+                        }
+                        rest.erase(ob, cb - ob + 1);
+                    }
+                    std::istringstream toks(rest);
+                    for (std::string mod; toks >> mod;) {
+                        if (!seen.insert(mod).second) continue;
+                        if (!fs::is_regular_file(
+                                lib64 / ("libnss_" + mod + ".so.2"), sec)) {
+                            if (!missing.empty()) missing += ", ";
+                            missing += mod;
+                        }
+                    }
+                }
+            }
+
+            add({
+                .kind    = FindingKind::NssResolution,
+                .level   = FindingLevel::Error,
+                .target  = storeName,
+                .version = version,
+                .detail  = std::format(
+                    "glibc {}: does NOT resolve the current user under our "
+                    "loader{}. Any package switched to this interpreter will "
+                    "see no user, silently.",
+                    version,
+                    missing.empty()
+                        ? std::string{}
+                        : std::format(
+                            " -- /etc/nsswitch.conf names backend(s) this "
+                            "payload does not ship: {}", missing)),
+            });
+        }
+#endif
+
+        for (const auto& scanRoot : sysrootRoots) {
+            const bool isActive = scanRoot.name.empty();
+            for (const auto& sub : {"usr/include", "usr/lib", "usr/lib64",
+                                    "usr/bin"}) {
+                const auto dir = scanRoot.root / sub;
+                std::error_code dec;
+                if (!fs::is_directory(dir, dec)) continue;
+                for (const auto& entry : platform::dir_entries(dir)) {
+                    std::error_code lec;
+                    // Both halves are required. A dangling link IS a symlink
+                    // and is NOT `exists()`; testing only existence reads it
+                    // as "already gone" -- the mistake that let #423's test
+                    // pass while the links were still on disk.
+                    if (!fs::is_symlink(entry.path(), lec)) continue;
+                    if (fs::exists(entry.path(), lec)) continue;
+                    auto target = fs::read_symlink(entry.path(), lec);
+                    add({
+                        .kind    = FindingKind::SysrootDangling,
+                        .level   = FindingLevel::Warning,
+                        .detail  = std::format(
+                            "{}{} points at {}, which does not exist",
+                            isActive ? std::string{}
+                                     : std::format("[{}] ", scanRoot.name),
+                            Config::display_path(entry.path()),
+                            lec ? std::string("(unreadable)")
+                                : Config::display_path(target)),
+                        .remedy  = isActive
+                            ? "xlings self doctor --fix"
+                            : std::format("XLINGS_ACTIVE_SUBOS={} xlings "
+                                          "self doctor --fix", scanRoot.name),
+                        // Empty for the active subos -- that is what `--fix`
+                        // keys on, so a finding from elsewhere cannot be
+                        // repaired by accident.
+                        .subos = isActive
+                            ? std::vector<std::string>{}
+                            : std::vector<std::string>{scanRoot.name},
+                        .shimPath = entry.path(),
+                    });
+                }
+            }
+        }
+
+        auto ownership = xvm::inspect_sysroot_ownership(
+            st.db, st.ws, entries, (p.dataDir / "xpkgs").string());
+        bindingFindings.insert(bindingFindings.end(),
+                               std::make_move_iterator(ownership.begin()),
+                               std::make_move_iterator(ownership.end()));
+    }
+
+    // One line per (code, entry), not per field.
+    //
+    // A single legacy anchor carries one dangling edge per program it bound --
+    // five for each of the two gcc flavours on the measured home -- and they
+    // are one problem with one cure. Fourteen lines saying the same thing
+    // about five entries is the noise this collapse exists for; the fields are
+    // still named, on the one line.
+    std::map<std::tuple<std::string, std::string, std::string>,
+             std::vector<const xvm::BindingFinding*>> bindingGroups;
+    std::vector<std::tuple<std::string, std::string, std::string>> bindingOrder;
+    for (const auto& f : bindingFindings) {
+        const auto key = std::tuple{f.code, f.target, f.version};
+        auto [it, inserted] = bindingGroups.try_emplace(key);
+        if (inserted) bindingOrder.push_back(key);
+        it->second.push_back(&f);
+    }
+    for (const auto& key : bindingOrder) {
+        const auto& group = bindingGroups.at(key);
+        const auto& f = *group.front();
+        std::string detail = f.summary;
+        if (!f.target.empty()) {
+            detail += std::format(
+                " [{}]", xvm::display_coordinate(f.target, f.version));
+        }
+        std::string fields;
+        for (const auto* member : group) {
+            if (member->field.empty()) continue;
+            if (!fields.empty()) fields += ", ";
+            fields += member->field;
+        }
+        if (!fields.empty()) {
+            detail += std::format(" at {}", fields);
+        }
+        // The code stays in the line. It is the only greppable handle a user
+        // or a bug report has on which invariant broke, and the hint alone is
+        // prose.
+        detail += std::format(" — {} — {}", f.code, f.hint);
+        add({
+            .kind    = FindingKind::BindingState,
+            // A notice describes state the upgrade inherited rather than
+            // created, so it does not colour the run red.
+            .level   = f.severity == xvm::BindingSeverity::Notice
+                           ? FindingLevel::Notice : FindingLevel::Error,
+            .target  = f.target,
+            .version = f.version,
+            .detail  = std::move(detail),
+        });
+    }
+
+    // Check 5: what the OTHER subos of this home point at.
+    //
+    // Never counted toward the exit code. The exit code answers "is the subos
+    // I am in healthy", and it has to stay answerable. Printing it is the
+    // point: before this, a subos whose active version was taken out from
+    // under it had no command that mentioned it.
+    // A remedy that cannot work is not a remedy.
+    //
+    // A dangling binding edge does not merely make `xlings use` refuse -- it
+    // makes registration validation refuse, so `xlings install <pkg>` fails on
+    // it too. Measured on a real home: of the three install commands the
+    // report printed, two exited 1 with `xvm-binding-validation-failed`, and
+    // only `self doctor --fix` cleared them (it prunes the edges before it
+    // runs the ladder). Printing the install anyway is how the user ends up
+    // back at the loop this whole change exists to break: run the command,
+    // watch it fail, be told to run doctor.
+    //
+    // Deliberately coarse -- ANY dangling edge redirects EVERY payload remedy.
+    // Which edge blocks which package is not decidable from here (the
+    // legacy-component walk can reach arbitrary edges), and the coarse answer
+    // is the true one: `--fix` is what repairs this home, whatever the entry.
+    const bool danglingEdges = std::ranges::any_of(
+        bindingFindings, [](const xvm::BindingFinding& f) {
+            return f.code == "xvm-legacy-edge-dangling";
+        });
+    if (danglingEdges) {
+        for (auto& f : scan.findings) {
+            if (f.kind != FindingKind::BrokenPayload || f.remedy.empty()) {
+                continue;
+            }
+            f.remedy = "xlings self doctor --fix";
+        }
+    }
+
+    for (const auto& f : xvm::inspect_subos_references(st.db, st.otherSubos)) {
+        add({
+            .kind    = FindingKind::OtherSubos,
+            .level   = f.severity == xvm::BindingSeverity::Notice
+                           ? FindingLevel::Notice : FindingLevel::Warning,
+            .target  = f.target,
+            .version = f.version,
+            .detail  = std::format("{} — {} — {}", f.summary, f.code, f.hint),
+        });
+    }
+
+    return scan;
+}
+
+// Everything below the payload layer: shims and pure state-file edits. All of
+// it is local, none of it can fail halfway in a way the user has to unpick.
+void repair_local_(const DoctorState& st, const Scan& scan,
+                   RepairReport& out) {
+    auto& p = Config::paths();
+    const auto note = [&](std::string label, std::string text) {
+        out.notes.emplace_back(std::move(label), std::move(text));
+    };
+
+    // Subos manifest repairs. Driven by the findings detection produced, not
+    // by a second reading of the rules -- so what `--fix` touches is exactly
+    // what was reported.
+    {
+        namespace mf = xlings::subos::manifest;
+        const bool wantsBlock = std::ranges::any_of(
+            scan.findings, [](const Finding& f) {
+                return f.kind == FindingKind::SubosManifest
+                       && f.remedy == "xlings self doctor --fix";
+            });
+        std::vector<std::string> orphans;
+        for (const auto& f : scan.findings)
+            if (f.kind == FindingKind::SubosEnvOrphan) orphans.push_back(f.version);
+
+        // A runtime declaration that contradicts what this subos actually runs.
+        // Keyed on the finding, and the adopted value is read back through the
+        // same `observed_runtime` the detection used, so the repairer cannot
+        // decide something the reporter did not say.
+        //
+        // Only the Error shape is adopted: a declaration with NO active runtime
+        // is a cold intent (`subos new --runtime X` before installing X), and
+        // overwriting that would undo a decision someone took.
+        std::string adoptRuntime;
+        for (const auto& f : scan.findings) {
+            if (f.kind != FindingKind::SubosRuntimeMissing) continue;
+            if (f.level != FindingLevel::Error) continue;
+            if (!f.remedy.starts_with("xlings self doctor --fix")) continue;
+            adoptRuntime = f.version;   // the declared binding; family only
+            break;
+        }
+
+        // A contested binding is deliberately NOT repaired here. It is reported
+        // precisely because nothing can say which version was meant -- the
+        // package has no active version -- and picking the highest, or the
+        // newest on disk, would be this codebase's recurring defect rather than
+        // a repair: a second answerer invented at the read end. Its remedy is
+        // `xlings use`, which makes the choice a decision someone took.
+
+        if (wantsBlock || !orphans.empty() || !adoptRuntime.empty()) {
+            auto doc = mf::read_document(p.subosDir);
+            nlohmann::json document = doc ? *doc : nlohmann::json::object();
+            if (!doc && fs::exists(mf::config_path(p.subosDir))) {
+                // Unreadable rather than absent. Detection already said so and
+                // offered no `--fix` remedy; do not overwrite it here either.
+                note(glyph::mark(glyph::failed, "subos manifest"),
+                     std::format("{} is not readable JSON; left untouched",
+                                 Config::display_path(
+                                     mf::config_path(p.subosDir))));
+            } else {
+                bool changed = false;
+                if (!document.contains("workspace"))
+                    document["workspace"] = nlohmann::json::object();
+                if (wantsBlock) {
+                    // A broken block can still carry a valid runtime binding.
+                    // Rewriting with DEFAULT_RUNTIME here used to re-declare
+                    // the subos against whatever the current default is — a
+                    // repair must not change what the subos IS.
+                    const auto keptRuntime =
+                        mf::preserved_runtime(document, mf::DEFAULT_RUNTIME);
+                    document[std::string(mf::BLOCK)] = mf::make_block(
+                        keptRuntime,
+                        std::format("xlings {}", Info::VERSION),
+                        platform::host_glibc_version());
+                    changed = true;
+                    note(glyph::mark(glyph::bullet, "subos manifest"),
+                         std::format("described subos '{}' (runtime {})",
+                                     p.activeSubos, keptRuntime));
+                }
+                if (!adoptRuntime.empty()) {
+                    const auto observed = mf::observed_runtime(
+                        document, mf::binding_name(adoptRuntime));
+                    if (observed.empty()) {
+                        note(glyph::mark(glyph::warn, "subos runtime"),
+                             std::format("cannot adopt: subos '{}' has no "
+                                         "active {} to record",
+                                         p.activeSubos,
+                                         mf::binding_name(adoptRuntime)));
+                    } else if (observed != adoptRuntime) {
+                        document[std::string(mf::BLOCK)]["runtime"] = observed;
+                        changed = true;
+                        note(glyph::mark(glyph::bullet, "subos runtime"),
+                             std::format("subos '{}' now declares {} "
+                                         "(was {}, never activated here)",
+                                         p.activeSubos, observed,
+                                         adoptRuntime));
+                    }
+                }
+                for (const auto& binding : orphans) {
+                    if (!mf::remove_provider(document, binding)) continue;
+                    changed = true;
+                    note(glyph::mark(glyph::bullet, "subos env dropped"),
+                         std::format("{} is not installed here", binding));
+                }
+
+                if (changed) {
+                    try {
+                        platform::write_string_to_file(
+                            mf::config_path(p.subosDir).string(),
+                            document.dump(2));
+                    } catch (const std::exception& e) {
+                        note(glyph::mark(glyph::failed, "subos manifest"),
+                             std::format("could not write {}: {}",
+                                         Config::display_path(
+                                             mf::config_path(p.subosDir)),
+                                         std::string(e.what())));
+                    }
+                }
+            }
+        }
+    }
+
+    for (const auto& f : scan.findings) {
+        if (f.kind == FindingKind::MissingShim) {
+            if (!fs::exists(st.xlingsBin)) continue;
+            std::error_code ec;
+            fs::create_directories(p.binDir, ec);
+            if (create_shim(st.xlingsBin, f.shimPath) != LinkResult::Failed) {
+                note(glyph::mark(glyph::bullet, "shim recreated"), Config::display_path(f.shimPath));
+            } else {
+                note(glyph::mark(glyph::failed, "shim repair failed"), std::format(
+                    "could not recreate {}",
+                    Config::display_path(f.shimPath)));
+            }
+        } else if (f.kind == FindingKind::SysrootDangling) {
+            // Another subos's link is reported, not removed. A second shell
+            // can have that subos active right now, and repairing state out
+            // from under it is the multi-subos boundary this codebase keeps
+            // everywhere else. The finding carries the exact command.
+            if (!f.subos.empty()) continue;
+            std::error_code ec;
+            // remove(), not remove_all(): the link is being deleted, and if
+            // it were somehow followable, remove_all would delete the
+            // package payload behind it.
+            fs::remove(f.shimPath, ec);
+            if (!ec) {
+                note(glyph::mark(glyph::bullet, "dangling link removed"),
+                     Config::display_path(f.shimPath));
+            } else {
+                note(glyph::mark(glyph::failed, "sysroot repair failed"),
+                     std::format("could not remove {}",
+                                 Config::display_path(f.shimPath)));
+            }
+        } else if (f.kind == FindingKind::OrphanShim
+                || f.kind == FindingKind::LegacyAliasShim) {
+            std::error_code ec;
+            fs::remove(f.shimPath, ec);
+            if (!ec) {
+                note(glyph::mark(glyph::bullet, "shim removed"), Config::display_path(f.shimPath));
+            } else {
+                note(glyph::mark(glyph::failed, "shim repair failed"), std::format(
+                    "could not remove {}", Config::display_path(f.shimPath)));
+            }
+        }
+    }
+}
+
+// The three state-file repairs, in an order that matters.
+//
+// Dangling edges first: they are repairable without guessing, and leaving one
+// in place keeps the release it names unresolvable, which would make the
+// deactivation pass below see a problem that is really this one. Unregistered
+// actives next, for the same reason in reverse: an active pointer into nothing
+// makes a release look incoherent when it is merely absent.
+void repair_state_(RepairReport& out) {
+    const auto note = [&](std::string label, std::string text) {
+        out.notes.emplace_back(std::move(label), std::move(text));
+    };
+
+    auto db = Config::versions();
+    if (auto pruning = xvm::plan_dangling_edge_pruning(db); !pruning.empty()) {
+        auto lock = xvm::acquire_state_lock(Config::paths().homeDir);
+        if (!lock) {
+            note(glyph::mark(glyph::failed, "binding state"), std::format(
+                "cannot drop dangling binding edges: {}", lock.error()));
+        } else {
+            Config::reload_state();
+            auto& mutableDb = Config::versions_mut();
+            const auto replanned = xvm::plan_dangling_edge_pruning(mutableDb);
+            if (xvm::apply_dangling_edge_pruning(mutableDb, replanned) > 0) {
+                Config::save_versions();
+                for (const auto& e : replanned.edges) {
+                    note(glyph::mark(glyph::bullet, "edge dropped"), std::format(
+                        "{} no longer points at unregistered {}",
+                        xvm::display_coordinate(e.target, e.version),
+                        xvm::display_coordinate(e.peerTarget, e.peerVersion)));
+                }
+            }
+        }
+    }
+
+    // Baked subos paths. Rewritten to `<home>/subos/current`, NOT to the
+    // subos this run happens to resolve to.
+    //
+    // Rewriting to the active subos only moved the pin: the record went on
+    // naming one concrete subos, so the very next `doctor` in a different one
+    // reported it again, and `--fix` could never clear its own finding.
+    // `current` is the symlink `self init` creates and `subos use --global`
+    // maintains, so the repaired record is correct from every subos at once --
+    // and exec-time normalization still substitutes the truly active
+    // directory, including under XLINGS_ACTIVE_SUBOS and project subos, where
+    // a symlink cannot follow.
+    {
+        const auto homeStr = Config::paths().homeDir.string();
+        const auto has_baked = [&](const xvm::VersionDB& src) {
+            if (homeStr.empty()) return false;
+            for (const auto& [name, vinfo] : src) {
+                for (const auto& [version, vdata] : vinfo.versions) {
+                    if (!vdata.alias.empty()
+                        && xvm::pin_subos_paths(vdata.alias[0], homeStr)
+                               != vdata.alias[0]) {
+                        return true;
+                    }
+                    for (const auto& [k, v] : vdata.envs) {
+                        if (xvm::pin_subos_paths(v, homeStr) != v) return true;
+                    }
+                }
+            }
+            return false;
+        };
+        if (has_baked(Config::versions())) {
+            auto lock = xvm::acquire_state_lock(Config::paths().homeDir);
+            if (!lock) {
+                note(glyph::mark(glyph::failed, "subos path"), std::format(
+                    "cannot rewrite install-time subos paths: {}",
+                    lock.error()));
+            } else {
+                Config::reload_state();
+                auto& mutableDb = Config::versions_mut();
+                std::size_t rewritten = 0;
+                for (auto& [name, vinfo] : mutableDb) {
+                    for (auto& [version, vdata] : vinfo.versions) {
+                        bool touched = false;
+                        // The real migration: the concrete subos becomes the
+                        // placeholder, so the finding disappears instead of
+                        // moving to whichever subos ran doctor. Rewriting it
+                        // to another subos -- including `current` -- would
+                        // leave a subos path in a shared database, and the
+                        // next run would be right to report it again.
+                        for (auto& a : vdata.alias) {
+                            auto fixed = xvm::pin_subos_paths(a, homeStr);
+                            if (fixed != a) { a = std::move(fixed); touched = true; }
+                        }
+                        // Envs get the same treatment, which they could not
+                        // when this was a flag: the defect is a property of
+                        // the value, not of any particular argument syntax.
+                        for (auto& [k, v] : vdata.envs) {
+                            auto fixed = xvm::pin_subos_paths(v, homeStr);
+                            if (fixed != v) { v = std::move(fixed); touched = true; }
+                        }
+                        if (touched) {
+                            ++rewritten;
+                            note(glyph::mark(glyph::bullet, "subos path"),
+                                 std::format(
+                                     "{} no longer records a subos",
+                                     xvm::display_coordinate(name, version)));
+                        }
+                    }
+                }
+                if (rewritten > 0) Config::save_versions();
+            }
+        }
+    }
+
+    db = Config::versions();
+    auto ws = Config::effective_workspace();
+    if (auto stale = xvm::plan_unregistered_active_deactivation(db, ws);
+        !stale.empty()) {
+        auto lock = xvm::acquire_state_lock(Config::paths().homeDir);
+        if (!lock) {
+            note(glyph::mark(glyph::failed, "binding state"), std::format(
+                "cannot deactivate unregistered versions: {}", lock.error()));
+        } else {
+            Config::reload_state();
+            auto& mutableWs = Config::workspace_mut();
+            std::size_t dropped = 0;
+            for (const auto& target : stale) {
+                const auto it = mutableWs.find(target);
+                if (it == mutableWs.end()) continue;
+                note(glyph::mark(glyph::bullet, "deactivated"), std::format(
+                    "{} was active at a version that is not registered — run "
+                    "`xlings use {} <version>` to select one",
+                    xvm::display_coordinate(target, it->second), target));
+                mutableWs.erase(it);
+                ++dropped;
+            }
+            if (dropped > 0) Config::save_workspace();
+        }
+    }
+
+    db = Config::versions();
+    ws = Config::effective_workspace();
+    if (auto plan = xvm::plan_incoherent_deactivation(db, ws);
+        !plan.targets.empty()) {
+        auto lock = xvm::acquire_state_lock(Config::paths().homeDir);
+        if (!lock) {
+            note(glyph::mark(glyph::failed, "binding state"), std::format(
+                "cannot deactivate incoherent releases: {}", lock.error()));
+        } else {
+            Config::reload_state();
+            auto& mutableWs = Config::workspace_mut();
+            std::size_t dropped = 0;
+            for (const auto& [target, label] : plan.targets) {
+                if (mutableWs.erase(target) == 0) continue;
+                ++dropped;
+                note(glyph::mark(glyph::bullet, "deactivated"), std::format(
+                    "{} (was part of {}) — run `xlings use {} <version>` to "
+                    "select a release", target, label, target));
+            }
+            if (dropped > 0) Config::save_workspace();
+        }
+    }
+}
+
+// Other subos: the deletions doctor could already describe exactly.
+//
+// Nothing is installed and nothing is chosen. `active` entries pointing at a
+// version the shared database does not have are dropped, and `installed[]`
+// entries likewise -- both are references into nothing, and both are what the
+// report used to hand back as a list of commands for the user to run one subos
+// at a time.
+void repair_other_subos_(const DoctorState& st, RepairReport& out) {
+    auto plan = xvm::plan_subos_metadata_repair(Config::versions(),
+                                                st.otherSubos);
+    if (plan.empty()) return;
+
+    auto lock = xvm::acquire_state_lock(Config::paths().homeDir);
+    if (!lock) {
+        out.notes.emplace_back(glyph::mark(glyph::failed, "other subos"), std::format(
+            "cannot repair other subos state: {}", lock.error()));
+        return;
+    }
+
+    for (const auto& entry : plan.entries) {
+        const auto snapshotIt = std::ranges::find_if(
+            st.otherSnapshots,
+            [&](const auto& s) { return s.name == entry.subos; });
+        if (snapshotIt == st.otherSnapshots.end()) continue;
+
+        // Re-read: the snapshot was taken before the repairs above ran, and
+        // one of them may have rewritten this very file.
+        auto fresh = profile::load_subos_snapshots(Config::paths().homeDir);
+        const auto freshIt = std::ranges::find_if(
+            fresh, [&](const auto& s) { return s.dir == snapshotIt->dir; });
+        if (freshIt == fresh.end()) continue;
+
+        auto workspace = freshIt->workspace;
+        const auto dropped =
+            xvm::apply_subos_metadata_repair(workspace, entry);
+        if (dropped == 0) continue;
+        if (!profile::save_subos_workspace(snapshotIt->dir, workspace)) {
+            out.notes.emplace_back(glyph::mark(glyph::failed, "other subos"), std::format(
+                "could not write the state file of subos '{}'", entry.subos));
+            continue;
+        }
+        for (const auto& target : entry.deactivate) {
+            out.notes.emplace_back(glyph::mark(glyph::bullet, "other subos repaired"), std::format(
+                "{}: deactivated '{}' — it named a version that is not "
+                "registered; run `xlings subos use {}` then `xlings use {} "
+                "<version>` to choose one", entry.subos, target,
+                entry.subos, target));
+        }
+        for (const auto& [target, version] : entry.dropInstalled) {
+            out.notes.emplace_back(glyph::mark(glyph::bullet, "other subos repaired"), std::format(
+                "{}: dropped stale installed entry {}", entry.subos,
+                xvm::display_coordinate(target, version)));
+        }
+    }
+}
+
+// ── the payload ladder ───────────────────────────────────────────────
+
+// `onStep`, because the repair below shells out to `xlings install` and that
+// can be a large download with nothing on screen.
+//
+// In a plain terminal the child's own output is visible. In the agent and TUI
+// modes it is NOT: `platform::exec` appends `>/dev/null 2>&1` when
+// `tui_mode_` is set (platform.cppm), so the same repair is a genuinely
+// silent multi-hundred-megabyte wait there. Saying what is about to run, and
+// that it may download, is the difference between waiting and giving up.
+void repair_payloads_(const DoctorState& st, const Scan& scan,
+                      const CoordinateProbe& probe, bool dryRun,
+                      RepairReport& out,
+                      const std::function<void(std::string_view)>& onStep = {}) {
+    // Collapse the findings onto their owning package: one install per
+    // release, not one per program in it. A broken llvm reports nine targets;
+    // reinstalling llvm nine times would be nine downloads for one problem.
+    std::map<xvm::InstallCoordinate, std::vector<const Finding*>> byOwner;
+    std::vector<const Finding*> unowned;
+    for (const auto& f : scan.findings) {
+        if (f.kind != FindingKind::BrokenPayload) continue;
+        if (auto coord =
+                owning_coordinate_(st.db, f.target, f.version, probe)) {
+            byOwner[*coord].push_back(&f);
+        } else {
+            unowned.push_back(&f);
+        }
+    }
+
+    if (dryRun) {
+        for (const auto& [coord, covered] : byOwner) {
+            out.planned.push_back(std::format(
+                "{}   ({} entr{})", coord.install_command(), covered.size(),
+                covered.size() == 1 ? std::string("y")
+                                    : std::string("ies")));
+        }
+        for (const auto* f : unowned) {
+            out.planned.push_back(std::format(
+                "prune {} (no package provides it and its payload is gone)",
+                xvm::display_coordinate(f->target, f->version)));
+        }
+        return;
+    }
+
+    const CommandRunner run = [](const std::string& cmd) {
+        return platform::exec(cmd);
+    };
+
+    // Repair with the client that is running, not with whatever `xlings`
+    // resolves to on PATH. Normally the same binary; not when doctor was
+    // started by absolute path, and then the repair would be carried out by a
+    // different client than the one that decided what needed repairing.
+    RepairPolicy policy;
+    {
+        const auto self = platform::get_executable_path().string();
+        if (!self.empty() && is_shell_safe_token(self)) policy.client = self;
+    }
+
+    for (const auto& [coord, covered] : byOwner) {
+        if (onStep) {
+            onStep(std::format("repairing {} — running `{}` (this may download)",
+                               coord.package, coord.install_command()));
+        }
+        // R3's remove exited 0 — did the records actually go? Asked of the
+        // FINDINGS the repair covers, not of the package name it ran the
+        // command with: a package name is not a key in the versions DB, so
+        // looking it up there finds nothing and reads as "removed".
+        const RemovalVerifier removalDone =
+            [&](const std::string&, const std::string&) {
+                Config::reload_state();
+                const auto current = Config::versions();
+                for (const auto* c : covered) {
+                    const auto* vi = xvm::get_vinfo(current, c->target);
+                    if (vi && vi->versions.contains(c->version)) return false;
+                }
+                return true;
+            };
+        RepairTask task{
+            .kind          = RepairKind::BrokenPayload,
+            .target        = coord.package,
+            .version       = coord.version,
+            .detail        = std::format("{} broken entr{}", covered.size(),
+                                         covered.size() == 1 ? std::string("y")
+                                                             : std::string("ies")),
+            .coordinate    = coord.canonical(),
+            .reinstallable = true,   // confirmed by the probe above
+        };
+        auto result = repair_one(task, policy, run, removalDone);
+        if (!result.healed) {
+            for (const auto* c : covered) {
+                out.failedEntries.emplace_back(c->target, c->version);
+            }
+            out.notes.emplace_back(glyph::mark(glyph::failed, "repair failed"), std::format(
+                "{} — {}", coord.canonical(),
+                result.note.empty() ? "the finding it covers is still there"
+                                    : result.note));
+        }
+    }
+}
+
+// Activate what is installed and inactive, by running `use`.
+//
+// Deliberately a subprocess and deliberately the exact command the finding
+// prints. Activating a release is not a workspace write: it places the
+// release's libraries and headers in the sysroot and writes a shim per
+// member, and xvm's `use` path is the only code that does all of it. Setting
+// `workspace[name]` here would activate the name and leave the sysroot
+// holding whatever the previous release put there -- the half-switched state
+// plan_use_switch was written to make impossible.
+//
+// `use` moves the WHOLE release, which can take a name from another provider:
+// node's release owns `npm`, and a separately installed npm package may hold
+// that name today. That is not a side effect this hides -- it is what the
+// printed remedy does when the user runs it by hand, and a `--fix` that did
+// something narrower than the command it advertises would be a third
+// behaviour to reason about. The install path is where "do not take a name
+// from another provider" belongs, and that is where it now lives
+// (registration.cppm); by the time doctor is looking at the wreckage, the
+// user has asked for repair.
+void repair_inactive_(const Scan& scan, const std::string& client,
+                      const CommandRunner& run, bool dryRun,
+                      RepairReport& out) {
+    for (const auto& f : scan.findings) {
+        if (f.kind != FindingKind::InactiveInstalled) continue;
+        // Known in advance to be a repair another repair would undo. Not
+        // attempted, and said so out loud: choosing between two packages that
+        // register the same program name is the user's decision, and `--fix`
+        // running `use` here would only start the fight described in
+        // activation_conflict_.
+        if (!f.conflict.empty()) continue;
+        if (!is_shell_safe_token(f.target) || !is_shell_safe_token(f.version)) {
+            out.notes.emplace_back(
+                glyph::mark(glyph::failed, "activation skipped"),
+                std::format("{} — name or version is not a safe shell token",
+                            xvm::display_coordinate(f.target, f.version)));
+            continue;
+        }
+        const auto cmd = std::format("{} use {}@{}", client, f.target,
+                                     f.version);
+        if (dryRun) {
+            out.planned.push_back(cmd);
+            continue;
+        }
+        if (run(cmd + quiet_suffix()) == 0) {
+            out.notes.emplace_back(glyph::mark(glyph::bullet, "activated"),
+                                   std::format("{}@{}", f.target, f.version));
+        } else {
+            out.failedEntries.emplace_back(f.target, f.version);
+            out.notes.emplace_back(
+                glyph::mark(glyph::failed, "activation failed"),
+                std::format("{} — run `{}` to see why",
+                            xvm::display_coordinate(f.target, f.version),
+                            f.remedy));
+        }
+    }
+}
+
+// Re-run the install of a payload whose own stamp records that it failed.
+//
+// Separate from repair_payloads_ and NOT routed through owning_coordinate_,
+// because these findings come from the store rather than the version database
+// and the database is exactly what does not know about them. The coordinate
+// was recovered from the store layout when the finding was made -- the payload
+// path IS the package identity (xvm/owner.cppm) -- so the remedy already names
+// the right package and there is nothing left to resolve.
+//
+// Re-running the install is the whole repair: the failure marker makes
+// `installation_state` report Incomplete, which is what makes the installer
+// run the hook again instead of concluding "already installed" from the files
+// the failure left behind.
+void repair_incomplete_(const Scan& scan, const CommandRunner& run,
+                        bool dryRun, RepairReport& out,
+                        const std::function<void(std::string_view)>& onStep = {}) {
+    for (const auto& f : scan.findings) {
+        if (f.kind != FindingKind::IncompletePayload) continue;
+        if (f.remedy.empty()) continue;
+        // The WHOLE remedy, not just target and version.
+        //
+        // This finding is built by walking the store, so its namespace comes
+        // from a directory NAME on disk rather than from the index -- and the
+        // remedy is handed to a shell. Checking target and version while
+        // letting the namespace through would leave the one component that
+        // this check, alone among the repairs here, takes from the filesystem.
+        if (!is_shell_safe_token(f.target) || !is_shell_safe_token(f.version)
+            || f.remedy.find_first_of(";&|$`\n<>()") != std::string::npos) {
+            out.notes.emplace_back(
+                glyph::mark(glyph::failed, "reinstall skipped"),
+                std::format("{} — its coordinate is not a safe shell token",
+                            xvm::display_coordinate(f.target, f.version)));
+            continue;
+        }
+        if (dryRun) {
+            out.planned.push_back(f.remedy);
+            continue;
+        }
+        // Said out loud for the reason repair_payloads_ documents: in agent
+        // and TUI mode platform::exec silences the child, so an install that
+        // downloads is an indefinite silent wait.
+        if (onStep) {
+            onStep(std::format("reinstalling {} (may download)",
+                               xvm::display_coordinate(f.target, f.version)));
+        }
+        if (run(f.remedy + quiet_suffix()) == 0) {
+            out.notes.emplace_back(glyph::mark(glyph::bullet, "reinstalled"),
+                                   xvm::display_coordinate(f.target, f.version));
+        } else {
+            out.failedEntries.emplace_back(f.target, f.version);
+            out.notes.emplace_back(
+                glyph::mark(glyph::failed, "reinstall failed"),
+                std::format("{} — run `{}` to see why",
+                            xvm::display_coordinate(f.target, f.version),
+                            f.remedy));
+        }
+    }
+}
+
+// The last rung: drop a registration that is provably dead.
+//
+// Runs after the ladder and after a reload, on findings that SURVIVED it. That
+// ordering is the whole safety argument -- pruning is not a guess about
+// whether an entry could be revived, it is what is left once the attempt to
+// revive it has been made and has failed.
+//
+// Three things have to be true, and re-detection has already established the
+// first two:
+//   - the payload is gone, or present with nothing runnable in it and no
+//     release to anchor. There is nothing to lose that has not already been
+//     lost.
+//   - the repair ladder ran and the finding is still there.
+//   - nothing else in the home still resolves through it. The workspace entry
+//     and the installed[] entry go with it, in the same transaction, or the
+//     prune would trade a broken payload for a dangling pointer.
+//
+// What it buys: the eleven `repair skipped` and nine `repair failed` lines on
+// the measured home -- entries whose namespace index no longer exists, and
+// aliases a foreign platform registered -- stop coming back on every run, and
+// the migration marker can finally land.
+void prune_dead_registrations_(const DoctorState& st, const Scan& remaining,
+                               RepairReport& out) {
+    std::vector<std::pair<std::string, std::string>> victims;
+    for (const auto& f : remaining.findings) {
+        if (f.kind != FindingKind::BrokenPayload) continue;
+        // Not if another subos still claims it.
+        //
+        // A BrokenPayload finding means THIS subos claims the entry; it does
+        // not mean this subos is alone. Dropping a version another subos has
+        // active turns a broken payload over there into an active pointer at
+        // nothing over there -- trading a repairable state for a worse one, in
+        // a subos the user is not even in. Caught by the multi-subos e2e,
+        // which pruned a version `other` was still using and then exited 0.
+        const auto owner = xvm::subos_ownership(
+            st.ws, st.wsInstalled, st.otherSubos, f.target, f.version);
+        if (!owner.otherSubos.empty()) {
+            std::string list;
+            for (const auto& other : owner.otherSubos) {
+                if (!list.empty()) list += ", ";
+                list += other;
+            }
+            out.notes.emplace_back(glyph::mark(glyph::failed, "kept"), std::format(
+                "{} could not be restored, but subos {} still uses it — "
+                "repair or remove it there",
+                xvm::display_coordinate(f.target, f.version), list));
+            out.failedEntries.emplace_back(f.target, f.version);
+            continue;
+        }
+        victims.emplace_back(f.target, f.version);
+    }
+    if (victims.empty()) return;
+
+    auto lock = xvm::acquire_state_lock(Config::paths().homeDir);
+    if (!lock) {
+        out.notes.emplace_back(glyph::mark(glyph::failed, "prune"), std::format(
+            "cannot drop dead registrations: {}", lock.error()));
+        for (const auto& victim : victims) out.failedEntries.push_back(victim);
+        return;
+    }
+    Config::reload_state();
+    auto& db = Config::versions_mut();
+    auto& ws = Config::workspace_mut();
+    auto& installed = Config::workspace_installed_mut();
+
+    std::size_t dropped = 0;
+    for (const auto& [target, version] : victims) {
+        const auto infoIt = db.find(target);
+        if (infoIt == db.end()) continue;
+        if (infoIt->second.versions.erase(version) == 0) continue;
+        ++dropped;
+        out.notes.emplace_back(glyph::mark(glyph::bullet, "dropped"), std::format(
+            "{} — its payload is gone and nothing can restore it",
+            xvm::display_coordinate(target, version)));
+
+        if (const auto wit = ws.find(target);
+            wit != ws.end() && wit->second == version) {
+            ws.erase(wit);
+        }
+        if (const auto iit = installed.find(target); iit != installed.end()) {
+            std::erase(iit->second, version);
+            if (iit->second.empty()) installed.erase(iit);
+        }
+        // Edges into the removed version would outlive it and make every
+        // release it touched unresolvable.
+        for (auto& [_, info] : db) {
+            for (auto edgeIt = info.bindings.begin();
+                 edgeIt != info.bindings.end();) {
+                if (edgeIt->first == target) {
+                    std::erase_if(edgeIt->second, [&](const auto& edge) {
+                        return edge.second == version;
+                    });
+                }
+                if (edgeIt->second.empty()) {
+                    edgeIt = info.bindings.erase(edgeIt);
+                } else {
+                    ++edgeIt;
+                }
+            }
+        }
+        if (infoIt->second.versions.empty()) {
+            db.erase(infoIt);
+        }
+    }
+    if (dropped > 0) {
+        Config::save_versions();
+        Config::save_workspace();
+        out.pruned += static_cast<int>(dropped);
+    }
+}
+
+Counts count_(const Scan& scan) {
+    Counts c;
+    std::set<std::string> aliasTargets;
+    std::set<std::string> bakedTargets;
+    for (const auto& f : scan.findings) {
+        switch (f.kind) {
+            case FindingKind::MissingShim:     ++c.missing; break;
+            case FindingKind::OrphanShim:
+                // An anchor shim is Notice-level: the file is useless but
+                // its presence is not the user's doing, and it must not set
+                // the exit code. --fix still removes it.
+                if (f.level != FindingLevel::Notice) ++c.orphans;
+                break;
+            case FindingKind::LegacyAliasShim: ++c.orphans; break;
+            case FindingKind::BrokenPayload:   ++c.broken;  break;
+            case FindingKind::ForeignPayload:  ++c.foreignPayloads; break;
+            case FindingKind::ShimAnchor: ++c.warnings; break;
+            // Counted per TARGET, because that is how they are printed. A
+            // count that does not match the list is the shape the old summary
+            // had -- "broken payloads 1" with nothing in the list to explain
+            // it -- and it sends people looking for a line that is not there.
+            // An alias that a host command satisfies is a Notice and counts
+            // as nothing; one that resolves nowhere is an Error and counts as
+            // an issue. They used to be the same warning, which is how a real
+            // break stayed invisible inside thirty-four false ones.
+            case FindingKind::AliasUnresolved:
+                if (f.level != FindingLevel::Error) break;
+                if (aliasTargets.insert(f.target).second) ++c.aliasBroken;
+                break;
+            case FindingKind::ReleaseAnchor:   break;
+            case FindingKind::InactiveInstalled: ++c.inactive; break;
+            // Per TARGET, matching how they are printed (see render_).
+            case FindingKind::SubosPathBaked:
+                if (bakedTargets.insert(f.target).second) ++c.warnings;
+                break;
+            case FindingKind::SysrootDangling: ++c.warnings; break;
+            case FindingKind::BindingState:
+                if (f.level != FindingLevel::Notice) ++c.binding;
+                break;
+            case FindingKind::OtherSubos:      ++c.otherSubos; break;
+            case FindingKind::LoaderLibcSplit:
+                // Counted as broken, so it reaches the exit code. A finding
+                // that prints and then exits 0 is how a check gets ignored by
+                // every script that wraps it.
+                ++c.broken;
+                break;
+            case FindingKind::NssResolution:
+                // Only the failing one counts. The passing case is a Notice
+                // that exists to say the cell RAN -- counting it would make a
+                // healthy home report a problem, and a cell that cries wolf
+                // gets read as noise by the second week.
+                if (f.level == FindingLevel::Error) ++c.broken;
+                break;
+            case FindingKind::SubosDoubleBinding:
+                // Counted for the same reason, and for a second one: `healed`
+                // is computed as before-minus-after over this count, so an
+                // uncounted finding that --fix repairs reports "healed 0" --
+                // repair and report disagreeing about whether anything
+                // happened.
+                ++c.broken;
+                break;
+            // The three below were Error-level and absent from this switch, so
+            // doctor printed `✗ subos env orphan …` and then exited 0. Two
+            // consequences, and the second is the quieter one:
+            //
+            //   1. every script wrapping `xlings self doctor` saw success;
+            //   2. `healed` is before-minus-after over this count, so --fix
+            //      repairing an orphan reported "healed 0" -- the repairer
+            //      acted and the reporter said nothing. That is the
+            //      reporter/repairer split this repo has produced three times,
+            //      arrived at from the counting side rather than the
+            //      predicate side.
+            case FindingKind::SubosManifest:
+            case FindingKind::SubosEnvOrphan:
+            case FindingKind::SubosEnvUnresolved:
+                ++c.broken;
+                break;
+            case FindingKind::SubosEnvConflict:
+                ++c.warnings;
+                break;
+            case FindingKind::SubosRuntimeMissing:
+                if (f.level == FindingLevel::Error) ++c.broken;
+                else ++c.warnings;
+                break;
+            case FindingKind::IncompletePayload:
+                // Counted as broken for both reasons the comment above gives:
+                // it must reach the exit code, and `healed` is computed as
+                // before-minus-after over this count, so an uncounted finding
+                // that --fix repairs reports "healed 0".
+                ++c.broken;
+                break;
+            case FindingKind::UnverifiedPayload:
+                // Counts as nothing, on purpose. It is a Notice about state we
+                // could not observe, not a defect we found -- and a home with
+                // 29 of them exiting non-zero would train everyone to ignore
+                // the command. The line still prints, with the command that
+                // settles it.
+                break;
+            case FindingKind::EntryBinaryDrift:
+                // Counts as nothing either: both shapes it reports are states
+                // a user may have chosen on purpose. It must be visible, not
+                // fatal.
+                break;
+        }
+    }
+    return c;
+}
+
+void render_(const Scan& scan, const RepairReport& repair, bool fix,
+             bool dryRun, bool verbose, EventStream& stream) {
+    nlohmann::json fields = nlohmann::json::array();
+    const auto add = [&](std::string_view label, std::string value,
+                         bool hl = false) {
+        fields.push_back({{"label", std::string(label)},
+                          {"value", std::move(value)},
+                          {"highlight", hl}});
+    };
+
+    const auto counts = count_(scan);
+
+    // Broken payloads, one line per payload rather than one per program.
+    //
+    // A missing payload directory takes out every program registered against
+    // it. On the measured home that is nine lines for llvm and three each for
+    // two virtualbox entries -- twenty lines describing four problems, with
+    // twenty remedies of which four were distinct.
+    std::map<std::string, std::vector<const Finding*>> payloadGroups;
+    std::vector<std::string> groupOrder;
+    for (const auto& f : scan.findings) {
+        if (f.kind != FindingKind::BrokenPayload
+            && f.kind != FindingKind::ForeignPayload) continue;
+        auto [it, inserted] = payloadGroups.try_emplace(f.groupKey);
+        if (inserted) groupOrder.push_back(f.groupKey);
+        it->second.push_back(&f);
+    }
+    for (const auto& key : groupOrder) {
+        const auto& group = payloadGroups.at(key);
+        const auto* head = group.front();
+        const bool foreign = head->kind == FindingKind::ForeignPayload;
+        std::string label = foreign
+            ? glyph::mark(glyph::failed,
+                          std::format("broken payload [subos: {}]",
+                          [&] {
+                              std::string list;
+                              for (const auto& s : head->subos) {
+                                  if (!list.empty()) list += ", ";
+                                  list += s;
+                              }
+                              return list;
+                          }()))
+            : (std::ranges::any_of(group, [](const Finding* f) {
+                   return f->active;
+               }) ? glyph::mark(glyph::failed, "broken payload [active]")
+                  : glyph::mark(glyph::failed, "broken payload"));
+
+        std::string detail = head->detail;
+        if (group.size() > 1) {
+            std::string names;
+            for (const auto* f : group) {
+                if (!names.empty()) names += ", ";
+                names += f->target;
+            }
+            detail += std::format("\n    {} programs from this payload: {}",
+                                  group.size(), names);
+        }
+        add(label, std::move(detail));
+        if (!head->remedy.empty()) {
+            add("  " + glyph::mark(glyph::remedy, "run"), head->remedy);
+        } else {
+            // No command would help. Saying that is the useful output; a
+            // plausible-looking `xlings install <target>` is not.
+            add("  " + glyph::mark(glyph::note, "no remedy"), fix
+                ? std::string("no package provides this entry — the "
+                              "registration was dropped")
+                : std::string("no package in any index provides this entry; "
+                              "`--fix` will drop the registration"));
+        }
+    }
+
+    // Everything else, in a stable order.
+    std::set<std::string> aliasTargetsShown;
+    std::map<std::string, int> aliasVersionCount;
+    std::set<std::string> bakedTargetsShown;
+    std::map<std::string, int> bakedVersionCount;
+    for (const auto& f : scan.findings) {
+        // Errors only: the "+N other version(s)" suffix is printed on an
+        // error line, so counting notices into it would inflate a number the
+        // user cannot see the rest of.
+        if (f.kind == FindingKind::AliasUnresolved
+            && f.level == FindingLevel::Error) ++aliasVersionCount[f.target];
+        else if (f.kind == FindingKind::SubosPathBaked) ++bakedVersionCount[f.target];
+    }
+    for (const auto& f : scan.findings) {
+        switch (f.kind) {
+            case FindingKind::MissingShim:
+                add(glyph::mark(glyph::failed, "missing shim"), f.detail); break;
+            case FindingKind::OrphanShim:
+                if (f.level == FindingLevel::Notice) {
+                    if (verbose) add(glyph::mark(glyph::note, "anchor shim"), f.detail);
+                } else {
+                    add(glyph::mark(glyph::failed, "orphan shim"), f.detail);
+                }
+                break;
+            case FindingKind::LegacyAliasShim:
+                add(glyph::mark(glyph::failed, "legacy alias shim"), f.detail); break;
+            case FindingKind::InactiveInstalled:
+                add(glyph::mark(glyph::failed, "no active version"), f.detail);
+                // Printed before the remedy, because it changes what the
+                // remedy means: not "run this to fix it" but "run this to
+                // choose this package over that one".
+                if (!f.conflict.empty()) {
+                    add("  " + glyph::mark(glyph::warn, "conflict"),
+                        std::format("{} — `--fix` will not choose between "
+                                    "them", f.conflict));
+                }
+                add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
+                break;
+            case FindingKind::ShimAnchor:
+                add(glyph::mark(glyph::warn, "shim anchor"), f.detail); break;
+            case FindingKind::AliasUnresolved:
+                // One line per TARGET, not per version. The alias is a
+                // property of the recipe, so every version of a package
+                // registers the same one and reports the same way -- five
+                // identical `claude` lines on the measured home. Collapsing
+                // the repeats is the fix; hiding the category is not, because
+                // a genuinely missing alias binary is the only signal there
+                // is.
+                //
+                // The Notice level is "a host command answers this", which is
+                // a portability fact rather than a defect. It is summarised
+                // like the other notices and printed only under `--all`, so
+                // the Error level -- an alias with nothing to exec anywhere --
+                // is the only thing this category shows by default. That is
+                // the whole point of splitting it: the error used to be one
+                // line among thirty-four identical-looking warnings.
+                if (f.level == FindingLevel::Notice) {
+                    if (verbose) {
+                        add(glyph::mark(glyph::note, "host alias"), f.detail);
+                    }
+                    break;
+                }
+                if (verbose || aliasTargetsShown.insert(f.target).second) {
+                    add(glyph::mark(glyph::failed, "alias unresolved"), verbose ? f.detail
+                        : std::format("{}{}", f.detail,
+                            aliasVersionCount.at(f.target) > 1
+                                ? std::format("  (+{} other version(s))",
+                                              aliasVersionCount.at(f.target) - 1)
+                                : std::string{}));
+                }
+                break;
+            case FindingKind::SysrootDangling:
+                add(glyph::mark(glyph::warn, "dangling sysroot link"), f.detail);
+                // A link in ANOTHER subos is reported here and repaired
+                // there, so the generic "run `xlings self doctor --fix`"
+                // footer is wrong for it -- that command, from here, will
+                // leave it exactly where it is. Name the one that works.
+                if (!f.subos.empty() && !f.remedy.empty()) {
+                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
+                }
+                break;
+            case FindingKind::SubosPathBaked:
+                // One line per TARGET. A single gcc install bakes the path
+                // into fourteen registrations (gcc, g++, cc, c++ and the
+                // triple-prefixed spellings, times two versions), and
+                // fourteen identical lines bury everything else -- the same
+                // reason `alias unresolved` collapses.
+                if (verbose || bakedTargetsShown.insert(f.target).second) {
+                    add(glyph::mark(glyph::warn, "subos path"), verbose
+                        ? f.detail
+                        : std::format("{}{}", f.detail,
+                            bakedVersionCount.at(f.target) > 1
+                                ? std::format("  (+{} other registration(s))",
+                                              bakedVersionCount.at(f.target) - 1)
+                                : std::string{}));
+                }
+                break;
+            case FindingKind::BindingState:
+                if (f.level == FindingLevel::Notice) {
+                    if (verbose) add(glyph::mark(glyph::note, "binding state"), f.detail);
+                } else {
+                    add(glyph::mark(glyph::failed, "binding state"), f.detail);
+                }
+                break;
+            case FindingKind::OtherSubos:
+                if (verbose || f.level != FindingLevel::Notice) {
+                    add(f.level == FindingLevel::Notice ? glyph::mark(glyph::note, "other subos")
+                                                        : glyph::mark(glyph::warn, "other subos"),
+                        f.detail);
+                }
+                break;
+            case FindingKind::ReleaseAnchor:
+                if (verbose) add(glyph::mark(glyph::note, "release anchor"), f.detail);
+                break;
+            case FindingKind::SubosManifest:
+                add(glyph::mark(glyph::failed, "subos manifest"), f.detail);
+                // The remedy for an unreadable file is not `--fix`, so it has
+                // to be printed rather than left to the generic footer.
+                if (!f.remedy.empty() && f.remedy != "xlings self doctor --fix")
+                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
+                break;
+            case FindingKind::SubosEnvOrphan:
+                add(glyph::mark(glyph::failed, "subos env orphan"), f.detail);
+                break;
+            case FindingKind::SubosDoubleBinding:
+                // Not collapsed into a count: which versions are bound is the
+                // finding, and there is at most a handful.
+                add(glyph::mark(glyph::failed, "subos double binding"), f.detail);
+                if (!f.remedy.empty())
+                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
+                break;
+            case FindingKind::SubosEnvUnresolved:
+                add(glyph::mark(glyph::failed, "subos env unresolved"), f.detail);
+                if (!f.remedy.empty())
+                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
+                break;
+            case FindingKind::SubosEnvConflict:
+                // Never collapsed into a count, unlike the notice categories:
+                // there is one per contested variable, the number is small,
+                // and which packages disagree is the whole content.
+                add(glyph::mark(glyph::warn, "subos env conflict"), f.detail);
+                break;
+            case FindingKind::SubosRuntimeMissing:
+                add(f.level == FindingLevel::Error
+                        ? glyph::mark(glyph::failed, "subos runtime")
+                        : glyph::mark(glyph::warn, "subos runtime"),
+                    f.detail);
+                if (!f.remedy.empty())
+                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
+                break;
+            case FindingKind::LoaderLibcSplit:
+                // Not collapsed into a count, and never abbreviated: the two
+                // paths ARE the finding. A reader who gets only "1 problem"
+                // has to reproduce the whole investigation this check exists
+                // to remove.
+                add(glyph::mark(glyph::failed, "loader/libc split"), f.detail);
+                if (!f.remedy.empty())
+                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
+                break;
+            case FindingKind::NssResolution:
+                add(f.level == FindingLevel::Error
+                        ? glyph::mark(glyph::failed, "nss resolution")
+                        : glyph::mark(glyph::done, "nss resolution"),
+                    f.detail);
+                break;
+            case FindingKind::IncompletePayload:
+                add(glyph::mark(glyph::failed, "incomplete install"), f.detail);
+                if (!f.remedy.empty())
+                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
+                break;
+            case FindingKind::UnverifiedPayload:
+                // Summarised into one counted line when not verbose -- see
+                // below. Twenty-nine of these would bury everything else,
+                // which is the failure mode the notice-collapsing block
+                // downstream was built for.
+                if (verbose) {
+                    add(glyph::mark(glyph::note, "unverified install"),
+                        f.detail);
+                    if (!f.remedy.empty())
+                        add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
+                }
+                break;
+            case FindingKind::EntryBinaryDrift:
+                // Printed in full, always -- NOT collapsed into the notice
+                // summary. There are at most two of these, and each one
+                // describes the single file every other tool in the home is
+                // dispatched through; a collapsed count would say "1 notice"
+                // about the fact that explains everything else on the page.
+                add(glyph::mark(glyph::note, "entry binary"), f.detail);
+                if (!f.remedy.empty())
+                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
+                break;
+            default: break;
+        }
+    }
+
+    // Notices that are not defects get one counted line unless asked for.
+    // Thirty `release anchor` lines saying "nothing is wrong here" is how the
+    // four lines that matter got lost.
+    if (!verbose) {
+        int anchors = 0, anchorShims = 0, bindingNotices = 0, subosNotices = 0;
+        int unverified = 0;
+        // Per TARGET, like the warning line it replaced: one package's alias
+        // is one fact however many versions of it are registered.
+        std::set<std::string> hostAliasTargets;
+        for (const auto& f : scan.findings) {
+            if (f.kind == FindingKind::UnverifiedPayload) ++unverified;
+            else if (f.kind == FindingKind::ReleaseAnchor) ++anchors;
+            else if (f.kind == FindingKind::OrphanShim
+                     && f.level == FindingLevel::Notice) ++anchorShims;
+            else if (f.kind == FindingKind::BindingState
+                     && f.level == FindingLevel::Notice) ++bindingNotices;
+            else if (f.kind == FindingKind::OtherSubos
+                     && f.level == FindingLevel::Notice) ++subosNotices;
+            else if (f.kind == FindingKind::AliasUnresolved
+                     && f.level == FindingLevel::Notice) {
+                hostAliasTargets.insert(f.target);
+            }
+        }
+        std::string summary;
+        const auto part = [&](int n, std::string_view what) {
+            if (n == 0) return;
+            if (!summary.empty()) {
+                summary += std::format(" {} ", std::string(glyph::bullet));
+            }
+            summary += std::format("{} {}", n, what);
+        };
+        part(anchors, "release anchor");
+        part(static_cast<int>(hostAliasTargets.size()), "host alias");
+        part(anchorShims, "anchor shim");
+        part(bindingNotices, "binding notice");
+        part(subosNotices, "other-subos notice");
+        part(unverified, "unverified install");
+        if (!summary.empty()) {
+            add(glyph::mark(glyph::note, "nothing to do"), summary + "  —  `--all` to list them");
+        }
+    }
+
+    for (const auto& [label, text] : repair.notes) add(label, text);
+    for (const auto& planned : repair.planned) add(glyph::mark(glyph::remedy, "would run"), planned);
+    if (dryRun) {
+        add("dry run", std::format(
+            "{} action(s) planned; nothing was changed",
+            repair.planned.size()), true);
+    }
+
+    if (counts.issues() == 0 && counts.warnings == 0
+        && counts.foreignPayloads == 0 && counts.otherSubos == 0) {
+        add("status", "OK — workspace, shims, and payloads are all consistent",
+            true);
+    } else {
+        if (counts.missing > 0)
+            add("missing shims", std::to_string(counts.missing));
+        if (counts.orphans > 0)
+            add("orphan shims", std::to_string(counts.orphans));
+        if (counts.broken > 0)
+            add("broken payloads", std::to_string(counts.broken));
+        if (counts.binding > 0)
+            add("binding state", std::to_string(counts.binding));
+        if (counts.inactive > 0)
+            add("no active version", std::to_string(counts.inactive));
+        if (counts.aliasBroken > 0)
+            add("unresolvable aliases", std::to_string(counts.aliasBroken));
+        if (counts.warnings > 0)
+            add("warnings", std::to_string(counts.warnings));
+        // Reported apart from the counts above because they are apart from the
+        // exit code: they belong to a subos this run is not in.
+        if (counts.foreignPayloads > 0)
+            add("owned by another subos", std::format(
+                "{} — repair them there", counts.foreignPayloads));
+        if (counts.otherSubos > 0)
+            add("other subos findings", std::to_string(counts.otherSubos));
+    }
+
+    if (fix) {
+        if (repair.healed > 0)
+            add("healed", std::to_string(repair.healed), true);
+        if (repair.pruned > 0)
+            add("pruned", std::to_string(repair.pruned), true);
+        if (counts.issues() > 0)
+            add("hint", "some findings remain — see the reasons above", true);
+    } else if (counts.issues() > 0 || counts.otherSubos > 0) {
+        add("hint", "run `xlings self doctor --fix` to repair", true);
+    }
+
+    // The nudge, for a home an older client set up. Last field of the same
+    // panel rather than a panel of its own: a second panel renders its own
+    // (empty) header, which reads as a broken frame rather than a footnote.
+    // Gated on the recorded version differing from the running one, which is
+    // what makes a successful `--fix` turn it off rather than merely quieten
+    // it.
+    if (auto hint = migration_hint(Config::recorded_client_version(),
+                                   Info::VERSION)) {
+        add(glyph::mark(glyph::note, "migration"), *hint);
+    }
+
+    nlohmann::json payload;
+    payload["title"]  = "xlings self doctor";
+    payload["fields"] = std::move(fields);
+    stream.emit(DataEvent{"info_panel", payload.dump()});
+}
+
+int cmd_doctor(EventStream& stream, bool fix, bool resetMetadata, bool dryRun, bool verbose, bool deep, std::optional<std::string> scope) {
+    // `--fix` implies `--deep`. Deliberate and load-bearing: the repair must
+    // be able to act on findings only the payload audit produces, and
+    // self_doctor_depth_test asserts it ("--fix retains the historical deep
+    // detection surface").
+    //
+    // It is also expensive. Measured on a 124-package / 71 GB home: plain
+    // `self doctor` 0.75s, `--fix --dry-run` 148-191s WITHOUT repairing
+    // anything, because the audit walks every package at every version. That
+    // cost is what makes `--fix` look dead, and the progress below is the
+    // answer to THAT -- the user's complaint was silence, not duration.
+    //
+    // Decoupling the two would trade the wait for a quieter problem: a `--fix`
+    // that no longer detects what only a deep scan finds. Getting the speed
+    // without that trade means making the audit itself cheap -- payload
+    // directories are immutable, so their scan results are cacheable by path
+    // and mtime -- which is a separate change with its own risk surface.
+    // See .agents/docs/2026-08-10-doctor-fix-hang-and-537.md (D2 vs D3).
+    const bool deepAudit = deep || fix;
+    if (scope && !deepAudit) {
+        stream.emit(ErrorEvent{
+            .code = ErrorCode::InvalidInput,
+            .message = "`--scope` requires `--deep` (or `--fix`, which implies it)",
+            .recoverable = false,
+        });
+        return 2;
+    }
+
+    // Announce the boundary before catalog evaluation or payload walking. A
+    // deep audit can legitimately take time on a large store; silence before
+    // the first result is indistinguishable from the hang this mode replaces.
+    if (deepAudit) {
+        // `--scope` narrows the payload/runtime AUDIT. Every other check, and
+        // every repair `--fix` performs, still covers the whole home -- so the
+        // announce line says which, rather than letting the reader infer that
+        // the run is confined to one package.
+        stream.emit(LogEvent{
+            LogLevel::info,
+            scope
+                ? std::format("deep audit scope: {} "
+                              "(payload/runtime audit only; other checks and "
+                              "repairs still cover this home)", *scope)
+                : std::string("deep audit scope: all installed payloads"),
+        });
+        std::cout.flush();
+    }
+
+    std::optional<xim::PackageCatalog> localCatalog;
+    AuditSelection audit{.deep = deepAudit};
+    // Both kinds, deliberately: the plain CLI renders LogEvent and ignores
+    // ProgressEvent, while the TUI and the agent protocol consume
+    // ProgressEvent and would show nothing for a LogEvent. Emitting one leaves
+    // the other with the silence this exists to remove.
+    audit.onProgress = [&stream](std::size_t done, std::size_t total,
+                                 std::string_view target, std::string_view version) {
+        stream.emit(ProgressEvent{
+            .phase = "auditing",
+            .percent = total ? static_cast<float>(done) / static_cast<float>(total) : 0.0f,
+            .message = std::format("auditing payloads {}/{}", done, total),
+        });
+        stream.emit(LogEvent{
+            LogLevel::info,
+            std::format("auditing payloads {}/{} — {}@{}", done, total, target, version),
+        });
+        std::cout.flush();
+    };
+    // The catalog is needed by the REPAIR, not only by the audit — it is how a
+    // broken payload's owning package is found so `xlings install` can be run
+    // against it. Gating it on `deepAudit` alone was the bug in the first cut
+    // of this change: decoupling `--fix` from `--deep` silently took the
+    // catalog away too, and `--fix` stopped repairing a payload whose
+    // directory was simply gone. Caught by self_doctor_test S8b, which asserts
+    // the repair by looking at the filesystem rather than at what doctor
+    // claimed — which is why it could catch it at all.
+    if (deepAudit || fix) {
+        localCatalog.emplace();
+        const auto rebuilt = localCatalog->rebuild();
+        if (!rebuilt) {
+            if (scope) {
+                stream.emit(ErrorEvent{
+                    .code = ErrorCode::InvalidInput,
+                    .message = std::format(
+                        "cannot resolve deep audit scope '{}': {}",
+                        *scope, rebuilt.error()),
+                    .recoverable = false,
+                });
+                return 2;
+            }
+            localCatalog.reset();
+        } else if (scope) {
+            auto resolved = localCatalog->resolve_target(
+                *scope, std::string(platform::build_os()));
+            if (!resolved) {
+                stream.emit(ErrorEvent{
+                    .code = ErrorCode::InvalidInput,
+                    .message = std::format(
+                        "deep audit scope '{}' is missing or ambiguous: {}",
+                        *scope, resolved.error()),
+                    .recoverable = false,
+                });
+                return 2;
+            }
+            const auto payloadDir = audit_payload_dir_(*resolved);
+            std::error_code ec;
+            if (!fs::is_directory(payloadDir, ec)
+                || !xim::payload_has_content(payloadDir)) {
+                stream.emit(ErrorEvent{
+                    .code = ErrorCode::InvalidInput,
+                    .message = std::format(
+                        "deep audit scope '{}' has no local payload at {}",
+                        *scope, Config::display_path(payloadDir)),
+                    .recoverable = false,
+                });
+                return 2;
+            }
+            audit.scope = std::move(*resolved);
+        }
+    }
+
+    // One in-process probe cache for the whole command. The same candidate is
+    // asked about once per finding it owns and again after repair passes.
+    std::map<std::string, bool> probed;
+    std::string client = "xlings";
+    {
+        const auto self = platform::get_executable_path().string();
+        if (!self.empty() && is_shell_safe_token(self)) client = self;
+    }
+    const CoordinateProbe probe =
+        [&](const xvm::InstallCoordinate& coord) {
+            const auto key = coord.canonical();
+            if (const auto it = probed.find(key); it != probed.end()) {
+                return it->second;
+            }
+            const bool ok = localCatalog
+                && xim::resolve_local_coordinate(*localCatalog, key).has_value();
+            probed.emplace(key, ok);
+            return ok;
+        };
+
+    auto state = load_state_();
+
+    // --reset-metadata runs before detection: an entry whose group is
+    // unreadable makes its release unresolvable, which detection would
+    // otherwise report as a different problem. It is the one repair that loses
+    // information, which is why it has its own flag.
+    RepairReport repair;
+    if (resetMetadata) {
+        if (auto reset = xvm::plan_metadata_reset(state.db); !reset.empty()) {
+            auto lock = xvm::acquire_state_lock(Config::paths().homeDir);
+            if (!lock) {
+                repair.notes.emplace_back(glyph::mark(glyph::failed, "binding state"), std::format(
+                    "cannot reset binding metadata: {}", lock.error()));
+            } else {
+                Config::reload_state();
+                auto& mutableDb = Config::versions_mut();
+                const auto replanned = xvm::plan_metadata_reset(mutableDb);
+                if (xvm::apply_metadata_reset(mutableDb, replanned) > 0) {
+                    Config::save_versions();
+                    for (const auto& entry : replanned.entries) {
+                        std::string codes;
+                        for (const auto& code : entry.codes) {
+                            if (!codes.empty()) codes += ", ";
+                            codes += code;
+                        }
+                        // Name what was discarded. This is the one repair that
+                        // loses information, so a bare count would be the
+                        // wrong report.
+                        repair.notes.emplace_back(glyph::mark(glyph::bullet, "metadata reset"),
+                            std::format(
+                                "{} dropped its release metadata ({}) and is "
+                                "now switchable on its own — reinstall it to "
+                                "restore the release",
+                                xvm::display_coordinate(entry.target,
+                                                        entry.version),
+                                codes));
+                    }
+                }
+            }
+        }
+        state = load_state_();
+    }
+
+    auto scan = detect_(state, probe, audit);
+
+    if (!fix) {
+        render_(scan, repair, fix, dryRun, verbose, stream);
+            return count_(scan).issues() == 0 ? 0 : 1;
+    }
+
+    const int before = count_(scan).issues();
+
+    const CommandRunner run = [](const std::string& cmd) {
+        return platform::exec(cmd);
+    };
+
+    if (dryRun) {
+        repair_payloads_(state, scan, probe, /*dryRun=*/true, repair);
+        repair_incomplete_(scan, run, /*dryRun=*/true, repair);
+        repair_inactive_(scan, client, run, /*dryRun=*/true, repair);
+        render_(scan, repair, fix, dryRun, verbose, stream);
+            return count_(scan).issues() == 0 ? 0 : 1;
+    }
+
+    // Re-read and re-detect between phases.
+    //
+    // Not a precaution: the payload repairs run in SUBPROCESSES that write the
+    // state file, while this process still holds the copy it read at startup.
+    // Without the reload, a cure that is purely a re-registration -- which is
+    // what the ladder mostly does -- reads as a failure, and only repairs that
+    // happened to restore a directory on disk appear to work.
+    const auto refresh = [&] {
+        Config::reload_state();
+        state = load_state_();
+        scan  = detect_(state, probe, audit);
+    };
+
+    // Phase 1: the cheap metadata repairs, BEFORE the ladder.
+    //
+    // A dangling edge is not only a finding of its own -- it makes its
+    // release unresolvable, and registration validates the whole release. So
+    // an unpruned edge makes `xlings install` refuse, which is the ladder's
+    // R2 failing for a reason the ladder cannot see and R3 then reacting to by
+    // removing a working package. Clearing them first is what lets the install
+    // that follows actually succeed.
+    repair_state_(repair);
+    repair_other_subos_(state, repair);
+    repair_local_(state, scan, repair);
+    refresh();
+
+    // Phase 2: the payload ladder.
+    const auto announce = [&stream](std::string_view msg) {
+        stream.emit(LogEvent{LogLevel::info, std::string(msg)});
+        std::cout.flush();
+    };
+    repair_payloads_(state, scan, probe, /*dryRun=*/false, repair, announce);
+    refresh();
+
+    // Phase 2b: payloads whose own stamp records a failed install.
+    //
+    // After the ladder and after a reload, so a payload the ladder already
+    // reinstalled is no longer reported here -- the refresh above re-reads the
+    // stamp, and a successful install overwrites the failure marker.
+    repair_incomplete_(scan, run, /*dryRun=*/false, repair, announce);
+    refresh();
+
+
+    // Phase 3: the cheap repairs again, on what the ladder left behind.
+    //
+    // Re-registering a package creates state: shims for programs that are
+    // registered but not active, and a release whose members are not all
+    // active because the entry point already was. Both are things phase 1
+    // repairs -- they just did not exist yet when phase 1 ran. Measured: one
+    // llvm re-registration produced 29 orphan shims and 29 incoherent-release
+    // findings that a single-pass repair reported as unfixed.
+    repair_state_(repair);
+    repair_local_(state, scan, repair);
+    refresh();
+
+    // Phase 3.5: activate what is installed and inactive.
+    //
+    // LAST among the repairs that write the workspace, and that placement is
+    // the fix for a real bug rather than a preference. It used to run before
+    // the final `repair_state_`, so it activated a release and the
+    // deactivation repair immediately afterwards took down whatever that
+    // activation had knocked out of step -- the two traded the workspace back
+    // and forth and `--fix` ended with more issues than it began with
+    // (2026.8.1.1, measured: `gcc` and `ld` left with no active version).
+    //
+    // Running last means every teardown has already settled, so this acts on a
+    // workspace nothing else is about to rewrite. The preflight in detection
+    // (activation_conflict_) is what stops it from creating a NEW disagreement
+    // for the next run to trip over; the ordering here is what stops it from
+    // being undone within this one.
+    //
+    // Still after the payload ladder for the original reason: a package whose
+    // payload was missing is both broken AND inactive, and `use` on a payload
+    // that is not there fails for a reason the user cannot act on.
+    repair_inactive_(scan, client, run, /*dryRun=*/false, repair);
+    refresh();
+
+    // Phase 4: whatever is STILL a broken payload after the ladder had its
+    // turn is dead. Prune it, then re-detect once more so the report shows the
+    // result rather than the intent.
+    prune_dead_registrations_(state, scan, repair);
+    if (repair.pruned > 0) {
+        refresh();
+        // A prune can orphan a shim of its own -- the entry is gone, the file
+        // is not.
+        repair_local_(state, scan, repair);
+        refresh();
+    }
+
+    const auto after = count_(scan);
+    repair.healed = std::max(0, before - after.issues() - repair.pruned);
+
+    // Did `--fix` actually leave the home better than it found it?
+    //
+    // Nothing asked this until 2026.8.1.2, and the release before it shipped a
+    // repair that undid another one: activating a release stranded members of
+    // a second release, the deactivation repair then took those members down,
+    // and the resulting "installed but inactive" entries were reported as new
+    // findings. `--fix` ended with MORE issues than it started with, having
+    // printed a hundred lines of `deactivated`, and the two repairs would go on
+    // trading the workspace back and forth on every subsequent run.
+    //
+    // This does not fix anything. It is the assertion that makes that class of
+    // bug announce itself on its FIRST run instead of hiding inside a long
+    // successful-looking report. Repairs that can conflict are prevented from
+    // conflicting elsewhere (see the preflight in repair_inactive_); this is
+    // the backstop for the next one nobody predicted.
+    if (after.issues() > before) {
+        repair.regressed = true;
+        repair.notes.emplace_back(
+            glyph::mark(glyph::failed, "not converging"),
+            std::format(
+                "--fix started with {} issue(s) and ended with {} — a repair "
+                "undid another. This is a bug in doctor, not in the home; "
+                "please report it with the output above.",
+                before, after.issues()));
+    }
+
+    // A ladder failure only still counts if the entry it covered is still a
+    // finding somewhere. An entry that was pruned, or that a later phase
+    // cured, is not an outstanding failure -- but one that merely moved to
+    // another subos's ledger IS, which is why this asks the findings rather
+    // than the counters.
+    std::set<std::pair<std::string, std::string>> stillFound;
+    for (const auto& f : scan.findings) {
+        if (f.kind == FindingKind::BrokenPayload
+            || f.kind == FindingKind::ForeignPayload) {
+            stillFound.emplace(f.target, f.version);
+        }
+    }
+    int outstanding = 0;
+    for (const auto& entry : repair.failedEntries) {
+        if (stillFound.contains(entry)) ++outstanding;
+    }
+
+    render_(scan, repair, fix, dryRun, verbose, stream);
+
+    // Stamp the home with the client that just checked it.
+    //
+    // `.xlings.json:version` records which xlings set the home up. Only `self
+    // install` ever wrote it, so `self update` -- which installs xlings@latest
+    // as a package -- left it reading the old version forever. Stamped here it
+    // becomes the migration marker: the hint appears while the home is behind
+    // and stops once a --fix has actually migrated the packages.
+    //
+    // Gated on the repairs this pass OWNS, not on a spotless home. doctor also
+    // reports things --fix is not responsible for -- unresolvable aliases,
+    // shim anchoring, another subos's broken payload -- and requiring zero of
+    // those would mean the marker never lands and the hint nags forever about
+    // a migration that already happened.
+    if (outstanding == 0 && after.foreignPayloads == 0) {
+        Config::record_client_version(std::string(Info::VERSION));
+    }
+
+    return (after.issues() == 0 && outstanding == 0 && !repair.regressed)
+        ? 0 : 1;
+}
+
+}
diff --git a/src/core/xself/doctor.cppm b/src/core/xself/doctor.cppm
index 81a324c3..bcec8e59 100644
--- a/src/core/xself/doctor.cppm
+++ b/src/core/xself/doctor.cppm
@@ -16,13 +16,9 @@ import xlings.core.xself.compat;
 
 import xlings.core.config;
 import xlings.core.glyph;
-import xlings.libs.json;
-import xlings.core.log;
-import xlings.platform;
 import xlings.runtime;
 import xlings.core.elf_same_source;
 import xlings.core.entry_binary;
-import xlings.core.version_order;
 import xlings.core.xvm.types;
 import xlings.core.xvm.bindings;
 import xlings.core.xvm.db;
@@ -294,107 +290,6 @@ constexpr std::string_view shim_ext_ = ".exe";
 constexpr std::string_view shim_ext_ = "";
 #endif
 
-std::string shim_filename_(const std::string& name) {
-    std::string fn = name;
-    if (!shim_ext_.empty() && !fn.ends_with(shim_ext_)) fn += shim_ext_;
-    return fn;
-}
-
-DoctorState load_state_() {
-    auto& p = Config::paths();
-    DoctorState st;
-    st.db          = Config::versions();
-    st.ws          = Config::effective_workspace();
-    st.wsInstalled = Config::workspace_installed();
-    st.homeStr     = p.homeDir.string();
-
-    // The other subos of this home.
-    //
-    // Everything doctor checks above the DB layer is scoped to the subos it
-    // runs in -- its binDir, its sysroot, its workspace. The versions DB and
-    // the payload store below are shared by every subos. Identified by
-    // directory, not by name: a project subos may be named the same as one
-    // under the home, and excluding the wrong one would make this subos audit
-    // itself as a foreigner.
-    std::error_code cec;
-    const auto here = fs::weakly_canonical(p.subosDir, cec);
-    for (auto& snapshot : profile::load_subos_snapshots(p.homeDir)) {
-        std::error_code sec;
-        if (fs::weakly_canonical(snapshot.dir, sec) == here) continue;
-        st.otherSubos.push_back(xvm::SubosRef{
-            .subos     = snapshot.name,
-            .active    = snapshot.workspace.active,
-            .installed = snapshot.workspace.installed,
-        });
-        st.otherSnapshots.push_back(std::move(snapshot));
-    }
-
-#ifdef _WIN32
-    st.xlingsBin = p.homeDir / "bin" / "xlings.exe";
-#else
-    st.xlingsBin = p.homeDir / "bin" / "xlings";
-#endif
-    if (!fs::exists(st.xlingsBin)) st.xlingsBin = p.homeDir / "xlings";
-    return st;
-}
-
-// Does this payload ship ANY executable?
-//
-// The discriminator between "a library-only package that xvm typed as a
-// program" and "a program whose binary went missing". `is_binding_root` was
-// doing that job and cannot: it skips the entry itself, so a package that is
-// the sole member of its own release comes back false and gets reported as
-// broken. Reinstalling it can never help, because nothing is wrong.
-//
-// Scanning is confined to the failure path, and shallow: the payload root and
-// bin/, which is where a recipe puts programs.
-bool payload_has_any_executable_(const fs::path& dir) {
-    auto scan = [](const fs::path& d) {
-        std::error_code ec;
-        if (!fs::is_directory(d, ec)) return false;
-        for (auto& e : platform::dir_entries(d)) {
-            std::error_code fec;
-            if (!e.is_regular_file(fec) && !e.is_symlink(fec)) continue;
-#if defined(_WIN32)
-            auto ext = e.path().extension().string();
-            if (ext == ".exe" || ext == ".bat" || ext == ".cmd") return true;
-#else
-            auto st = fs::status(e.path(), fec);
-            if (!fec && (st.permissions() & (fs::perms::owner_exec
-                                             | fs::perms::group_exec
-                                             | fs::perms::others_exec))
-                        != fs::perms::none) {
-                return true;
-            }
-#endif
-        }
-        return false;
-    };
-    return scan(dir) || scan(dir / "bin");
-}
-
-// An alias as the runtime would actually read it.
-//
-// Two things had to be stripped before the "is this an absolute path outside
-// the payload" question could be answered, and neither was:
-//   - surrounding quotes. A recipe that quotes a path containing spaces stores
-//     `"/home/…/claude.exe"`, whose first character is `"`, so is_absolute()
-//     said no and every such entry was reported as an unresolvable alias. Five
-//     of the nine warnings on the measured home were this.
-//   - ${XLINGS_HOME} / @xlings placeholders, which expand to an absolute path
-//     and until then look relative.
-std::string alias_program_(const std::string& aliasCmd,
-                           const std::string& homeStr) {
-    auto sp = aliasCmd.find(' ');
-    std::string prog = (sp == std::string::npos)
-        ? aliasCmd : aliasCmd.substr(0, sp);
-    if (prog.size() >= 2
-        && ((prog.front() == '"'  && prog.back() == '"')
-         || (prog.front() == '\'' && prog.back() == '\''))) {
-        prog = prog.substr(1, prog.size() - 2);
-    }
-    return xvm::expand_path(prog, homeStr);
-}
 
 // ── detection ────────────────────────────────────────────────────────
 
@@ -417,1682 +312,8 @@ struct AuditSelection {
         onProgress;
 };
 
-fs::path audit_payload_dir_(const xim::PackageMatch& match) {
-    return match.storeRoot
-        / xim::package_store_name(match.namespaceName, match.name)
-        / match.version;
-}
-
-// The command that repairs a broken entry, or nothing.
-//
-// A finding names an xvm TARGET; every remedy is a PACKAGE. `xlings install
-// nm@20.1.7` cannot succeed, because no package is called `nm` -- it is a
-// program the llvm package registers. The same goes for `xim-musl-gnu-gcc`
-// (package: `musl-gcc`) and `VBoxHeadless` (package: `virtualbox`). Printing
-// twenty such commands is worse than printing none, because they get run.
-//
-// Candidates come from xvm/owner.cppm in descending order of confidence and
-// each is confirmed against the index before use. Nothing is offered on a
-// guess, and when nothing confirms, the finding says so instead of inventing
-// a command.
-std::optional<xvm::InstallCoordinate>
-owning_coordinate_(const xvm::VersionDB& db,
-                   const std::string& target,
-                   const std::string& version,
-                   const CoordinateProbe& probe) {
-    for (const auto& candidate : xvm::owner_candidates(db, target, version)) {
-        if (probe(candidate)) return candidate;
-    }
-    return std::nullopt;
-}
-
-// Would activating this release be undone by the repair that runs next?
-//
-// `--fix` is a sequence of repairs, and two of them want opposite things. The
-// activation repair makes an unreachable release reachable; the deactivation
-// repair (repair_state_ → plan_incoherent_deactivation) takes down releases
-// whose members disagree about which release they are. Activating a release
-// that shares program names with an ACTIVE one produces exactly that
-// disagreement, so the second repair tears down what the first just built --
-// and the wreckage reads as a fresh crop of "installed but inactive" entries,
-// which the next run tries to activate again. Measured on 2026.8.1.1: `--fix`
-// ended with more issues than it started with and left `gcc` and `ld` with no
-// active version at all.
-//
-// The answer does not need new machinery. Both halves already exist and are
-// exported: `plan_use_switch` computes the member map activation would write,
-// and `plan_incoherent_deactivation` IS the teardown. So the question is
-// answered by asking the second repair about the first repair's result --
-// simulate, then consult. Detection calls the function the repair calls, the
-// same rule the baked-subos-path check follows, so the two cannot drift.
-//
-// Returns the reason to refuse, or empty when the activation is safe.
-std::string activation_conflict_(const DoctorState& st,
-                                 const std::string& rootTarget,
-                                 const std::string& rootVersion) {
-    auto plan = xvm::plan_use_switch(st.db, st.ws, rootTarget, rootVersion);
-    if (!plan) {
-        // Unresolvable release: `use` would fail too. Refusing here means the
-        // user gets the finding and the command, rather than `--fix` running
-        // something that cannot work.
-        return "the release does not resolve";
-    }
-
-    auto simulated = st.ws;
-    for (const auto& [target, version] : plan->members) {
-        simulated[target] = version;
-    }
-
-    const auto teardown = xvm::plan_incoherent_deactivation(st.db, simulated);
-    if (teardown.targets.empty()) return {};
-
-    // Name the releases that would come down and a few of the programs they
-    // would take with them -- "there is a conflict" is not actionable, "this
-    // takes `ar` away from llvm" is.
-    std::map<std::string, std::vector<std::string>> byRelease;
-    for (const auto& [target, label] : teardown.targets) {
-        byRelease[label].push_back(target);
-    }
-    std::string reason;
-    for (auto& [label, targets] : byRelease) {
-        std::ranges::sort(targets);
-        std::string names;
-        constexpr std::size_t kShown = 4;
-        for (std::size_t i = 0; i < targets.size() && i < kShown; ++i) {
-            if (!names.empty()) names += ", ";
-            names += targets[i];
-        }
-        if (targets.size() > kShown) {
-            names += std::format(", … (+{})", targets.size() - kShown);
-        }
-        if (!reason.empty()) reason += "; ";
-        reason += std::format("it would take {} from the active {}", names,
-                              label);
-    }
-    return reason;
-}
-
-// D1–D5 over the active subos's `subos_info`.
-//
-// One function, called by detection and again by the repair pass. The repair
-// acts on what this returns rather than on its own reading of the rules --
-// a reporter and a repairer that each describe the criteria end up describing
-// them differently, and then fight.
-//
-// Nothing here needs XVM state except D2 and D5, which take the database and
-// already-parsed active workspace as arguments, so the manifest leaf itself
-// stays independent of VersionDB.
-std::vector<Finding> detect_subos_manifest_(const xvm::VersionDB& db,
-                                            const xvm::Workspace& workspace,
-                                            const fs::path& subosDir,
-                                            const std::string& subosName) {
-    namespace mf = xlings::subos::manifest;
-    std::vector<Finding> out;
-
-    // D1 — structure. Anything wrong here makes the rest unreadable, so it is
-    // the only finding produced when it fires.
-    if (auto structural = mf::validate(subosDir); !structural.empty()) {
-        std::string detail;
-        for (const auto& f : structural) {
-            if (!detail.empty()) detail += "; ";
-            detail += std::string(mf::describe(f.kind));
-            if (!f.detail.empty()) detail += " (" + f.detail + ")";
-        }
-        const bool unreadable = std::ranges::any_of(
-            structural, [](const auto& f) {
-                return f.kind == mf::Defect::ConfigUnreadable;
-            });
-        out.push_back({
-            .kind    = FindingKind::SubosManifest,
-            .level   = FindingLevel::Error,
-            .target  = subosName,
-            .detail  = detail,
-            // An unreadable file is not repaired: rewriting it would discard a
-            // workspace no one has managed to parse. Everything else is a
-            // missing or unusable block, which `--fix` can add.
-            .remedy  = unreadable
-                ? std::format("inspect {}",
-                              Config::display_path(mf::config_path(subosDir)))
-                : "xlings self doctor --fix",
-        });
-        return out;
-    }
-
-    auto doc = mf::read_document(subosDir);
-    if (!doc) return out;                      // D1 already covered this
-    const auto info = mf::parse(*doc);
-
-    const auto installed = [&](std::string_view binding) {
-        const auto at = binding.find('@');
-        if (at == std::string_view::npos) return false;
-        const std::string name(binding.substr(0, at));
-        const std::string version(binding.substr(at + 1));
-        const auto* vi = xvm::get_vinfo(db, name);
-        if (!vi) return false;
-        // Namespaced installs record `<ns>:<version>`, so a bare match is not
-        // enough -- compare the version tail.
-        return std::ranges::any_of(vi->versions, [&](const auto& entry) {
-            const auto& key = entry.first;
-            if (key == version) return true;
-            const auto colon = key.find(':');
-            return colon != std::string::npos && key.substr(colon + 1) == version;
-        });
-    };
-
-    // D2 — an envs section whose owner is not installed here.
-    for (const auto& provider : info.envs) {
-        if (installed(provider.binding)) continue;
-        out.push_back({
-            .kind    = FindingKind::SubosEnvOrphan,
-            .level   = FindingLevel::Error,
-            .target  = subosName,
-            .version = provider.binding,
-            .detail  = std::format(
-                "subos '{}' exports {} variable(s) for '{}', which is not "
-                "installed here", subosName, provider.decls.size(),
-                provider.binding),
-            .remedy  = "xlings self doctor --fix",
-        });
-    }
-
-    // D3/D4 — over the resolved set, so both see exactly what activation will.
-    //
-    // select_effective first, for the same reason: a dormant provider (a second
-    // version whose sibling is the active one) contributes nothing, so
-    // reporting that it "would export an unexpanded path" describes an export
-    // that will not happen. D2 above deliberately stays over the FULL set --
-    // "recorded here but not installed here" is true of a dormant section too.
-    const auto effective = mf::select_effective(info, mf::active_versions(*doc));
-    const auto resolved = mf::resolve(effective, mf::Placeholders{
-        .subosdir    = subosDir,
-        .home        = platform::get_home_dir(),
-        .xlings_home = Config::paths().homeDir,
-        .pkgdir_of   = [](std::string_view binding) -> fs::path {
-            const auto at = binding.find('@');
-            if (at == std::string_view::npos) return {};
-            const std::string name(binding.substr(0, at));
-            const std::string version(binding.substr(at + 1));
-            const auto store = Config::paths().dataDir / "xpkgs";
-            std::error_code ec;
-            if (auto direct = store / name / version;
-                fs::is_directory(direct, ec)) {
-                return direct;
-            }
-            if (!fs::is_directory(store, ec)) return {};
-            const auto suffix = "-x-" + name;
-            for (const auto& entry : platform::dir_entries(store)) {
-                if (!entry.is_directory(ec)) continue;
-                if (!entry.path().filename().string().ends_with(suffix)) continue;
-                if (auto candidate = entry.path() / version;
-                    fs::is_directory(candidate, ec)) {
-                    return candidate;
-                }
-            }
-            return {};
-        },
-    });
-
-    for (const auto& v : resolved) {
-        if (v.unresolved) {
-            out.push_back({
-                .kind    = FindingKind::SubosEnvUnresolved,
-                .level   = FindingLevel::Error,
-                .target  = subosName,
-                .version = v.var,
-                .detail  = std::format(
-                    "{} would export an unexpanded path; its provider's "
-                    "payload is missing", v.var),
-                // Reinstalling the provider is what puts the payload back.
-                // Only one is named even when several declared the variable:
-                // a remedy the user can paste beats an exhaustive one.
-                .remedy  = v.providers.empty() ? std::string{}
-                    : std::format("xlings install {}", v.providers.front()),
-            });
-        }
-        if (v.conflicted) {
-            std::string names;
-            for (const auto& b : v.providers) {
-                if (!names.empty()) names += ", ";
-                names += b;
-            }
-            out.push_back({
-                .kind    = FindingKind::SubosEnvConflict,
-                // A warning, not an error: resolution is deterministic and the
-                // subos works. What is wrong is that one of these packages is
-                // silently not getting what it asked for.
-                .level   = FindingLevel::Warning,
-                .target  = subosName,
-                .version = v.var,
-                .detail  = std::format("{} is claimed by {}", v.var, names),
-            });
-        }
-    }
-
-    // D6 — a package bound at several versions with nothing able to say which.
-    //
-    // Not every duplicate: two versions where one is active is ordinary, and
-    // the dormant section is exactly what lets `xlings use pkg@<older>` restore
-    // an environment without reinstalling. Activation already drops it
-    // (manifest::select_effective).
-    //
-    // What is reportable is the subset with NO active version -- `xvm.add(name)`
-    // with no version registers a root without one, which is what mesa,
-    // libglvnd and nvidia-gl-host-link do. For those every provider
-    // contributes, so a second version really does export every variable twice.
-    // That is the state that enumerated one GPU as two.
-    //
-    // The predicate is mf::contested_bindings, and --fix calls that same
-    // function rather than an equivalent one written here. Three report/repair
-    // pairs in this repo have drifted, each showing up as a finding that
-    // repairing does not clear.
-    const auto activeInSubos = mf::active_versions(*doc);
-    for (const auto& dup : mf::contested_bindings(info, activeInSubos)) {
-        std::string names;
-        for (const auto& b : dup.bindings) {
-            if (!names.empty()) names += ", ";
-            names += b;
-        }
-        out.push_back({
-            .kind    = FindingKind::SubosDoubleBinding,
-            // Error: the observable effect -- a device enumerated twice, a
-            // search path with two of everything -- is a wrong result, not a
-            // cosmetic one.
-            .level   = FindingLevel::Error,
-            .target  = subosName,
-            .version = dup.name,
-            .detail  = std::format(
-                "'{}' is bound {} times in subos '{}' ({}) and has no active "
-                "version, so every one of them contributes",
-                dup.name, dup.bindings.size(), subosName, names),
-            // Naming the versions in the remedy: the user is otherwise left
-            // choosing between two strings with nothing to tell them apart.
-            .remedy  = std::format("xlings use {}@<one of: {}>", dup.name, [&] {
-                std::string vs;
-                for (const auto& b : dup.bindings) {
-                    if (!vs.empty()) vs += ", ";
-                    vs += std::string(mf::binding_version(b));
-                }
-                return vs;
-            }()),
-        });
-    }
-
-    // D5 — the manifest and this SubOS's active XVM runtime must agree
-    // exactly. Finding the declared version elsewhere in the global DB is not
-    // enough: many payload versions coexist globally by design, while one
-    // SubOS has one active core runtime.
-    const auto runtimePayloadExists = [&](std::string_view binding) {
-        if (!mf::is_binding(binding)) return false;
-        const std::string name(mf::binding_name(binding));
-        const auto wanted = mf::binding_version(binding);
-        const auto* vi = xvm::get_vinfo(db, name);
-        if (!vi) return false;
-        for (const auto& [version, data] : vi->versions) {
-            if (!mf::version_is_active(wanted, version) || data.path.empty()) {
-                continue;
-            }
-            std::error_code ec;
-            const auto expanded = xvm::expand_path(
-                data.path, Config::paths().homeDir.string());
-            if (fs::exists(expanded, ec) && !ec) return true;
-        }
-        return false;
-    };
-
-    if (mf::is_binding(info.runtime)) {
-        const auto runtimeName = std::string(mf::binding_name(info.runtime));
-        const auto activeIt = workspace.find(runtimeName);
-        const std::string activeVersion = activeIt == workspace.end()
-            ? std::string{} : activeIt->second;
-        const auto mismatch = mf::check_runtime_activation(
-            info, activeVersion, runtimePayloadExists(info.runtime));
-        if (!mismatch) return out;
-
-        // A cold default SubOS records its runtime authority before that
-        // payload is materialized, while `self install` intentionally stays
-        // lightweight and does not download it. There is no split state until an
-        // active runtime exists. Keep the declaration visible as a warning;
-        // an active mismatch or an active runtime whose payload disappeared
-        // remains an error.
-        const bool unmaterializedDeclaration =
-            activeVersion.empty() && mismatch->payloadMissing;
-
-        const auto active = mismatch->active.empty()
-            ? std::string("<none>") : mismatch->active;
-        std::string detail = std::format(
-            "subos '{}' declares runtime {}, but its active XVM runtime is {}",
-            subosName, mismatch->declared, active);
-        if (mismatch->payloadMissing) {
-            detail += std::format("; declared runtime payload {} is missing",
-                                  mismatch->declared);
-        }
-
-        // Two ways out, and "create a new SubOS" is neither of them.
-        //
-        //   adopt   -- record what this subos is actually running. `--fix`
-        //              does this, and it is what a home upgraded from before
-        //              `subos_info` existed needs: the declaration was written
-        //              by the upgrade, not chosen by anyone.
-        //   migrate -- install the declared runtime and activate it. That path
-        //              already works, because activating the DECLARED version
-        //              is exactly what the use guard permits.
-        //
-        // Naming only "create a new SubOS" made this a dead end it never was.
-        const bool differentActive = !mismatch->active.empty()
-            && mismatch->active != mismatch->declared;
-        if (differentActive) {
-            detail += std::format(
-                "; nothing here was ever activated against {}",
-                mismatch->declared);
-        }
-        out.push_back({
-            .kind    = FindingKind::SubosRuntimeMissing,
-            .level   = unmaterializedDeclaration
-                ? FindingLevel::Warning : FindingLevel::Error,
-            .target  = subosName,
-            .version = mismatch->declared,
-            .detail  = std::move(detail),
-            .remedy  = differentActive
-                ? std::format(
-                    "xlings self doctor --fix   (adopt {}; or migrate with "
-                    "`xlings install {}` then `xlings use {} {}`)",
-                    mismatch->active, mismatch->declared,
-                    mf::binding_name(mismatch->declared),
-                    mf::binding_version(mismatch->declared))
-                : std::format("xlings install {}", mismatch->declared),
-        });
-    }
-    return out;
-}
-
-// Is the file every shim dispatches through the xlings this home says it runs?
-//
-// TWO SHAPES, ONE FINDING. Reported separately because the user's next move
-// differs, and because each is evidence the other cannot supply:
-//
-//   * the active binding names a version, the FILE reports another. Provable
-//     divergence -- the writer is `use`/`install` of the xlings package, so
-//     the only ways to reach this state are a hand-copied binary or a failed
-//     replacement. Live on a real home while this was written: the binding
-//     said `local:0.4.51` and the file was 2026.8.11.1.
-//   * the file is behind a version this home already has on disk. Directional
-//     on purpose -- "not equal" would fire on every deliberately pinned entry,
-//     and the half that bites is only ever "the entry is older".
-//
-// The version comes from RUNNING the binary (entry_binary::version_of), not
-// from a record. Checking a record against another record is what let the
-// original divergence stand: `.xlings.json` and the versions DB agreed with
-// each other and neither described the file. ~60ms, measured, once per run.
-//
-// An unreadable entry produces NOTHING. No observation is not a verdict --
-// the same rule `registered`/`kRegisteredUnrecorded` follows one module over.
-std::vector<Finding> detect_entry_binary_(const DoctorState& st) {
-    std::vector<Finding> out;
-    auto& p = Config::paths();
-
-    const auto entry = entry_binary::path_of(p.homeDir);
-    const auto actual = entry_binary::version_of(entry);
-    if (actual.empty()) return out;   // absent, or would not answer
-
-    // What the home says is active for the `xlings` program, in this subos.
-    if (auto it = st.ws.find("xlings");
-        it != st.ws.end() && !it->second.empty()) {
-        // The binding may be namespace-qualified (`local:0.4.51`); compare on
-        // the version alone, since the file cannot report a namespace.
-        std::string boundVersion = it->second;
-        if (auto colon = boundVersion.rfind(':'); colon != std::string::npos) {
-            boundVersion = boundVersion.substr(colon + 1);
-        }
-        // A binding that is not a version at all -- a sentinel like `latest`,
-        // or anything a future client writes -- is NO OBSERVATION, not a
-        // mismatch. Comparing it against the file would report drift on every
-        // home that spells its binding that way. Same first-digit rule
-        // entry_binary::version_of applies to the binary's own answer, so the
-        // two sides of the comparison are qualified identically.
-        const bool boundIsAVersion =
-            !boundVersion.empty()
-            && std::isdigit(static_cast<unsigned char>(boundVersion[0]));
-        if (boundIsAVersion && boundVersion != actual) {
-            // Reconcile toward the NEWER of the two, whichever side it is on.
-            //
-            // The obvious remedy -- "make the file match the binding" -- is
-            // actively harmful in the case that produced this check: the
-            // binding was a June `local:` build and the file was current, so
-            // that command would have recreated the outage it is meant to
-            // report. `use` rewrites the entry either way, so choosing the
-            // newer side re-aligns the binding at no cost when the file is
-            // ahead, and upgrades the file when the binding is ahead.
-            const bool bindingIsNewer =
-                version_order::compare(boundVersion, actual) > 0;
-            const auto toward = bindingIsNewer ? it->second : actual;
-            out.push_back({
-                .kind    = FindingKind::EntryBinaryDrift,
-                .level   = FindingLevel::Notice,
-                .target  = "xlings",
-                .version = actual,
-                .detail  = std::format(
-                    "bin/xlings reports {}, but this subos has {} active -- "
-                    "every shim in the home dispatches through the file, not "
-                    "the binding",
-                    actual, it->second),
-                .remedy  = std::format("xlings use xlings {}", toward),
-            });
-        }
-    }
-
-    // Something newer sitting in the store. Payload dirs, not the versions DB:
-    // the question is what this home COULD dispatch through, and a payload
-    // with a binary in it is the direct evidence of that.
-    std::string newest;
-    std::string newestCoordinate;
-    const auto xpkgs = Config::global_data_dir() / "xpkgs";
-    std::error_code ec;
-    if (fs::is_directory(xpkgs, ec)) {
-        for (const auto& pkgDir : platform::dir_entries(xpkgs)) {
-            if (!pkgDir.is_directory()) continue;
-            const auto storeName = pkgDir.path().filename().string();
-            const auto sep = storeName.find("-x-");
-            const auto name = sep == std::string::npos
-                ? storeName : storeName.substr(sep + 3);
-            if (name != "xlings") continue;
-            const auto ns = sep == std::string::npos
-                ? std::string{} : storeName.substr(0, sep);
-            for (const auto& verDir : platform::dir_entries(pkgDir.path())) {
-                if (!verDir.is_directory()) continue;
-                const auto version = verDir.path().filename().string();
-                // Positive evidence only: a payload that failed to install is
-                // not something this home can dispatch through.
-                if (xim::stamped_incomplete(verDir.path())) continue;
-                if (!fs::exists(verDir.path() / "bin"
-                                / shim_filename_("xlings"), ec)) continue;
-                // A payload built for another platform cannot become this
-                // home's entry, and the remedy this finding prints would fail
-                // against it. Only a PROVABLE mismatch is excluded -- Unknown
-                // stays eligible, the same rule PackageMatch::payloadForeign
-                // follows.
-                if (xim::classify_payload_platform(verDir.path())
-                        == xim::PayloadPlatform::Foreign) continue;
-                if (version_order::compare(version, actual) <= 0) continue;
-                if (!newest.empty()
-                    && version_order::compare(version, newest) <= 0) continue;
-                newest = version;
-                newestCoordinate = ns.empty()
-                    ? std::format("xlings@{}", version)
-                    : std::format("{}:xlings@{}", ns, version);
-            }
-        }
-    }
-    if (!newest.empty()) {
-        out.push_back({
-            .kind    = FindingKind::EntryBinaryDrift,
-            .level   = FindingLevel::Notice,
-            .target  = "xlings",
-            .version = actual,
-            .detail  = std::format(
-                "bin/xlings is {}, and {} is already installed here -- an "
-                "older entry may not expand records a newer index wrote",
-                actual, newestCoordinate),
-            .remedy  = std::format("xlings use xlings {}", newest),
-        });
-    }
-    return out;
-}
-
 Scan detect_(const DoctorState& st, const CoordinateProbe& probe,
-             const AuditSelection& audit) {
-    auto& p = Config::paths();
-    Scan scan;
-    const auto add = [&](Finding f) { scan.findings.push_back(std::move(f)); };
-
-    // The subos this run is actually in. Other subos are not inspected from
-    // here for the same reason their payloads are not repaired: a second
-    // shell may be inside one right now.
-    for (auto&& f : detect_subos_manifest_(st.db, st.ws, p.subosDir,
-                                           p.activeSubos.empty() ? "default"
-                                                                 : p.activeSubos)) {
-        add(std::move(f));
-    }
-
-    for (auto&& f : detect_entry_binary_(st)) add(std::move(f));
-
-    // The PATH an aliased command would inherit. Read once, and read from
-    // THIS process: doctor is normally started from the user's shell, so this
-    // is the same PATH the shim would get. It is not guaranteed to be -- a
-    // stripped environment sees fewer host commands than the user does -- so
-    // it can only ever downgrade a finding from "satisfied by the host" to
-    // "resolves to nothing", never the reverse. That direction is the safe
-    // one to be wrong in: it over-reports in a sandbox instead of staying
-    // silent on a real break.
-    const std::string hostPath =
-        std::getenv("PATH") ? std::getenv("PATH") : std::string{};
-
-    // Check 1: every workspace program has its shim.
-    for (const auto& [name, version] : st.ws) {
-        if (version.empty()) continue;
-        const auto* vi = xvm::get_vinfo(st.db, name);
-        if (!vi || xvm::effective_kind_of(st.db, name, version) != "program")
-            continue;
-
-        auto shimPath = p.binDir / shim_filename_(name);
-        if (fs::exists(shimPath) || fs::is_symlink(shimPath)) continue;
-        add({
-            .kind    = FindingKind::MissingShim,
-            .level   = FindingLevel::Error,
-            .target  = name,
-            .version = version,
-            .detail  = std::format("workspace[{}]={} but {} missing",
-                                   name, version,
-                                   Config::display_path(shimPath)),
-            .shimPath = shimPath,
-        });
-    }
-
-    // Does this name exist only to anchor releases? Check 3 asks the same
-    // question per (name, version) and answers it with a `release anchor`
-    // notice; Check 2 has no version to ask about -- nothing is active, that
-    // is the finding -- so it asks about every registered version instead.
-    //
-    // All of them, not any: a name with one real program version and one
-    // anchor version is a program whose shim genuinely has no active version.
-    const auto anchor_only_target_ = [&](const std::string& name,
-                                         const xvm::VInfo& vi) {
-        if (vi.versions.empty()) return false;
-        return std::ranges::all_of(
-            vi.versions, [&](const auto& entry) {
-                return xvm::is_binding_root(st.db, name, entry.first);
-            });
-    };
-
-    // Check 2: orphan shims (program shim file present, workspace doesn't know
-    // about it). Only names registered as type "program" count -- random files
-    // under binDir aren't ours.
-    if (fs::exists(p.binDir)) {
-        for (auto& entry : platform::dir_entries(p.binDir)) {
-            std::error_code ec;
-            if (!entry.is_regular_file(ec) && !entry.is_symlink(ec)) continue;
-            auto fname = entry.path().filename().string();
-            std::string base = fname;
-            if (!shim_ext_.empty() && base.ends_with(shim_ext_)) {
-                base = base.substr(0, base.size() - shim_ext_.size());
-            }
-            // Only a shim file name is in hand here, so the question is
-            // widened to "any version of this name is a program".
-            const auto* vi = xvm::get_vinfo(st.db, base);
-            if (!vi || !xvm::has_program_kind(st.db, base)) continue;
-
-            auto wit = st.ws.find(base);
-            if (wit != st.ws.end() && !wit->second.empty()) continue;
-
-            // A binding root is not a program anyone runs -- it names the
-            // release its members belong to. Installs before 2026.7.29.2
-            // wrote a shim for one whenever registration withheld activation
-            // from the release (installer.cppm, the ProgramShim effect), so
-            // this file is on existing homes through no act of the user's.
-            // `--fix` still removes it; it is no longer an error that it is
-            // there.
-            const bool anchor = anchor_only_target_(base, *vi);
-            add({
-                .kind   = FindingKind::OrphanShim,
-                .level  = anchor ? FindingLevel::Notice : FindingLevel::Error,
-                .target = base,
-                .detail = anchor
-                    ? std::format(
-                        "{} anchors a release and has no active version; "
-                        "nothing dispatches through it",
-                        Config::display_path(entry.path()))
-                    : std::format(
-                        "{} exists but workspace has no active version for {}",
-                        Config::display_path(entry.path()), base),
-                .shimPath = entry.path(),
-            });
-        }
-    }
-
-    // COMPAT(0.4.8 → drop in 0.6.0): Check 2.5 — legacy alias shims
-    // (xim/xvm/xself/xsubos/xinstall). Names + predicate are owned by
-    // xself::compat. When the compat module is removed, delete this block.
-    if (fs::exists(p.binDir)) {
-        std::error_code bec;
-        auto canonicalBootstrap = fs::weakly_canonical(st.xlingsBin, bec);
-        for (auto alias : compat::v0_4_8::LEGACY_ALIAS_NAMES) {
-            auto path = p.binDir / shim_filename_(std::string(alias));
-            if (!compat::v0_4_8::is_legacy_alias_symlink_to_bootstrap(
-                    path, canonicalBootstrap)) continue;
-            add({
-                .kind   = FindingKind::LegacyAliasShim,
-                .level  = FindingLevel::Error,
-                .target = std::string(alias),
-                .detail = std::format(
-                    "{} is a leftover symlink from older xlings (alias `{}` "
-                    "removed in 0.4.8)",
-                    Config::display_path(path), alias),
-                .shimPath = path,
-            });
-        }
-    }
-
-    // Check 2.7: installed here, and nothing active.
-    //
-    // The gap between Check 1 and Check 2. Check 1 asks "does every ACTIVE
-    // program have a shim" and never sees a name with no active version;
-    // Check 2 asks "does every shim have an active version" and never sees a
-    // name with no shim. A package that is installed and inactive is missing
-    // from both tables at once, so both loops skip it and the payload loop
-    // below finds it perfectly healthy -- which it is. What is broken is the
-    // selection, and until now nothing looked at the selection.
-    //
-    // Reported per RELEASE, not per program.
-    //
-    // Activation is a release-level act -- `use` moves a whole binding group
-    // at once -- so one inactive release is one problem no matter how many
-    // names it registers. On the measured home the per-program shape printed
-    // fifty lines for three releases: `clang`, `clang++`, `clang-22`,
-    // `llvm-ar` … each with its own identical remedy. That is the same burial
-    // the broken-payload grouping exists to prevent (see Finding::groupKey),
-    // and it would have hidden `node` in the middle of it.
-    // Keyed by ROOT TARGET, not by (root, version).
-    //
-    // F3: a package can have several installed releases with none of them
-    // active, and keying by version produced one finding per release, each
-    // with a remedy contradicting the others -- `xim-gnu-gcc@15.1.0` and
-    // `@16.1.0` side by side, both saying "run me". There is one problem here
-    // ("nothing of this package is selected") and one decision to make, so
-    // there is one finding, and it names the versions to choose from.
-    struct InactiveRelease {
-        std::string rootTarget;
-        std::string rootVersion;   // the one the remedy proposes
-        std::set<std::string> members;
-    };
-    std::map<std::string, InactiveRelease> inactiveReleases;
-
-    for (const auto& [name, versions] : st.wsInstalled) {
-        if (versions.empty()) continue;
-        if (auto wit = st.ws.find(name);
-            wit != st.ws.end() && !wit->second.empty()) continue;
-
-        const auto* vi = xvm::get_vinfo(st.db, name);
-        if (!vi || !xvm::has_program_kind(st.db, name)) continue;
-
-        // Only versions this subos actually has, highest first: the same
-        // ordering removal.cppm:390-393 uses to pick a replacement release,
-        // so doctor's remedy and remove's automatic choice cannot disagree.
-        std::vector<std::string> candidates;
-        for (const auto& version : versions) {
-            if (!vi->versions.contains(version)) continue;
-            if (xvm::effective_kind_of(st.db, name, version) != "program")
-                continue;
-            candidates.push_back(version);
-        }
-        if (candidates.empty()) continue;
-        std::ranges::sort(candidates, xvm::version_key_greater);
-
-        // Would activating it actually produce a working command?
-        //
-        // This is the whole filter, and `is_binding_root` deliberately is not
-        // part of it. A name that exists only to anchor a release has no
-        // executable and drops out here -- activating one is issue #452 in the
-        // other direction, where the shim can only ever print "no active
-        // version". But asking `is_binding_root` first would have thrown out
-        // the real cases too: a group's root is usually its main program.
-        // `node` roots the release that owns `npm` and `npx`, so it answers
-        // true to that question while being exactly the program the user is
-        // missing. Only the payload can tell the two apart, so only the
-        // payload is asked -- the same order Check 3 uses.
-        //
-        // A version whose payload is gone is skipped as well: Check 3 already
-        // reports that as a broken payload with an install remedy, and
-        // offering `xlings use` on top of it would name a command that cannot
-        // succeed.
-        const auto usable = std::ranges::find_if(
-            candidates, [&](const std::string& version) {
-                const auto* vd = xvm::get_vdata(st.db, name, version);
-                if (!vd || vd->path.empty()) return false;
-                if (!vd->alias.empty() && !vd->alias[0].empty()) return true;
-                return !xvm::resolve_executable(name, vd->path, st.homeStr)
-                            .empty();
-            });
-        if (usable == candidates.end()) continue;
-
-        // The release this program belongs to, which is what `use` takes as
-        // an argument. A legacy entry carries no group and is its own root --
-        // that is not a fallback, it is what a single-program package is.
-        const auto* vd = xvm::get_vdata(st.db, name, *usable);
-        const std::string rootTarget =
-            vd && vd->bindingGroup ? vd->bindingGroup->rootTarget : name;
-        const std::string rootVersion =
-            vd && vd->bindingGroup ? vd->bindingGroup->rootVersion : *usable;
-
-        // Both guards run BEFORE the map is touched: `operator[]` would insert
-        // a default-constructed release and the `continue` would leave it
-        // there, which renders as a finding with an empty name and zero
-        // programs.
-        //
-        // F1 — is this release the one you did not pick, rather than one you
-        // cannot reach?
-        //
-        // `llvm` installed at 20.1.7 and 22.1.8, active at 22.1.8, is a normal
-        // home. But 20.1.7 registers names 22.1.8 does not, and those names
-        // have no active version, so the release came back as a finding whose
-        // remedy -- `xlings use llvm@20.1.7` -- would DOWNGRADE the toolchain
-        // the user is actually using. Two releases of one package were
-        // reported as two mutually contradictory defects.
-        //
-        // The root target answers it. If some version of the root is active,
-        // the user has chosen a release of this package and the others are
-        // alternatives, not breakage. When no version of the root is active,
-        // nothing of the package is reachable -- which is exactly the `node`
-        // case this check was written for.
-        if (const auto rootIt = st.ws.find(rootTarget);
-            rootIt != st.ws.end() && !rootIt->second.empty()) {
-            continue;
-        }
-
-        // F2 — a payload built for another platform has no programs to put on
-        // PATH here, ever.
-        //
-        // The measured home carried a May-era WINDOWS llvm@20.1.7 in a Linux
-        // store; it registered `clang.exe` … `libomp.dll` as programs (the
-        // case payload.cppm's header documents), and this check dutifully
-        // reported 29 of them as "not on PATH". They cannot be. The classifier
-        // that answers this already exists and the installer already uses it
-        // (installer.cppm) -- this check simply never asked.
-        if (vd && !vd->path.empty()
-            && xim::classify_payload_platform(
-                   fs::path(xvm::expand_path(vd->path, st.homeStr)))
-                   == xim::PayloadPlatform::Foreign) {
-            continue;
-        }
-
-        auto& release = inactiveReleases[rootTarget];
-        release.rootTarget = rootTarget;
-        // Highest wins the remedy, by version rather than by iteration order.
-        if (release.rootVersion.empty()
-            || xvm::version_key_greater(rootVersion, release.rootVersion)) {
-            release.rootVersion = rootVersion;
-        }
-        release.members.insert(name);
-    }
-
-    for (const auto& [key, release] : inactiveReleases) {
-        // Names, not a count. "30 programs" tells the user nothing they can
-        // check; `clang, clang++, ld.lld …` is how they recognise what they
-        // have been missing. The list is capped because a release with thirty
-        // members would otherwise take the terminal apart -- `--all` prints it
-        // whole.
-        constexpr std::size_t kShown = 6;
-        std::string names;
-        std::size_t shown = 0;
-        for (const auto& member : release.members) {
-            if (shown++ >= kShown) break;
-            if (!names.empty()) names += ", ";
-            names += member;
-        }
-        if (release.members.size() > kShown) {
-            names += std::format(", … (+{})", release.members.size() - kShown);
-        }
-
-        // When several releases are installed and none chosen, the versions
-        // ARE the decision. Naming only the one the remedy proposes would hide
-        // that there was a choice.
-        //
-        // Read from installed[], not from the versions the members happened to
-        // resolve to: every member picks the same highest release, so
-        // accumulating those yields one version and the choice stays invisible
-        // -- which is what it did until this was measured.
-        std::string otherVersions;
-        if (const auto rootInstalled = st.wsInstalled.find(release.rootTarget);
-            rootInstalled != st.wsInstalled.end()) {
-            std::vector<std::string> others;
-            for (const auto& version : rootInstalled->second) {
-                if (version == release.rootVersion) continue;
-                others.push_back(version);
-            }
-            std::ranges::sort(others, xvm::version_key_greater);
-            for (const auto& version : others) {
-                if (!otherVersions.empty()) otherVersions += ", ";
-                otherVersions += version;
-            }
-            if (!otherVersions.empty()) {
-                otherVersions = std::format("  —  also installed: {}",
-                                            otherVersions);
-            }
-        }
-
-        // What the repair will ALSO do.
-        //
-        // The remedy is `use`, and `use` moves a whole release. A name that
-        // another package currently owns -- node's release registers `npm`,
-        // and a standalone npm package may hold it -- changes hands when the
-        // release is activated. That is correct for `use` and it is what the
-        // user gets whether they run the command themselves or let `--fix`
-        // run it, but it must not be something they discover afterwards:
-        // finding out later that a selection moved is the same silent-change
-        // shape this whole check exists to end.
-        std::string alsoMoves;
-        if (const auto selection = xvm::resolve_binding_selection(
-                st.db, release.rootTarget, release.rootVersion)) {
-            for (const auto& [memberTarget, memberVersion]
-                     : selection->members) {
-                const auto activeIt = st.ws.find(memberTarget);
-                if (activeIt == st.ws.end() || activeIt->second.empty()) continue;
-                if (activeIt->second == memberVersion) continue;
-                if (!alsoMoves.empty()) alsoMoves += ", ";
-                alsoMoves += std::format("{} ({} → {})", memberTarget,
-                                         activeIt->second, memberVersion);
-            }
-        }
-
-        add({
-            .kind    = FindingKind::InactiveInstalled,
-            .level   = FindingLevel::Error,
-            .target  = release.rootTarget,
-            .version = release.rootVersion,
-            .detail  = std::format(
-                "{} is installed in this subos but no version is active, so no "
-                "shim was written and {} program(s) are not on PATH: {}{}",
-                xvm::display_coordinate(release.rootTarget,
-                                        release.rootVersion),
-                release.members.size(), names,
-                otherVersions
-                    + (alsoMoves.empty()
-                           ? std::string{}
-                           : std::format(
-                                 "  —  activating it also moves {}",
-                                 alsoMoves))),
-            .remedy  = std::format("xlings use {}@{}", release.rootTarget,
-                                   release.rootVersion),
-            .conflict = activation_conflict_(st, release.rootTarget,
-                                             release.rootVersion),
-            .groupKey = key,
-        });
-    }
-
-    // Check 2.6: shim ownership anchoring (0.4.48). Warning-only: the usual
-    // cause is a hand-copied shim file or a damaged home layout, and the right
-    // fix depends on which it is. Scoped to bin dirs physically inside the
-    // home -- a project subos binDir lives in the project tree, where shims
-    // intentionally anchor to the global home.
-    // See .agents/docs/2026-06-04-shim-owner-anchoring-design.md.
-    std::error_code relEc;
-    auto binRel = fs::relative(p.binDir, p.homeDir, relEc);
-    const bool binDirInsideHome = !relEc && !binRel.empty()
-        && binRel.string().rfind("..", 0) != 0;
-    if (binDirInsideHome && fs::exists(p.binDir)) {
-        std::error_code hec;
-        auto homeCanon = fs::weakly_canonical(p.homeDir, hec);
-        for (auto& entry : platform::dir_entries(p.binDir)) {
-            std::error_code ec;
-            if (!entry.is_regular_file(ec) && !entry.is_symlink(ec)) continue;
-            auto fname = entry.path().filename().string();
-            std::string base = fname;
-            if (!shim_ext_.empty() && base.ends_with(shim_ext_)) {
-                base = base.substr(0, base.size() - shim_ext_.size());
-            }
-            if (xvm::is_xlings_binary(base)) continue;
-            if (!xvm::has_program_kind(st.db, base)) continue;
-
-            auto owner = xvm::resolve_owner_home(entry.path());
-            std::error_code oec;
-            if (owner && fs::weakly_canonical(*owner, oec) == homeCanon) {
-                continue;
-            }
-            add({
-                .kind   = FindingKind::ShimAnchor,
-                .level  = FindingLevel::Warning,
-                .target = base,
-                .detail = std::format(
-                    "{} anchors to {} (expected this home); it will dispatch "
-                    "against that home's versions DB",
-                    Config::display_path(entry.path()),
-                    owner ? Config::display_path(*owner)
-                          : std::string("no home (orphan)")),
-            });
-        }
-    }
-
-    // Check 3: payload existence + executability for every (name, version) in
-    // the versions DB. Reuses the same `resolve_executable` helper that
-    // shim_dispatch uses at runtime, so doctor's verdict matches what the user
-    // will actually experience when they invoke the shim.
-    //
-    // Scope: ALL versions (active + inactive) — heads-up before users
-    // `xlings use` an inactive version that's already broken.
-    const auto reportBrokenPayload =
-        [&](const std::string& name, const std::string& version,
-            const fs::path& expanded, std::string detail) {
-        // Whose entry is this? The finding is home-wide -- the loop walks the
-        // shared DB -- but the repair is not: `xlings install` re-runs
-        // config(), and config() registers into whichever subos is current.
-        //
-        // Unclaimed entries are still repaired here. On a home written before
-        // installed[] existed, every inactive version is unclaimed, and that
-        // cohort is exactly who the repair ladder was built for.
-        const auto owner = xvm::subos_ownership(
-            st.ws, st.wsInstalled, st.otherSubos, name, version);
-        if (!owner.ownedHere && !owner.otherSubos.empty()) {
-            add({
-                .kind    = FindingKind::ForeignPayload,
-                .level   = FindingLevel::Warning,
-                .target  = name,
-                .version = version,
-                .detail  = std::move(detail),
-                .remedy  = std::format(
-                    "xlings subos use {} && xlings self doctor --fix",
-                    owner.otherSubos.front()),
-                .groupKey = std::format("{}|{}", expanded.string(), version),
-                .subos   = owner.otherSubos,
-            });
-            return;
-        }
-        const auto wit = st.ws.find(name);
-        std::string remedy;
-        if (audit.deep) {
-            if (auto coord = owning_coordinate_(st.db, name, version, probe)) {
-                remedy = coord->install_command();
-            }
-        }
-        add({
-            .kind     = FindingKind::BrokenPayload,
-            .level    = FindingLevel::Error,
-            .target   = name,
-            .version  = version,
-            .detail   = std::move(detail),
-            .remedy   = std::move(remedy),
-            .groupKey = std::format("{}|{}", expanded.string(), version),
-            .active   = wit != st.ws.end() && wit->second == version,
-        });
-    };
-
-    for (const auto& [name, vinfo] : st.db) {
-        for (const auto& [version, vdata] : vinfo.versions) {
-            // Per version, not per target: one target can hold versions of
-            // different kinds, and skipping the whole target on the
-            // target-level fallback discards the ones that are programs.
-            if (xvm::effective_kind(vinfo, vdata) != "program") continue;
-            if (vdata.path.empty()) continue;  // type-only stub
-
-            auto expanded = xvm::expand_path(vdata.path, st.homeStr);
-            std::error_code ec;
-
-            // L4: payload directory must exist.
-            if (!fs::is_directory(expanded, ec)) {
-                reportBrokenPayload(name, version, expanded, std::format(
-                    "{} path {} missing",
-                    xvm::display_coordinate(name, version),
-                    Config::display_path(expanded)));
-                continue;
-            }
-
-            // An install-time subos path recorded in the alias or an env
-            // value. Detected before the alias/no-alias split because envs
-            // carry it too, and a package with no alias at all still can.
-            if (const auto activeSubos =
-                    Config::xvm_artifact_subos_dir().string();
-                !activeSubos.empty()) {
-                std::vector<std::string> baked;
-                // A subos path stored in a database every subos shares.
-                //
-                // Alias and envs are asked the SAME question -- "does this
-                // pin one subos?" -- because they have the same fix and the
-                // same cause. The defect is a property of the VALUE, not of
-                // any argument syntax, which is why an earlier shape that
-                // looked for a `--sysroot` flag could do nothing for envs.
-                //
-                // Detection calls the function the repair calls, so the two
-                // cannot drift, and after the repair there is nothing left to
-                // rewrite: the finding goes away permanently instead of
-                // moving to whichever subos runs doctor next.
-                const auto note_if_baked = [&](std::string_view what,
-                                               const std::string& value) {
-                    if (xvm::pin_subos_paths(value, st.homeStr) != value) {
-                        baked.push_back(std::format("{} '{}'", what, value));
-                    }
-                };
-                if (!vdata.alias.empty()) {
-                    note_if_baked("alias", vdata.alias[0]);
-                }
-                for (const auto& [key, value] : vdata.envs) {
-                    note_if_baked(std::format("env {}", key), value);
-                }
-                if (!baked.empty()) {
-                    std::string list;
-                    for (const auto& b : baked) {
-                        if (!list.empty()) list += ", ";
-                        list += b;
-                    }
-                    add({
-                        .kind    = FindingKind::SubosPathBaked,
-                        .level   = FindingLevel::Warning,
-                        .target  = name,
-                        .version = version,
-                        .detail  = std::format(
-                            "{} records an install-time subos path: {} — "
-                            "execution already follows the active subos; "
-                            "`--fix` rewrites the record",
-                            xvm::display_coordinate(name, version), list),
-                    });
-                }
-            }
-
-            const bool aliasMode =
-                !vdata.alias.empty() && !vdata.alias[0].empty();
-            if (!aliasMode) {
-                // L5: the executable shim_dispatch would exec must resolve.
-                if (!xvm::resolve_executable(name, vdata.path, st.homeStr)
-                         .empty()) {
-                    continue;
-                }
-                // A name that exists only to anchor a release is not a broken
-                // payload. Library-only packages have no program of their own,
-                // and with `type` unset that entry defaults to "program" and
-                // then fails this check forever.
-                if (xvm::is_binding_root(st.db, name, version)
-                    || !payload_has_any_executable_(expanded)) {
-                    add({
-                        .kind    = FindingKind::ReleaseAnchor,
-                        .level   = FindingLevel::Notice,
-                        .target  = name,
-                        .version = version,
-                        .detail  = std::format(
-                            "{} registers no program of its own; it names the "
-                            "release its libraries belong to",
-                            xvm::display_coordinate(name, version)),
-                    });
-                    continue;
-                }
-                reportBrokenPayload(name, version, expanded, std::format(
-                    "{} executable '{}' not found in {}",
-                    xvm::display_coordinate(name, version), name,
-                    Config::display_path(expanded)));
-                continue;
-            }
-
-            // Alias mode: ask the question the runtime answers.
-            //
-            // This used to call resolve_executable, which searches the
-            // package's own payload and nothing else, and report every miss as
-            // one warning. But the alias branch of shim_dispatch prepends the
-            // payload, the payload's bin, AND the subos bin dir to PATH before
-            // handing the command to a shell, so two whole tiers of the real
-            // search were invisible here. A package whose only job is to give
-            // thirty short names to a sibling package's `mcpp` resolves on
-            // every invocation and was reported broken on every doctor run --
-            // thirty-four such warnings on one measured home, all of them
-            // false, and one warning level for "runs fine via a sibling",
-            // "runs fine via the host" and "nothing to exec at all".
-            //
-            // resolve_alias_program lives next to the dispatcher so the two
-            // cannot drift, the same reason the baked-path check calls the
-            // function its repair calls.
-            //
-            // TODO(self-doctor): only alias[0] is inspected — matches the
-            // runtime today; if multi-element fallback chains ever land they
-            // should be covered too.
-            const auto aliasProg = alias_program_(vdata.alias[0], st.homeStr);
-            const auto resolution = xvm::resolve_alias_program(
-                aliasProg, vdata.path, st.homeStr, p.binDir, hostPath);
-            // Its own payload, a sibling shim in this subos, or a full path
-            // that is there. Nothing to report.
-            //
-            // The absolute case used to be skipped BEFORE anything was
-            // checked, so an absolute alias pointing at a path that no longer
-            // existed was the one alias shape doctor could never report. It
-            // is checked now, and only its absence is a finding.
-            if (resolution.origin == xvm::AliasOrigin::Absolute
-                || resolution.origin == xvm::AliasOrigin::Payload
-                || resolution.origin == xvm::AliasOrigin::SubosBin) {
-                continue;
-            }
-            if (resolution.origin == xvm::AliasOrigin::SystemPath) {
-                // Works, and is allowed to: a recipe may deliberately wrap a
-                // host tool. Worth saying once because it is the difference
-                // between a home that is portable and one that is not, but it
-                // is not a defect and must not touch the exit code.
-                add({
-                    .kind    = FindingKind::AliasUnresolved,
-                    .level   = FindingLevel::Notice,
-                    .target  = name,
-                    .version = version,
-                    .detail  = std::format(
-                        "{} alias '{}' is satisfied by a host command ({}), "
-                        "not by anything xlings installed",
-                        xvm::display_coordinate(name, version), aliasProg,
-                        resolution.path.string()),
-                });
-                continue;
-            }
-
-            // Nothing to exec, anywhere the runtime would look.
-            //
-            // Now an error, because it now means what it says. If the alias
-            // names a target xlings knows about, the honest finding is that
-            // the target has no active version -- Check 2.7 already reported
-            // it against the release, with a remedy that fixes both -- and
-            // repeating it here as an alias defect would send the user after
-            // the wrong thing.
-            if (const auto* aliasVi = xvm::get_vinfo(st.db, aliasProg);
-                aliasVi && xvm::has_program_kind(st.db, aliasProg)) {
-                continue;
-            }
-            add({
-                .kind    = FindingKind::AliasUnresolved,
-                .level   = FindingLevel::Error,
-                .target  = name,
-                .version = version,
-                .detail  = std::format(
-                    "{} alias '{}' resolves to nothing — not in {}, not a "
-                    "sibling command in {}, not on PATH",
-                    xvm::display_coordinate(name, version), aliasProg,
-                    Config::display_path(expanded),
-                    Config::display_path(p.binDir)),
-            });
-        }
-    }
-
-    // Check 4: the binding state itself.
-    //
-    // Everything above looks at shims and payloads. None of it can see a
-    // release whose members disagree about which release they are, or an
-    // active toolchain whose members drifted apart -- and those are exactly the
-    // states that make `xlings use` refuse.
-    auto bindingFindings = xvm::inspect_binding_state(st.db, st.ws);
-
-    // Sysroot ownership. Reported only for destinations a package declares,
-    // not for the whole tree: the subos carries the host image, so listing
-    // every unmanaged entry would bury the two or three that matter.
-    {
-        std::vector<xvm::SysrootEntry> entries;
-        for (const auto& [target, version] : st.ws) {
-            auto infoIt = st.db.find(target);
-            if (infoIt == st.db.end()) continue;
-            auto dataIt = infoIt->second.versions.find(version);
-            if (dataIt == infoIt->second.versions.end()) continue;
-            const auto& dst = dataIt->second.fileDst;
-            if (dst.empty()) continue;
-            const auto abs = p.subosDir / dst;
-            std::error_code ec;
-            if (!fs::exists(abs, ec) && !fs::is_symlink(abs, ec)) continue;
-            xvm::SysrootEntry entry{.path = dst};
-            if (fs::is_symlink(abs, ec)) {
-                entry.linkTarget = fs::read_symlink(abs, ec).string();
-                if (ec) entry.linkTarget.clear();
-            }
-            entries.push_back(std::move(entry));
-        }
-        // Dangling links, scanned rather than derived from the workspace.
-        //
-        // The loop above only visits destinations the ACTIVE selection
-        // declares, and the links that matter here are precisely the ones
-        // nothing declares any more: the package was removed, or was
-        // installed by a run whose payload store is gone. Scanning is cheap
-        // (the header farm is one link per top-level entry) and it is the
-        // only way to see them at all.
-        //
-        // Every subos, not just the active one. The damage that produces
-        // these links is not something the user does from inside the subos it
-        // lands in -- the measured case was an isolated run that materialized
-        // headers into the real home's `dev-hello` while the user was working
-        // in `default` -- so "only look where you happen to be standing"
-        // guarantees the report misses it. Repair still only touches the
-        // active subos (the multi-subos boundary: another subos may be live
-        // in another shell); the others get named, with the command that
-        // fixes them.
-        struct SysrootScanRoot {
-            std::string name;      // empty => the active selection
-            fs::path    root;
-        };
-        std::vector<SysrootScanRoot> sysrootRoots{{{}, p.subosDir}};
-        {
-            std::error_code sec;
-            const auto activeRoot = fs::weakly_canonical(p.subosDir, sec);
-            for (const auto& name : Config::list_subos_names()) {
-                auto root = p.homeDir / "subos" / name;
-                std::error_code rec;
-                if (fs::weakly_canonical(root, rec) == activeRoot) continue;
-                sysrootRoots.push_back({name, std::move(root)});
-            }
-        }
-
-        // Payloads whose files and whose records disagree.
-        //
-        // Walks the STORE, not the version database -- which is the whole
-        // point. Every other check here starts from a DB entry and asks
-        // whether the files behind it are sound; this one starts from files
-        // that no DB entry mentions. A package that registered nothing is
-        // invisible to a DB walk by construction, and invisible is exactly how
-        // it presented: `xlings info` said `installed`, `xlings list` agreed,
-        // and no subos held one of its libraries.
-        //
-        // Runs WITHOUT `--deep`. It reads one small file per version directory
-        // and opens no payload, so it costs a few hundred stats on a large
-        // home -- the deep audit's price is readelf per binary, and this is
-        // nothing like it. Putting it behind `--deep` would hide the finding
-        // from the default command, which is the command people run.
-        {
-            const xim::LedgerIndex ledgerIndex(st.db, st.homeStr);
-            std::error_code sec;
-            for (const auto& storeRoot : {Config::global_data_dir() / "xpkgs",
-                                          Config::project_data_dir() / "xpkgs"}) {
-                if (!fs::is_directory(storeRoot, sec)) continue;
-                for (const auto& pkgDir : platform::dir_entries(storeRoot)) {
-                    if (!pkgDir.is_directory()) continue;
-                    const auto storeName = pkgDir.path().filename().string();
-                    const auto sep = storeName.find("-x-");
-                    const auto ns = sep == std::string::npos
-                        ? std::string{} : storeName.substr(0, sep);
-                    const auto name = sep == std::string::npos
-                        ? storeName : storeName.substr(sep + 3);
-                    for (const auto& verDir :
-                            platform::dir_entries(pkgDir.path())) {
-                        if (!verDir.is_directory()) continue;
-                        const auto version =
-                            verDir.path().filename().string();
-                        const auto coordinate = ns.empty()
-                            ? std::format("{}@{}", name, version)
-                            : std::format("{}:{}@{}", ns, name, version);
-                        const auto remedy =
-                            std::format("xlings install {}", coordinate);
-
-                        if (xim::stamped_incomplete(verDir.path())) {
-                            add({
-                                .kind    = FindingKind::IncompletePayload,
-                                .level   = FindingLevel::Error,
-                                .target  = name,
-                                .version = version,
-                                .detail  = std::format(
-                                    "{} did not finish installing; its payload "
-                                    "is on disk and nothing registered it",
-                                    coordinate),
-                                .remedy  = remedy,
-                            });
-                            continue;
-                        }
-                        if (xim::unverifiable_stamped_payload(
-                                ledgerIndex, ns, name, version,
-                                verDir.path())) {
-                            add({
-                                .kind    = FindingKind::UnverifiedPayload,
-                                .level   = FindingLevel::Notice,
-                                .target  = name,
-                                .version = version,
-                                .detail  = std::format(
-                                    "{} is installed but the version database "
-                                    "references none of it -- it may register "
-                                    "nothing by design, or its install may "
-                                    "have registered nothing",
-                                    coordinate),
-                                .remedy  = remedy,
-                            });
-                        }
-                    }
-                }
-            }
-        }
-
-        struct PayloadAuditRoot {
-            fs::path path;
-            std::string target;
-            std::string storeName;
-            std::string version;
-        };
-        std::vector<PayloadAuditRoot> payloadAuditRoots;
-        if (audit.deep) {
-            if (audit.scope) {
-                const auto& match = *audit.scope;
-                const auto storeName = xim::package_store_name(
-                    match.namespaceName, match.name);
-                const auto path = audit_payload_dir_(match);
-                std::error_code sec;
-                if (fs::is_directory(path, sec)) {
-                    payloadAuditRoots.push_back({
-                        .path = path,
-                        .target = match.canonicalName,
-                        .storeName = storeName,
-                        .version = match.version,
-                    });
-                }
-            } else {
-                std::error_code sec;
-                const auto store = Config::paths().dataDir / "xpkgs";
-                if (fs::is_directory(store, sec)) {
-                    for (const auto& pkgDir : platform::dir_entries(store)) {
-                        if (!pkgDir.is_directory()) continue;
-                        const auto storeName = pkgDir.path().filename().string();
-                        for (const auto& verDir :
-                                platform::dir_entries(pkgDir.path())) {
-                            if (!verDir.is_directory()) continue;
-                            payloadAuditRoots.push_back({
-                                .path = verDir.path(),
-                                .target = storeName,
-                                .storeName = storeName,
-                                .version = verDir.path().filename().string(),
-                            });
-                        }
-                    }
-                }
-            }
-        }
-
-        // Loader and libc from one payload, over what is already on disk.
-        //
-        // The install path refuses to create a split, so anything found here
-        // predates that check or was written by hand. Scanned per payload
-        // rather than per subos because the fault lives in the payload: one
-        // bad binary is bad in every subos that uses it.
-        //
-        // Same implementation the installer asserts with -- deliberately.
-        // Report and repair have drifted three times in this repo, and it
-        // always looks the same from outside: doctor keeps reporting what
-        // `--fix` claims to have fixed.
-        // Progress, because this loop is the reason `--fix` looks dead.
-        //
-        // Measured on a 124-payload / 71 GB home: 145 seconds between the line
-        // announcing the audit and the first result, with nothing in between.
-        // A user cannot tell scanning from hung from dead, and this repo's
-        // usual failure is the reverse -- failure that looks like success --
-        // so the reflex to distrust silence is not there.
-        //
-        // RATE-LIMITED BY TIME, NOT BY COUNT, and silent for the first
-        // seconds. A home small enough to finish quickly prints nothing extra;
-        // only a run long enough to be mistaken for a hang starts reporting.
-        // Tying it to the payload count instead would put a line per payload on
-        // a home that finished in two seconds, and none on the one that needed
-        // them.
-        //
-        // GRANULARITY LIMIT, measured and not hidden: the tick fires between
-        // payloads, so a single large payload still produces one silent
-        // stretch as long as its own scan. On the home this was written
-        // against that was 26 seconds for one payload, down from 145 for the
-        // whole run. Going finer means a progress callback inside
-        // `elfcheck::scan_payload`, which is a shared module and a wider
-        // change; the name of the payload being scanned is emitted BEFORE the
-        // wait, so the remaining silence is at least attributed.
-        //
-        // Both event kinds: the plain CLI renders LogEvent and ignores
-        // ProgressEvent, while the TUI and the agent protocol consume
-        // ProgressEvent. Emitting only one leaves the other silent.
-        {
-        using audit_clock_ = std::chrono::steady_clock;
-        const auto auditStarted = audit_clock_::now();
-        auto auditLastSpoke = auditStarted;
-        std::size_t auditDone = 0;
-        const auto auditTotal = payloadAuditRoots.size();
-        auto auditTick = [&](const auto& root) {
-            if (!audit.onProgress) return;
-            const auto now = audit_clock_::now();
-            using namespace std::chrono;
-            if (duration_cast<seconds>(now - auditStarted).count() < 1) return;
-            if (duration_cast<seconds>(now - auditLastSpoke).count() < 2) return;
-            auditLastSpoke = now;
-            audit.onProgress(auditDone, auditTotal, root.target, root.version);
-        };
-        for (const auto& root : payloadAuditRoots) {
-            auditTick(root);
-            ++auditDone;
-            for (const auto& f : elfcheck::scan_payload(root.path)) {
-                add({
-                    .kind   = FindingKind::LoaderLibcSplit,
-                    .level  = FindingLevel::Error,
-                    .target = root.target,
-                    .version = root.version,
-                    .detail = elfcheck::describe(f),
-                    .remedy = std::format(
-                        "xlings install {}@{} --force",
-                        root.target, root.version),
-                });
-            }
-        }
-        }
-
-        // Name resolution under our own glibc.
-        //
-        // Run for real rather than inferred, and this is the one place where
-        // that distinction is cheap: the glibc payload ships `bin/getent`, so
-        // executing it under its own loader exercises the exact dlopen path a
-        // switched payload will take. Reading the module list off disk would
-        // only tell us which files exist.
-        //
-        // Doing it in-process was the obvious shortcut and it is wrong: this
-        // binary has its own libc (a static musl build has no NSS at all), so
-        // an in-process getpwuid answers a question about xlings rather than
-        // about the payload every other package is about to depend on.
-        //
-        // Notice, not Error, when it works: this is the cell that is supposed
-        // to be boring. When it fails it is an Error, because a home whose
-        // packages resolve no users is broken in a way nothing else reports.
-#ifdef __linux__
-        for (const auto& root : payloadAuditRoots) {
-            const auto& storeName = root.storeName;
-            // `<ns>-x-glibc`, any namespace.
-            if (!storeName.ends_with("-x-glibc")) continue;
-            std::error_code sec;
-            const auto lib64  = root.path / "lib64";
-            const auto loader = lib64 / "ld-linux-x86-64.so.2";
-            const auto getent = root.path / "bin" / "getent";
-            if (!fs::is_regular_file(loader, sec)) continue;
-            if (!fs::is_regular_file(getent, sec)) continue;
-
-            const auto& version = root.version;
-            const auto cmd = std::format(
-                "\"{}\" --library-path \"{}\" \"{}\" passwd {} 2>/dev/null",
-                loader.string(), lib64.string(), getent.string(),
-                ::geteuid());
-            auto [rc, out] = platform::run_command_capture(cmd);
-
-            if (rc == 0 && !out.empty()) {
-                add({
-                    .kind    = FindingKind::NssResolution,
-                    .level   = FindingLevel::Notice,
-                    .target  = storeName,
-                    .version = version,
-                    .detail  = std::format(
-                        "glibc {}: resolves the current user "
-                        "(getent passwd {} under our loader)",
-                        version, ::geteuid()),
-                });
-                continue;
-            }
-
-            // Which backends this host asks for that we do not ship. Part of
-            // the finding, not a separate check: it is the only actionable
-            // thing about the failure.
-            std::string missing;
-            {
-                std::ifstream nss("/etc/nsswitch.conf");
-                std::set<std::string> seen;
-                for (std::string line; std::getline(nss, line);) {
-                    if (auto h = line.find('#'); h != std::string::npos)
-                        line.resize(h);
-                    auto colon = line.find(':');
-                    if (colon == std::string::npos) continue;
-                    auto rest = line.substr(colon + 1);
-                    // `[NOTFOUND=return]` is control flow, not a module.
-                    while (true) {
-                        auto ob = rest.find('[');
-                        if (ob == std::string::npos) break;
-                        auto cb = rest.find(']', ob);
-                        if (cb == std::string::npos) {
-                            rest.resize(ob);
-                            break;
-                        }
-                        rest.erase(ob, cb - ob + 1);
-                    }
-                    std::istringstream toks(rest);
-                    for (std::string mod; toks >> mod;) {
-                        if (!seen.insert(mod).second) continue;
-                        if (!fs::is_regular_file(
-                                lib64 / ("libnss_" + mod + ".so.2"), sec)) {
-                            if (!missing.empty()) missing += ", ";
-                            missing += mod;
-                        }
-                    }
-                }
-            }
-
-            add({
-                .kind    = FindingKind::NssResolution,
-                .level   = FindingLevel::Error,
-                .target  = storeName,
-                .version = version,
-                .detail  = std::format(
-                    "glibc {}: does NOT resolve the current user under our "
-                    "loader{}. Any package switched to this interpreter will "
-                    "see no user, silently.",
-                    version,
-                    missing.empty()
-                        ? std::string{}
-                        : std::format(
-                            " -- /etc/nsswitch.conf names backend(s) this "
-                            "payload does not ship: {}", missing)),
-            });
-        }
-#endif
-
-        for (const auto& scanRoot : sysrootRoots) {
-            const bool isActive = scanRoot.name.empty();
-            for (const auto& sub : {"usr/include", "usr/lib", "usr/lib64",
-                                    "usr/bin"}) {
-                const auto dir = scanRoot.root / sub;
-                std::error_code dec;
-                if (!fs::is_directory(dir, dec)) continue;
-                for (const auto& entry : platform::dir_entries(dir)) {
-                    std::error_code lec;
-                    // Both halves are required. A dangling link IS a symlink
-                    // and is NOT `exists()`; testing only existence reads it
-                    // as "already gone" -- the mistake that let #423's test
-                    // pass while the links were still on disk.
-                    if (!fs::is_symlink(entry.path(), lec)) continue;
-                    if (fs::exists(entry.path(), lec)) continue;
-                    auto target = fs::read_symlink(entry.path(), lec);
-                    add({
-                        .kind    = FindingKind::SysrootDangling,
-                        .level   = FindingLevel::Warning,
-                        .detail  = std::format(
-                            "{}{} points at {}, which does not exist",
-                            isActive ? std::string{}
-                                     : std::format("[{}] ", scanRoot.name),
-                            Config::display_path(entry.path()),
-                            lec ? std::string("(unreadable)")
-                                : Config::display_path(target)),
-                        .remedy  = isActive
-                            ? "xlings self doctor --fix"
-                            : std::format("XLINGS_ACTIVE_SUBOS={} xlings "
-                                          "self doctor --fix", scanRoot.name),
-                        // Empty for the active subos -- that is what `--fix`
-                        // keys on, so a finding from elsewhere cannot be
-                        // repaired by accident.
-                        .subos = isActive
-                            ? std::vector<std::string>{}
-                            : std::vector<std::string>{scanRoot.name},
-                        .shimPath = entry.path(),
-                    });
-                }
-            }
-        }
-
-        auto ownership = xvm::inspect_sysroot_ownership(
-            st.db, st.ws, entries, (p.dataDir / "xpkgs").string());
-        bindingFindings.insert(bindingFindings.end(),
-                               std::make_move_iterator(ownership.begin()),
-                               std::make_move_iterator(ownership.end()));
-    }
-
-    // One line per (code, entry), not per field.
-    //
-    // A single legacy anchor carries one dangling edge per program it bound --
-    // five for each of the two gcc flavours on the measured home -- and they
-    // are one problem with one cure. Fourteen lines saying the same thing
-    // about five entries is the noise this collapse exists for; the fields are
-    // still named, on the one line.
-    std::map<std::tuple<std::string, std::string, std::string>,
-             std::vector<const xvm::BindingFinding*>> bindingGroups;
-    std::vector<std::tuple<std::string, std::string, std::string>> bindingOrder;
-    for (const auto& f : bindingFindings) {
-        const auto key = std::tuple{f.code, f.target, f.version};
-        auto [it, inserted] = bindingGroups.try_emplace(key);
-        if (inserted) bindingOrder.push_back(key);
-        it->second.push_back(&f);
-    }
-    for (const auto& key : bindingOrder) {
-        const auto& group = bindingGroups.at(key);
-        const auto& f = *group.front();
-        std::string detail = f.summary;
-        if (!f.target.empty()) {
-            detail += std::format(
-                " [{}]", xvm::display_coordinate(f.target, f.version));
-        }
-        std::string fields;
-        for (const auto* member : group) {
-            if (member->field.empty()) continue;
-            if (!fields.empty()) fields += ", ";
-            fields += member->field;
-        }
-        if (!fields.empty()) {
-            detail += std::format(" at {}", fields);
-        }
-        // The code stays in the line. It is the only greppable handle a user
-        // or a bug report has on which invariant broke, and the hint alone is
-        // prose.
-        detail += std::format(" — {} — {}", f.code, f.hint);
-        add({
-            .kind    = FindingKind::BindingState,
-            // A notice describes state the upgrade inherited rather than
-            // created, so it does not colour the run red.
-            .level   = f.severity == xvm::BindingSeverity::Notice
-                           ? FindingLevel::Notice : FindingLevel::Error,
-            .target  = f.target,
-            .version = f.version,
-            .detail  = std::move(detail),
-        });
-    }
-
-    // Check 5: what the OTHER subos of this home point at.
-    //
-    // Never counted toward the exit code. The exit code answers "is the subos
-    // I am in healthy", and it has to stay answerable. Printing it is the
-    // point: before this, a subos whose active version was taken out from
-    // under it had no command that mentioned it.
-    // A remedy that cannot work is not a remedy.
-    //
-    // A dangling binding edge does not merely make `xlings use` refuse -- it
-    // makes registration validation refuse, so `xlings install <pkg>` fails on
-    // it too. Measured on a real home: of the three install commands the
-    // report printed, two exited 1 with `xvm-binding-validation-failed`, and
-    // only `self doctor --fix` cleared them (it prunes the edges before it
-    // runs the ladder). Printing the install anyway is how the user ends up
-    // back at the loop this whole change exists to break: run the command,
-    // watch it fail, be told to run doctor.
-    //
-    // Deliberately coarse -- ANY dangling edge redirects EVERY payload remedy.
-    // Which edge blocks which package is not decidable from here (the
-    // legacy-component walk can reach arbitrary edges), and the coarse answer
-    // is the true one: `--fix` is what repairs this home, whatever the entry.
-    const bool danglingEdges = std::ranges::any_of(
-        bindingFindings, [](const xvm::BindingFinding& f) {
-            return f.code == "xvm-legacy-edge-dangling";
-        });
-    if (danglingEdges) {
-        for (auto& f : scan.findings) {
-            if (f.kind != FindingKind::BrokenPayload || f.remedy.empty()) {
-                continue;
-            }
-            f.remedy = "xlings self doctor --fix";
-        }
-    }
-
-    for (const auto& f : xvm::inspect_subos_references(st.db, st.otherSubos)) {
-        add({
-            .kind    = FindingKind::OtherSubos,
-            .level   = f.severity == xvm::BindingSeverity::Notice
-                           ? FindingLevel::Notice : FindingLevel::Warning,
-            .target  = f.target,
-            .version = f.version,
-            .detail  = std::format("{} — {} — {}", f.summary, f.code, f.hint),
-        });
-    }
-
-    return scan;
-}
+             const AuditSelection& audit);
 
 // ── repair ───────────────────────────────────────────────────────────
 
@@ -2120,711 +341,6 @@ struct RepairReport {
     bool regressed { false };
 };
 
-// Everything below the payload layer: shims and pure state-file edits. All of
-// it is local, none of it can fail halfway in a way the user has to unpick.
-void repair_local_(const DoctorState& st, const Scan& scan,
-                   RepairReport& out) {
-    auto& p = Config::paths();
-    const auto note = [&](std::string label, std::string text) {
-        out.notes.emplace_back(std::move(label), std::move(text));
-    };
-
-    // Subos manifest repairs. Driven by the findings detection produced, not
-    // by a second reading of the rules -- so what `--fix` touches is exactly
-    // what was reported.
-    {
-        namespace mf = xlings::subos::manifest;
-        const bool wantsBlock = std::ranges::any_of(
-            scan.findings, [](const Finding& f) {
-                return f.kind == FindingKind::SubosManifest
-                       && f.remedy == "xlings self doctor --fix";
-            });
-        std::vector<std::string> orphans;
-        for (const auto& f : scan.findings)
-            if (f.kind == FindingKind::SubosEnvOrphan) orphans.push_back(f.version);
-
-        // A runtime declaration that contradicts what this subos actually runs.
-        // Keyed on the finding, and the adopted value is read back through the
-        // same `observed_runtime` the detection used, so the repairer cannot
-        // decide something the reporter did not say.
-        //
-        // Only the Error shape is adopted: a declaration with NO active runtime
-        // is a cold intent (`subos new --runtime X` before installing X), and
-        // overwriting that would undo a decision someone took.
-        std::string adoptRuntime;
-        for (const auto& f : scan.findings) {
-            if (f.kind != FindingKind::SubosRuntimeMissing) continue;
-            if (f.level != FindingLevel::Error) continue;
-            if (!f.remedy.starts_with("xlings self doctor --fix")) continue;
-            adoptRuntime = f.version;   // the declared binding; family only
-            break;
-        }
-
-        // A contested binding is deliberately NOT repaired here. It is reported
-        // precisely because nothing can say which version was meant -- the
-        // package has no active version -- and picking the highest, or the
-        // newest on disk, would be this codebase's recurring defect rather than
-        // a repair: a second answerer invented at the read end. Its remedy is
-        // `xlings use`, which makes the choice a decision someone took.
-
-        if (wantsBlock || !orphans.empty() || !adoptRuntime.empty()) {
-            auto doc = mf::read_document(p.subosDir);
-            nlohmann::json document = doc ? *doc : nlohmann::json::object();
-            if (!doc && fs::exists(mf::config_path(p.subosDir))) {
-                // Unreadable rather than absent. Detection already said so and
-                // offered no `--fix` remedy; do not overwrite it here either.
-                note(glyph::mark(glyph::failed, "subos manifest"),
-                     std::format("{} is not readable JSON; left untouched",
-                                 Config::display_path(
-                                     mf::config_path(p.subosDir))));
-            } else {
-                bool changed = false;
-                if (!document.contains("workspace"))
-                    document["workspace"] = nlohmann::json::object();
-                if (wantsBlock) {
-                    // A broken block can still carry a valid runtime binding.
-                    // Rewriting with DEFAULT_RUNTIME here used to re-declare
-                    // the subos against whatever the current default is — a
-                    // repair must not change what the subos IS.
-                    const auto keptRuntime =
-                        mf::preserved_runtime(document, mf::DEFAULT_RUNTIME);
-                    document[std::string(mf::BLOCK)] = mf::make_block(
-                        keptRuntime,
-                        std::format("xlings {}", Info::VERSION),
-                        platform::host_glibc_version());
-                    changed = true;
-                    note(glyph::mark(glyph::bullet, "subos manifest"),
-                         std::format("described subos '{}' (runtime {})",
-                                     p.activeSubos, keptRuntime));
-                }
-                if (!adoptRuntime.empty()) {
-                    const auto observed = mf::observed_runtime(
-                        document, mf::binding_name(adoptRuntime));
-                    if (observed.empty()) {
-                        note(glyph::mark(glyph::warn, "subos runtime"),
-                             std::format("cannot adopt: subos '{}' has no "
-                                         "active {} to record",
-                                         p.activeSubos,
-                                         mf::binding_name(adoptRuntime)));
-                    } else if (observed != adoptRuntime) {
-                        document[std::string(mf::BLOCK)]["runtime"] = observed;
-                        changed = true;
-                        note(glyph::mark(glyph::bullet, "subos runtime"),
-                             std::format("subos '{}' now declares {} "
-                                         "(was {}, never activated here)",
-                                         p.activeSubos, observed,
-                                         adoptRuntime));
-                    }
-                }
-                for (const auto& binding : orphans) {
-                    if (!mf::remove_provider(document, binding)) continue;
-                    changed = true;
-                    note(glyph::mark(glyph::bullet, "subos env dropped"),
-                         std::format("{} is not installed here", binding));
-                }
-
-                if (changed) {
-                    try {
-                        platform::write_string_to_file(
-                            mf::config_path(p.subosDir).string(),
-                            document.dump(2));
-                    } catch (const std::exception& e) {
-                        note(glyph::mark(glyph::failed, "subos manifest"),
-                             std::format("could not write {}: {}",
-                                         Config::display_path(
-                                             mf::config_path(p.subosDir)),
-                                         std::string(e.what())));
-                    }
-                }
-            }
-        }
-    }
-
-    for (const auto& f : scan.findings) {
-        if (f.kind == FindingKind::MissingShim) {
-            if (!fs::exists(st.xlingsBin)) continue;
-            std::error_code ec;
-            fs::create_directories(p.binDir, ec);
-            if (create_shim(st.xlingsBin, f.shimPath) != LinkResult::Failed) {
-                note(glyph::mark(glyph::bullet, "shim recreated"), Config::display_path(f.shimPath));
-            } else {
-                note(glyph::mark(glyph::failed, "shim repair failed"), std::format(
-                    "could not recreate {}",
-                    Config::display_path(f.shimPath)));
-            }
-        } else if (f.kind == FindingKind::SysrootDangling) {
-            // Another subos's link is reported, not removed. A second shell
-            // can have that subos active right now, and repairing state out
-            // from under it is the multi-subos boundary this codebase keeps
-            // everywhere else. The finding carries the exact command.
-            if (!f.subos.empty()) continue;
-            std::error_code ec;
-            // remove(), not remove_all(): the link is being deleted, and if
-            // it were somehow followable, remove_all would delete the
-            // package payload behind it.
-            fs::remove(f.shimPath, ec);
-            if (!ec) {
-                note(glyph::mark(glyph::bullet, "dangling link removed"),
-                     Config::display_path(f.shimPath));
-            } else {
-                note(glyph::mark(glyph::failed, "sysroot repair failed"),
-                     std::format("could not remove {}",
-                                 Config::display_path(f.shimPath)));
-            }
-        } else if (f.kind == FindingKind::OrphanShim
-                || f.kind == FindingKind::LegacyAliasShim) {
-            std::error_code ec;
-            fs::remove(f.shimPath, ec);
-            if (!ec) {
-                note(glyph::mark(glyph::bullet, "shim removed"), Config::display_path(f.shimPath));
-            } else {
-                note(glyph::mark(glyph::failed, "shim repair failed"), std::format(
-                    "could not remove {}", Config::display_path(f.shimPath)));
-            }
-        }
-    }
-}
-
-// The three state-file repairs, in an order that matters.
-//
-// Dangling edges first: they are repairable without guessing, and leaving one
-// in place keeps the release it names unresolvable, which would make the
-// deactivation pass below see a problem that is really this one. Unregistered
-// actives next, for the same reason in reverse: an active pointer into nothing
-// makes a release look incoherent when it is merely absent.
-void repair_state_(RepairReport& out) {
-    const auto note = [&](std::string label, std::string text) {
-        out.notes.emplace_back(std::move(label), std::move(text));
-    };
-
-    auto db = Config::versions();
-    if (auto pruning = xvm::plan_dangling_edge_pruning(db); !pruning.empty()) {
-        auto lock = xvm::acquire_state_lock(Config::paths().homeDir);
-        if (!lock) {
-            note(glyph::mark(glyph::failed, "binding state"), std::format(
-                "cannot drop dangling binding edges: {}", lock.error()));
-        } else {
-            Config::reload_state();
-            auto& mutableDb = Config::versions_mut();
-            const auto replanned = xvm::plan_dangling_edge_pruning(mutableDb);
-            if (xvm::apply_dangling_edge_pruning(mutableDb, replanned) > 0) {
-                Config::save_versions();
-                for (const auto& e : replanned.edges) {
-                    note(glyph::mark(glyph::bullet, "edge dropped"), std::format(
-                        "{} no longer points at unregistered {}",
-                        xvm::display_coordinate(e.target, e.version),
-                        xvm::display_coordinate(e.peerTarget, e.peerVersion)));
-                }
-            }
-        }
-    }
-
-    // Baked subos paths. Rewritten to `<home>/subos/current`, NOT to the
-    // subos this run happens to resolve to.
-    //
-    // Rewriting to the active subos only moved the pin: the record went on
-    // naming one concrete subos, so the very next `doctor` in a different one
-    // reported it again, and `--fix` could never clear its own finding.
-    // `current` is the symlink `self init` creates and `subos use --global`
-    // maintains, so the repaired record is correct from every subos at once --
-    // and exec-time normalization still substitutes the truly active
-    // directory, including under XLINGS_ACTIVE_SUBOS and project subos, where
-    // a symlink cannot follow.
-    {
-        const auto homeStr = Config::paths().homeDir.string();
-        const auto has_baked = [&](const xvm::VersionDB& src) {
-            if (homeStr.empty()) return false;
-            for (const auto& [name, vinfo] : src) {
-                for (const auto& [version, vdata] : vinfo.versions) {
-                    if (!vdata.alias.empty()
-                        && xvm::pin_subos_paths(vdata.alias[0], homeStr)
-                               != vdata.alias[0]) {
-                        return true;
-                    }
-                    for (const auto& [k, v] : vdata.envs) {
-                        if (xvm::pin_subos_paths(v, homeStr) != v) return true;
-                    }
-                }
-            }
-            return false;
-        };
-        if (has_baked(Config::versions())) {
-            auto lock = xvm::acquire_state_lock(Config::paths().homeDir);
-            if (!lock) {
-                note(glyph::mark(glyph::failed, "subos path"), std::format(
-                    "cannot rewrite install-time subos paths: {}",
-                    lock.error()));
-            } else {
-                Config::reload_state();
-                auto& mutableDb = Config::versions_mut();
-                std::size_t rewritten = 0;
-                for (auto& [name, vinfo] : mutableDb) {
-                    for (auto& [version, vdata] : vinfo.versions) {
-                        bool touched = false;
-                        // The real migration: the concrete subos becomes the
-                        // placeholder, so the finding disappears instead of
-                        // moving to whichever subos ran doctor. Rewriting it
-                        // to another subos -- including `current` -- would
-                        // leave a subos path in a shared database, and the
-                        // next run would be right to report it again.
-                        for (auto& a : vdata.alias) {
-                            auto fixed = xvm::pin_subos_paths(a, homeStr);
-                            if (fixed != a) { a = std::move(fixed); touched = true; }
-                        }
-                        // Envs get the same treatment, which they could not
-                        // when this was a flag: the defect is a property of
-                        // the value, not of any particular argument syntax.
-                        for (auto& [k, v] : vdata.envs) {
-                            auto fixed = xvm::pin_subos_paths(v, homeStr);
-                            if (fixed != v) { v = std::move(fixed); touched = true; }
-                        }
-                        if (touched) {
-                            ++rewritten;
-                            note(glyph::mark(glyph::bullet, "subos path"),
-                                 std::format(
-                                     "{} no longer records a subos",
-                                     xvm::display_coordinate(name, version)));
-                        }
-                    }
-                }
-                if (rewritten > 0) Config::save_versions();
-            }
-        }
-    }
-
-    db = Config::versions();
-    auto ws = Config::effective_workspace();
-    if (auto stale = xvm::plan_unregistered_active_deactivation(db, ws);
-        !stale.empty()) {
-        auto lock = xvm::acquire_state_lock(Config::paths().homeDir);
-        if (!lock) {
-            note(glyph::mark(glyph::failed, "binding state"), std::format(
-                "cannot deactivate unregistered versions: {}", lock.error()));
-        } else {
-            Config::reload_state();
-            auto& mutableWs = Config::workspace_mut();
-            std::size_t dropped = 0;
-            for (const auto& target : stale) {
-                const auto it = mutableWs.find(target);
-                if (it == mutableWs.end()) continue;
-                note(glyph::mark(glyph::bullet, "deactivated"), std::format(
-                    "{} was active at a version that is not registered — run "
-                    "`xlings use {} <version>` to select one",
-                    xvm::display_coordinate(target, it->second), target));
-                mutableWs.erase(it);
-                ++dropped;
-            }
-            if (dropped > 0) Config::save_workspace();
-        }
-    }
-
-    db = Config::versions();
-    ws = Config::effective_workspace();
-    if (auto plan = xvm::plan_incoherent_deactivation(db, ws);
-        !plan.targets.empty()) {
-        auto lock = xvm::acquire_state_lock(Config::paths().homeDir);
-        if (!lock) {
-            note(glyph::mark(glyph::failed, "binding state"), std::format(
-                "cannot deactivate incoherent releases: {}", lock.error()));
-        } else {
-            Config::reload_state();
-            auto& mutableWs = Config::workspace_mut();
-            std::size_t dropped = 0;
-            for (const auto& [target, label] : plan.targets) {
-                if (mutableWs.erase(target) == 0) continue;
-                ++dropped;
-                note(glyph::mark(glyph::bullet, "deactivated"), std::format(
-                    "{} (was part of {}) — run `xlings use {} <version>` to "
-                    "select a release", target, label, target));
-            }
-            if (dropped > 0) Config::save_workspace();
-        }
-    }
-}
-
-// Other subos: the deletions doctor could already describe exactly.
-//
-// Nothing is installed and nothing is chosen. `active` entries pointing at a
-// version the shared database does not have are dropped, and `installed[]`
-// entries likewise -- both are references into nothing, and both are what the
-// report used to hand back as a list of commands for the user to run one subos
-// at a time.
-void repair_other_subos_(const DoctorState& st, RepairReport& out) {
-    auto plan = xvm::plan_subos_metadata_repair(Config::versions(),
-                                                st.otherSubos);
-    if (plan.empty()) return;
-
-    auto lock = xvm::acquire_state_lock(Config::paths().homeDir);
-    if (!lock) {
-        out.notes.emplace_back(glyph::mark(glyph::failed, "other subos"), std::format(
-            "cannot repair other subos state: {}", lock.error()));
-        return;
-    }
-
-    for (const auto& entry : plan.entries) {
-        const auto snapshotIt = std::ranges::find_if(
-            st.otherSnapshots,
-            [&](const auto& s) { return s.name == entry.subos; });
-        if (snapshotIt == st.otherSnapshots.end()) continue;
-
-        // Re-read: the snapshot was taken before the repairs above ran, and
-        // one of them may have rewritten this very file.
-        auto fresh = profile::load_subos_snapshots(Config::paths().homeDir);
-        const auto freshIt = std::ranges::find_if(
-            fresh, [&](const auto& s) { return s.dir == snapshotIt->dir; });
-        if (freshIt == fresh.end()) continue;
-
-        auto workspace = freshIt->workspace;
-        const auto dropped =
-            xvm::apply_subos_metadata_repair(workspace, entry);
-        if (dropped == 0) continue;
-        if (!profile::save_subos_workspace(snapshotIt->dir, workspace)) {
-            out.notes.emplace_back(glyph::mark(glyph::failed, "other subos"), std::format(
-                "could not write the state file of subos '{}'", entry.subos));
-            continue;
-        }
-        for (const auto& target : entry.deactivate) {
-            out.notes.emplace_back(glyph::mark(glyph::bullet, "other subos repaired"), std::format(
-                "{}: deactivated '{}' — it named a version that is not "
-                "registered; run `xlings subos use {}` then `xlings use {} "
-                "<version>` to choose one", entry.subos, target,
-                entry.subos, target));
-        }
-        for (const auto& [target, version] : entry.dropInstalled) {
-            out.notes.emplace_back(glyph::mark(glyph::bullet, "other subos repaired"), std::format(
-                "{}: dropped stale installed entry {}", entry.subos,
-                xvm::display_coordinate(target, version)));
-        }
-    }
-}
-
-// ── the payload ladder ───────────────────────────────────────────────
-
-// `onStep`, because the repair below shells out to `xlings install` and that
-// can be a large download with nothing on screen.
-//
-// In a plain terminal the child's own output is visible. In the agent and TUI
-// modes it is NOT: `platform::exec` appends `>/dev/null 2>&1` when
-// `tui_mode_` is set (platform.cppm), so the same repair is a genuinely
-// silent multi-hundred-megabyte wait there. Saying what is about to run, and
-// that it may download, is the difference between waiting and giving up.
-void repair_payloads_(const DoctorState& st, const Scan& scan,
-                      const CoordinateProbe& probe, bool dryRun,
-                      RepairReport& out,
-                      const std::function<void(std::string_view)>& onStep = {}) {
-    // Collapse the findings onto their owning package: one install per
-    // release, not one per program in it. A broken llvm reports nine targets;
-    // reinstalling llvm nine times would be nine downloads for one problem.
-    std::map<xvm::InstallCoordinate, std::vector<const Finding*>> byOwner;
-    std::vector<const Finding*> unowned;
-    for (const auto& f : scan.findings) {
-        if (f.kind != FindingKind::BrokenPayload) continue;
-        if (auto coord =
-                owning_coordinate_(st.db, f.target, f.version, probe)) {
-            byOwner[*coord].push_back(&f);
-        } else {
-            unowned.push_back(&f);
-        }
-    }
-
-    if (dryRun) {
-        for (const auto& [coord, covered] : byOwner) {
-            out.planned.push_back(std::format(
-                "{}   ({} entr{})", coord.install_command(), covered.size(),
-                covered.size() == 1 ? std::string("y")
-                                    : std::string("ies")));
-        }
-        for (const auto* f : unowned) {
-            out.planned.push_back(std::format(
-                "prune {} (no package provides it and its payload is gone)",
-                xvm::display_coordinate(f->target, f->version)));
-        }
-        return;
-    }
-
-    const CommandRunner run = [](const std::string& cmd) {
-        return platform::exec(cmd);
-    };
-
-    // Repair with the client that is running, not with whatever `xlings`
-    // resolves to on PATH. Normally the same binary; not when doctor was
-    // started by absolute path, and then the repair would be carried out by a
-    // different client than the one that decided what needed repairing.
-    RepairPolicy policy;
-    {
-        const auto self = platform::get_executable_path().string();
-        if (!self.empty() && is_shell_safe_token(self)) policy.client = self;
-    }
-
-    for (const auto& [coord, covered] : byOwner) {
-        if (onStep) {
-            onStep(std::format("repairing {} — running `{}` (this may download)",
-                               coord.package, coord.install_command()));
-        }
-        // R3's remove exited 0 — did the records actually go? Asked of the
-        // FINDINGS the repair covers, not of the package name it ran the
-        // command with: a package name is not a key in the versions DB, so
-        // looking it up there finds nothing and reads as "removed".
-        const RemovalVerifier removalDone =
-            [&](const std::string&, const std::string&) {
-                Config::reload_state();
-                const auto current = Config::versions();
-                for (const auto* c : covered) {
-                    const auto* vi = xvm::get_vinfo(current, c->target);
-                    if (vi && vi->versions.contains(c->version)) return false;
-                }
-                return true;
-            };
-        RepairTask task{
-            .kind          = RepairKind::BrokenPayload,
-            .target        = coord.package,
-            .version       = coord.version,
-            .detail        = std::format("{} broken entr{}", covered.size(),
-                                         covered.size() == 1 ? std::string("y")
-                                                             : std::string("ies")),
-            .coordinate    = coord.canonical(),
-            .reinstallable = true,   // confirmed by the probe above
-        };
-        auto result = repair_one(task, policy, run, removalDone);
-        if (!result.healed) {
-            for (const auto* c : covered) {
-                out.failedEntries.emplace_back(c->target, c->version);
-            }
-            out.notes.emplace_back(glyph::mark(glyph::failed, "repair failed"), std::format(
-                "{} — {}", coord.canonical(),
-                result.note.empty() ? "the finding it covers is still there"
-                                    : result.note));
-        }
-    }
-}
-
-// Activate what is installed and inactive, by running `use`.
-//
-// Deliberately a subprocess and deliberately the exact command the finding
-// prints. Activating a release is not a workspace write: it places the
-// release's libraries and headers in the sysroot and writes a shim per
-// member, and xvm's `use` path is the only code that does all of it. Setting
-// `workspace[name]` here would activate the name and leave the sysroot
-// holding whatever the previous release put there -- the half-switched state
-// plan_use_switch was written to make impossible.
-//
-// `use` moves the WHOLE release, which can take a name from another provider:
-// node's release owns `npm`, and a separately installed npm package may hold
-// that name today. That is not a side effect this hides -- it is what the
-// printed remedy does when the user runs it by hand, and a `--fix` that did
-// something narrower than the command it advertises would be a third
-// behaviour to reason about. The install path is where "do not take a name
-// from another provider" belongs, and that is where it now lives
-// (registration.cppm); by the time doctor is looking at the wreckage, the
-// user has asked for repair.
-void repair_inactive_(const Scan& scan, const std::string& client,
-                      const CommandRunner& run, bool dryRun,
-                      RepairReport& out) {
-    for (const auto& f : scan.findings) {
-        if (f.kind != FindingKind::InactiveInstalled) continue;
-        // Known in advance to be a repair another repair would undo. Not
-        // attempted, and said so out loud: choosing between two packages that
-        // register the same program name is the user's decision, and `--fix`
-        // running `use` here would only start the fight described in
-        // activation_conflict_.
-        if (!f.conflict.empty()) continue;
-        if (!is_shell_safe_token(f.target) || !is_shell_safe_token(f.version)) {
-            out.notes.emplace_back(
-                glyph::mark(glyph::failed, "activation skipped"),
-                std::format("{} — name or version is not a safe shell token",
-                            xvm::display_coordinate(f.target, f.version)));
-            continue;
-        }
-        const auto cmd = std::format("{} use {}@{}", client, f.target,
-                                     f.version);
-        if (dryRun) {
-            out.planned.push_back(cmd);
-            continue;
-        }
-        if (run(cmd + quiet_suffix()) == 0) {
-            out.notes.emplace_back(glyph::mark(glyph::bullet, "activated"),
-                                   std::format("{}@{}", f.target, f.version));
-        } else {
-            out.failedEntries.emplace_back(f.target, f.version);
-            out.notes.emplace_back(
-                glyph::mark(glyph::failed, "activation failed"),
-                std::format("{} — run `{}` to see why",
-                            xvm::display_coordinate(f.target, f.version),
-                            f.remedy));
-        }
-    }
-}
-
-// Re-run the install of a payload whose own stamp records that it failed.
-//
-// Separate from repair_payloads_ and NOT routed through owning_coordinate_,
-// because these findings come from the store rather than the version database
-// and the database is exactly what does not know about them. The coordinate
-// was recovered from the store layout when the finding was made -- the payload
-// path IS the package identity (xvm/owner.cppm) -- so the remedy already names
-// the right package and there is nothing left to resolve.
-//
-// Re-running the install is the whole repair: the failure marker makes
-// `installation_state` report Incomplete, which is what makes the installer
-// run the hook again instead of concluding "already installed" from the files
-// the failure left behind.
-void repair_incomplete_(const Scan& scan, const CommandRunner& run,
-                        bool dryRun, RepairReport& out,
-                        const std::function<void(std::string_view)>& onStep = {}) {
-    for (const auto& f : scan.findings) {
-        if (f.kind != FindingKind::IncompletePayload) continue;
-        if (f.remedy.empty()) continue;
-        // The WHOLE remedy, not just target and version.
-        //
-        // This finding is built by walking the store, so its namespace comes
-        // from a directory NAME on disk rather than from the index -- and the
-        // remedy is handed to a shell. Checking target and version while
-        // letting the namespace through would leave the one component that
-        // this check, alone among the repairs here, takes from the filesystem.
-        if (!is_shell_safe_token(f.target) || !is_shell_safe_token(f.version)
-            || f.remedy.find_first_of(";&|$`\n<>()") != std::string::npos) {
-            out.notes.emplace_back(
-                glyph::mark(glyph::failed, "reinstall skipped"),
-                std::format("{} — its coordinate is not a safe shell token",
-                            xvm::display_coordinate(f.target, f.version)));
-            continue;
-        }
-        if (dryRun) {
-            out.planned.push_back(f.remedy);
-            continue;
-        }
-        // Said out loud for the reason repair_payloads_ documents: in agent
-        // and TUI mode platform::exec silences the child, so an install that
-        // downloads is an indefinite silent wait.
-        if (onStep) {
-            onStep(std::format("reinstalling {} (may download)",
-                               xvm::display_coordinate(f.target, f.version)));
-        }
-        if (run(f.remedy + quiet_suffix()) == 0) {
-            out.notes.emplace_back(glyph::mark(glyph::bullet, "reinstalled"),
-                                   xvm::display_coordinate(f.target, f.version));
-        } else {
-            out.failedEntries.emplace_back(f.target, f.version);
-            out.notes.emplace_back(
-                glyph::mark(glyph::failed, "reinstall failed"),
-                std::format("{} — run `{}` to see why",
-                            xvm::display_coordinate(f.target, f.version),
-                            f.remedy));
-        }
-    }
-}
-
-// The last rung: drop a registration that is provably dead.
-//
-// Runs after the ladder and after a reload, on findings that SURVIVED it. That
-// ordering is the whole safety argument -- pruning is not a guess about
-// whether an entry could be revived, it is what is left once the attempt to
-// revive it has been made and has failed.
-//
-// Three things have to be true, and re-detection has already established the
-// first two:
-//   - the payload is gone, or present with nothing runnable in it and no
-//     release to anchor. There is nothing to lose that has not already been
-//     lost.
-//   - the repair ladder ran and the finding is still there.
-//   - nothing else in the home still resolves through it. The workspace entry
-//     and the installed[] entry go with it, in the same transaction, or the
-//     prune would trade a broken payload for a dangling pointer.
-//
-// What it buys: the eleven `repair skipped` and nine `repair failed` lines on
-// the measured home -- entries whose namespace index no longer exists, and
-// aliases a foreign platform registered -- stop coming back on every run, and
-// the migration marker can finally land.
-void prune_dead_registrations_(const DoctorState& st, const Scan& remaining,
-                               RepairReport& out) {
-    std::vector<std::pair<std::string, std::string>> victims;
-    for (const auto& f : remaining.findings) {
-        if (f.kind != FindingKind::BrokenPayload) continue;
-        // Not if another subos still claims it.
-        //
-        // A BrokenPayload finding means THIS subos claims the entry; it does
-        // not mean this subos is alone. Dropping a version another subos has
-        // active turns a broken payload over there into an active pointer at
-        // nothing over there -- trading a repairable state for a worse one, in
-        // a subos the user is not even in. Caught by the multi-subos e2e,
-        // which pruned a version `other` was still using and then exited 0.
-        const auto owner = xvm::subos_ownership(
-            st.ws, st.wsInstalled, st.otherSubos, f.target, f.version);
-        if (!owner.otherSubos.empty()) {
-            std::string list;
-            for (const auto& other : owner.otherSubos) {
-                if (!list.empty()) list += ", ";
-                list += other;
-            }
-            out.notes.emplace_back(glyph::mark(glyph::failed, "kept"), std::format(
-                "{} could not be restored, but subos {} still uses it — "
-                "repair or remove it there",
-                xvm::display_coordinate(f.target, f.version), list));
-            out.failedEntries.emplace_back(f.target, f.version);
-            continue;
-        }
-        victims.emplace_back(f.target, f.version);
-    }
-    if (victims.empty()) return;
-
-    auto lock = xvm::acquire_state_lock(Config::paths().homeDir);
-    if (!lock) {
-        out.notes.emplace_back(glyph::mark(glyph::failed, "prune"), std::format(
-            "cannot drop dead registrations: {}", lock.error()));
-        for (const auto& victim : victims) out.failedEntries.push_back(victim);
-        return;
-    }
-    Config::reload_state();
-    auto& db = Config::versions_mut();
-    auto& ws = Config::workspace_mut();
-    auto& installed = Config::workspace_installed_mut();
-
-    std::size_t dropped = 0;
-    for (const auto& [target, version] : victims) {
-        const auto infoIt = db.find(target);
-        if (infoIt == db.end()) continue;
-        if (infoIt->second.versions.erase(version) == 0) continue;
-        ++dropped;
-        out.notes.emplace_back(glyph::mark(glyph::bullet, "dropped"), std::format(
-            "{} — its payload is gone and nothing can restore it",
-            xvm::display_coordinate(target, version)));
-
-        if (const auto wit = ws.find(target);
-            wit != ws.end() && wit->second == version) {
-            ws.erase(wit);
-        }
-        if (const auto iit = installed.find(target); iit != installed.end()) {
-            std::erase(iit->second, version);
-            if (iit->second.empty()) installed.erase(iit);
-        }
-        // Edges into the removed version would outlive it and make every
-        // release it touched unresolvable.
-        for (auto& [_, info] : db) {
-            for (auto edgeIt = info.bindings.begin();
-                 edgeIt != info.bindings.end();) {
-                if (edgeIt->first == target) {
-                    std::erase_if(edgeIt->second, [&](const auto& edge) {
-                        return edge.second == version;
-                    });
-                }
-                if (edgeIt->second.empty()) {
-                    edgeIt = info.bindings.erase(edgeIt);
-                } else {
-                    ++edgeIt;
-                }
-            }
-        }
-        if (infoIt->second.versions.empty()) {
-            db.erase(infoIt);
-        }
-    }
-    if (dropped > 0) {
-        Config::save_versions();
-        Config::save_workspace();
-        out.pruned += static_cast<int>(dropped);
-    }
-}
-
 // ── render ───────────────────────────────────────────────────────────
 
 struct Counts {
@@ -2843,487 +359,6 @@ struct Counts {
     }
 };
 
-Counts count_(const Scan& scan) {
-    Counts c;
-    std::set<std::string> aliasTargets;
-    std::set<std::string> bakedTargets;
-    for (const auto& f : scan.findings) {
-        switch (f.kind) {
-            case FindingKind::MissingShim:     ++c.missing; break;
-            case FindingKind::OrphanShim:
-                // An anchor shim is Notice-level: the file is useless but
-                // its presence is not the user's doing, and it must not set
-                // the exit code. --fix still removes it.
-                if (f.level != FindingLevel::Notice) ++c.orphans;
-                break;
-            case FindingKind::LegacyAliasShim: ++c.orphans; break;
-            case FindingKind::BrokenPayload:   ++c.broken;  break;
-            case FindingKind::ForeignPayload:  ++c.foreignPayloads; break;
-            case FindingKind::ShimAnchor: ++c.warnings; break;
-            // Counted per TARGET, because that is how they are printed. A
-            // count that does not match the list is the shape the old summary
-            // had -- "broken payloads 1" with nothing in the list to explain
-            // it -- and it sends people looking for a line that is not there.
-            // An alias that a host command satisfies is a Notice and counts
-            // as nothing; one that resolves nowhere is an Error and counts as
-            // an issue. They used to be the same warning, which is how a real
-            // break stayed invisible inside thirty-four false ones.
-            case FindingKind::AliasUnresolved:
-                if (f.level != FindingLevel::Error) break;
-                if (aliasTargets.insert(f.target).second) ++c.aliasBroken;
-                break;
-            case FindingKind::ReleaseAnchor:   break;
-            case FindingKind::InactiveInstalled: ++c.inactive; break;
-            // Per TARGET, matching how they are printed (see render_).
-            case FindingKind::SubosPathBaked:
-                if (bakedTargets.insert(f.target).second) ++c.warnings;
-                break;
-            case FindingKind::SysrootDangling: ++c.warnings; break;
-            case FindingKind::BindingState:
-                if (f.level != FindingLevel::Notice) ++c.binding;
-                break;
-            case FindingKind::OtherSubos:      ++c.otherSubos; break;
-            case FindingKind::LoaderLibcSplit:
-                // Counted as broken, so it reaches the exit code. A finding
-                // that prints and then exits 0 is how a check gets ignored by
-                // every script that wraps it.
-                ++c.broken;
-                break;
-            case FindingKind::NssResolution:
-                // Only the failing one counts. The passing case is a Notice
-                // that exists to say the cell RAN -- counting it would make a
-                // healthy home report a problem, and a cell that cries wolf
-                // gets read as noise by the second week.
-                if (f.level == FindingLevel::Error) ++c.broken;
-                break;
-            case FindingKind::SubosDoubleBinding:
-                // Counted for the same reason, and for a second one: `healed`
-                // is computed as before-minus-after over this count, so an
-                // uncounted finding that --fix repairs reports "healed 0" --
-                // repair and report disagreeing about whether anything
-                // happened.
-                ++c.broken;
-                break;
-            // The three below were Error-level and absent from this switch, so
-            // doctor printed `✗ subos env orphan …` and then exited 0. Two
-            // consequences, and the second is the quieter one:
-            //
-            //   1. every script wrapping `xlings self doctor` saw success;
-            //   2. `healed` is before-minus-after over this count, so --fix
-            //      repairing an orphan reported "healed 0" -- the repairer
-            //      acted and the reporter said nothing. That is the
-            //      reporter/repairer split this repo has produced three times,
-            //      arrived at from the counting side rather than the
-            //      predicate side.
-            case FindingKind::SubosManifest:
-            case FindingKind::SubosEnvOrphan:
-            case FindingKind::SubosEnvUnresolved:
-                ++c.broken;
-                break;
-            case FindingKind::SubosEnvConflict:
-                ++c.warnings;
-                break;
-            case FindingKind::SubosRuntimeMissing:
-                if (f.level == FindingLevel::Error) ++c.broken;
-                else ++c.warnings;
-                break;
-            case FindingKind::IncompletePayload:
-                // Counted as broken for both reasons the comment above gives:
-                // it must reach the exit code, and `healed` is computed as
-                // before-minus-after over this count, so an uncounted finding
-                // that --fix repairs reports "healed 0".
-                ++c.broken;
-                break;
-            case FindingKind::UnverifiedPayload:
-                // Counts as nothing, on purpose. It is a Notice about state we
-                // could not observe, not a defect we found -- and a home with
-                // 29 of them exiting non-zero would train everyone to ignore
-                // the command. The line still prints, with the command that
-                // settles it.
-                break;
-            case FindingKind::EntryBinaryDrift:
-                // Counts as nothing either: both shapes it reports are states
-                // a user may have chosen on purpose. It must be visible, not
-                // fatal.
-                break;
-        }
-    }
-    return c;
-}
-
-void render_(const Scan& scan, const RepairReport& repair, bool fix,
-             bool dryRun, bool verbose, EventStream& stream) {
-    nlohmann::json fields = nlohmann::json::array();
-    const auto add = [&](std::string_view label, std::string value,
-                         bool hl = false) {
-        fields.push_back({{"label", std::string(label)},
-                          {"value", std::move(value)},
-                          {"highlight", hl}});
-    };
-
-    const auto counts = count_(scan);
-
-    // Broken payloads, one line per payload rather than one per program.
-    //
-    // A missing payload directory takes out every program registered against
-    // it. On the measured home that is nine lines for llvm and three each for
-    // two virtualbox entries -- twenty lines describing four problems, with
-    // twenty remedies of which four were distinct.
-    std::map<std::string, std::vector<const Finding*>> payloadGroups;
-    std::vector<std::string> groupOrder;
-    for (const auto& f : scan.findings) {
-        if (f.kind != FindingKind::BrokenPayload
-            && f.kind != FindingKind::ForeignPayload) continue;
-        auto [it, inserted] = payloadGroups.try_emplace(f.groupKey);
-        if (inserted) groupOrder.push_back(f.groupKey);
-        it->second.push_back(&f);
-    }
-    for (const auto& key : groupOrder) {
-        const auto& group = payloadGroups.at(key);
-        const auto* head = group.front();
-        const bool foreign = head->kind == FindingKind::ForeignPayload;
-        std::string label = foreign
-            ? glyph::mark(glyph::failed,
-                          std::format("broken payload [subos: {}]",
-                          [&] {
-                              std::string list;
-                              for (const auto& s : head->subos) {
-                                  if (!list.empty()) list += ", ";
-                                  list += s;
-                              }
-                              return list;
-                          }()))
-            : (std::ranges::any_of(group, [](const Finding* f) {
-                   return f->active;
-               }) ? glyph::mark(glyph::failed, "broken payload [active]")
-                  : glyph::mark(glyph::failed, "broken payload"));
-
-        std::string detail = head->detail;
-        if (group.size() > 1) {
-            std::string names;
-            for (const auto* f : group) {
-                if (!names.empty()) names += ", ";
-                names += f->target;
-            }
-            detail += std::format("\n    {} programs from this payload: {}",
-                                  group.size(), names);
-        }
-        add(label, std::move(detail));
-        if (!head->remedy.empty()) {
-            add("  " + glyph::mark(glyph::remedy, "run"), head->remedy);
-        } else {
-            // No command would help. Saying that is the useful output; a
-            // plausible-looking `xlings install <target>` is not.
-            add("  " + glyph::mark(glyph::note, "no remedy"), fix
-                ? std::string("no package provides this entry — the "
-                              "registration was dropped")
-                : std::string("no package in any index provides this entry; "
-                              "`--fix` will drop the registration"));
-        }
-    }
-
-    // Everything else, in a stable order.
-    std::set<std::string> aliasTargetsShown;
-    std::map<std::string, int> aliasVersionCount;
-    std::set<std::string> bakedTargetsShown;
-    std::map<std::string, int> bakedVersionCount;
-    for (const auto& f : scan.findings) {
-        // Errors only: the "+N other version(s)" suffix is printed on an
-        // error line, so counting notices into it would inflate a number the
-        // user cannot see the rest of.
-        if (f.kind == FindingKind::AliasUnresolved
-            && f.level == FindingLevel::Error) ++aliasVersionCount[f.target];
-        else if (f.kind == FindingKind::SubosPathBaked) ++bakedVersionCount[f.target];
-    }
-    for (const auto& f : scan.findings) {
-        switch (f.kind) {
-            case FindingKind::MissingShim:
-                add(glyph::mark(glyph::failed, "missing shim"), f.detail); break;
-            case FindingKind::OrphanShim:
-                if (f.level == FindingLevel::Notice) {
-                    if (verbose) add(glyph::mark(glyph::note, "anchor shim"), f.detail);
-                } else {
-                    add(glyph::mark(glyph::failed, "orphan shim"), f.detail);
-                }
-                break;
-            case FindingKind::LegacyAliasShim:
-                add(glyph::mark(glyph::failed, "legacy alias shim"), f.detail); break;
-            case FindingKind::InactiveInstalled:
-                add(glyph::mark(glyph::failed, "no active version"), f.detail);
-                // Printed before the remedy, because it changes what the
-                // remedy means: not "run this to fix it" but "run this to
-                // choose this package over that one".
-                if (!f.conflict.empty()) {
-                    add("  " + glyph::mark(glyph::warn, "conflict"),
-                        std::format("{} — `--fix` will not choose between "
-                                    "them", f.conflict));
-                }
-                add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
-                break;
-            case FindingKind::ShimAnchor:
-                add(glyph::mark(glyph::warn, "shim anchor"), f.detail); break;
-            case FindingKind::AliasUnresolved:
-                // One line per TARGET, not per version. The alias is a
-                // property of the recipe, so every version of a package
-                // registers the same one and reports the same way -- five
-                // identical `claude` lines on the measured home. Collapsing
-                // the repeats is the fix; hiding the category is not, because
-                // a genuinely missing alias binary is the only signal there
-                // is.
-                //
-                // The Notice level is "a host command answers this", which is
-                // a portability fact rather than a defect. It is summarised
-                // like the other notices and printed only under `--all`, so
-                // the Error level -- an alias with nothing to exec anywhere --
-                // is the only thing this category shows by default. That is
-                // the whole point of splitting it: the error used to be one
-                // line among thirty-four identical-looking warnings.
-                if (f.level == FindingLevel::Notice) {
-                    if (verbose) {
-                        add(glyph::mark(glyph::note, "host alias"), f.detail);
-                    }
-                    break;
-                }
-                if (verbose || aliasTargetsShown.insert(f.target).second) {
-                    add(glyph::mark(glyph::failed, "alias unresolved"), verbose ? f.detail
-                        : std::format("{}{}", f.detail,
-                            aliasVersionCount.at(f.target) > 1
-                                ? std::format("  (+{} other version(s))",
-                                              aliasVersionCount.at(f.target) - 1)
-                                : std::string{}));
-                }
-                break;
-            case FindingKind::SysrootDangling:
-                add(glyph::mark(glyph::warn, "dangling sysroot link"), f.detail);
-                // A link in ANOTHER subos is reported here and repaired
-                // there, so the generic "run `xlings self doctor --fix`"
-                // footer is wrong for it -- that command, from here, will
-                // leave it exactly where it is. Name the one that works.
-                if (!f.subos.empty() && !f.remedy.empty()) {
-                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
-                }
-                break;
-            case FindingKind::SubosPathBaked:
-                // One line per TARGET. A single gcc install bakes the path
-                // into fourteen registrations (gcc, g++, cc, c++ and the
-                // triple-prefixed spellings, times two versions), and
-                // fourteen identical lines bury everything else -- the same
-                // reason `alias unresolved` collapses.
-                if (verbose || bakedTargetsShown.insert(f.target).second) {
-                    add(glyph::mark(glyph::warn, "subos path"), verbose
-                        ? f.detail
-                        : std::format("{}{}", f.detail,
-                            bakedVersionCount.at(f.target) > 1
-                                ? std::format("  (+{} other registration(s))",
-                                              bakedVersionCount.at(f.target) - 1)
-                                : std::string{}));
-                }
-                break;
-            case FindingKind::BindingState:
-                if (f.level == FindingLevel::Notice) {
-                    if (verbose) add(glyph::mark(glyph::note, "binding state"), f.detail);
-                } else {
-                    add(glyph::mark(glyph::failed, "binding state"), f.detail);
-                }
-                break;
-            case FindingKind::OtherSubos:
-                if (verbose || f.level != FindingLevel::Notice) {
-                    add(f.level == FindingLevel::Notice ? glyph::mark(glyph::note, "other subos")
-                                                        : glyph::mark(glyph::warn, "other subos"),
-                        f.detail);
-                }
-                break;
-            case FindingKind::ReleaseAnchor:
-                if (verbose) add(glyph::mark(glyph::note, "release anchor"), f.detail);
-                break;
-            case FindingKind::SubosManifest:
-                add(glyph::mark(glyph::failed, "subos manifest"), f.detail);
-                // The remedy for an unreadable file is not `--fix`, so it has
-                // to be printed rather than left to the generic footer.
-                if (!f.remedy.empty() && f.remedy != "xlings self doctor --fix")
-                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
-                break;
-            case FindingKind::SubosEnvOrphan:
-                add(glyph::mark(glyph::failed, "subos env orphan"), f.detail);
-                break;
-            case FindingKind::SubosDoubleBinding:
-                // Not collapsed into a count: which versions are bound is the
-                // finding, and there is at most a handful.
-                add(glyph::mark(glyph::failed, "subos double binding"), f.detail);
-                if (!f.remedy.empty())
-                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
-                break;
-            case FindingKind::SubosEnvUnresolved:
-                add(glyph::mark(glyph::failed, "subos env unresolved"), f.detail);
-                if (!f.remedy.empty())
-                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
-                break;
-            case FindingKind::SubosEnvConflict:
-                // Never collapsed into a count, unlike the notice categories:
-                // there is one per contested variable, the number is small,
-                // and which packages disagree is the whole content.
-                add(glyph::mark(glyph::warn, "subos env conflict"), f.detail);
-                break;
-            case FindingKind::SubosRuntimeMissing:
-                add(f.level == FindingLevel::Error
-                        ? glyph::mark(glyph::failed, "subos runtime")
-                        : glyph::mark(glyph::warn, "subos runtime"),
-                    f.detail);
-                if (!f.remedy.empty())
-                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
-                break;
-            case FindingKind::LoaderLibcSplit:
-                // Not collapsed into a count, and never abbreviated: the two
-                // paths ARE the finding. A reader who gets only "1 problem"
-                // has to reproduce the whole investigation this check exists
-                // to remove.
-                add(glyph::mark(glyph::failed, "loader/libc split"), f.detail);
-                if (!f.remedy.empty())
-                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
-                break;
-            case FindingKind::NssResolution:
-                add(f.level == FindingLevel::Error
-                        ? glyph::mark(glyph::failed, "nss resolution")
-                        : glyph::mark(glyph::done, "nss resolution"),
-                    f.detail);
-                break;
-            case FindingKind::IncompletePayload:
-                add(glyph::mark(glyph::failed, "incomplete install"), f.detail);
-                if (!f.remedy.empty())
-                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
-                break;
-            case FindingKind::UnverifiedPayload:
-                // Summarised into one counted line when not verbose -- see
-                // below. Twenty-nine of these would bury everything else,
-                // which is the failure mode the notice-collapsing block
-                // downstream was built for.
-                if (verbose) {
-                    add(glyph::mark(glyph::note, "unverified install"),
-                        f.detail);
-                    if (!f.remedy.empty())
-                        add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
-                }
-                break;
-            case FindingKind::EntryBinaryDrift:
-                // Printed in full, always -- NOT collapsed into the notice
-                // summary. There are at most two of these, and each one
-                // describes the single file every other tool in the home is
-                // dispatched through; a collapsed count would say "1 notice"
-                // about the fact that explains everything else on the page.
-                add(glyph::mark(glyph::note, "entry binary"), f.detail);
-                if (!f.remedy.empty())
-                    add("  " + glyph::mark(glyph::remedy, "run"), f.remedy);
-                break;
-            default: break;
-        }
-    }
-
-    // Notices that are not defects get one counted line unless asked for.
-    // Thirty `release anchor` lines saying "nothing is wrong here" is how the
-    // four lines that matter got lost.
-    if (!verbose) {
-        int anchors = 0, anchorShims = 0, bindingNotices = 0, subosNotices = 0;
-        int unverified = 0;
-        // Per TARGET, like the warning line it replaced: one package's alias
-        // is one fact however many versions of it are registered.
-        std::set<std::string> hostAliasTargets;
-        for (const auto& f : scan.findings) {
-            if (f.kind == FindingKind::UnverifiedPayload) ++unverified;
-            else if (f.kind == FindingKind::ReleaseAnchor) ++anchors;
-            else if (f.kind == FindingKind::OrphanShim
-                     && f.level == FindingLevel::Notice) ++anchorShims;
-            else if (f.kind == FindingKind::BindingState
-                     && f.level == FindingLevel::Notice) ++bindingNotices;
-            else if (f.kind == FindingKind::OtherSubos
-                     && f.level == FindingLevel::Notice) ++subosNotices;
-            else if (f.kind == FindingKind::AliasUnresolved
-                     && f.level == FindingLevel::Notice) {
-                hostAliasTargets.insert(f.target);
-            }
-        }
-        std::string summary;
-        const auto part = [&](int n, std::string_view what) {
-            if (n == 0) return;
-            if (!summary.empty()) {
-                summary += std::format(" {} ", std::string(glyph::bullet));
-            }
-            summary += std::format("{} {}", n, what);
-        };
-        part(anchors, "release anchor");
-        part(static_cast<int>(hostAliasTargets.size()), "host alias");
-        part(anchorShims, "anchor shim");
-        part(bindingNotices, "binding notice");
-        part(subosNotices, "other-subos notice");
-        part(unverified, "unverified install");
-        if (!summary.empty()) {
-            add(glyph::mark(glyph::note, "nothing to do"), summary + "  —  `--all` to list them");
-        }
-    }
-
-    for (const auto& [label, text] : repair.notes) add(label, text);
-    for (const auto& planned : repair.planned) add(glyph::mark(glyph::remedy, "would run"), planned);
-    if (dryRun) {
-        add("dry run", std::format(
-            "{} action(s) planned; nothing was changed",
-            repair.planned.size()), true);
-    }
-
-    if (counts.issues() == 0 && counts.warnings == 0
-        && counts.foreignPayloads == 0 && counts.otherSubos == 0) {
-        add("status", "OK — workspace, shims, and payloads are all consistent",
-            true);
-    } else {
-        if (counts.missing > 0)
-            add("missing shims", std::to_string(counts.missing));
-        if (counts.orphans > 0)
-            add("orphan shims", std::to_string(counts.orphans));
-        if (counts.broken > 0)
-            add("broken payloads", std::to_string(counts.broken));
-        if (counts.binding > 0)
-            add("binding state", std::to_string(counts.binding));
-        if (counts.inactive > 0)
-            add("no active version", std::to_string(counts.inactive));
-        if (counts.aliasBroken > 0)
-            add("unresolvable aliases", std::to_string(counts.aliasBroken));
-        if (counts.warnings > 0)
-            add("warnings", std::to_string(counts.warnings));
-        // Reported apart from the counts above because they are apart from the
-        // exit code: they belong to a subos this run is not in.
-        if (counts.foreignPayloads > 0)
-            add("owned by another subos", std::format(
-                "{} — repair them there", counts.foreignPayloads));
-        if (counts.otherSubos > 0)
-            add("other subos findings", std::to_string(counts.otherSubos));
-    }
-
-    if (fix) {
-        if (repair.healed > 0)
-            add("healed", std::to_string(repair.healed), true);
-        if (repair.pruned > 0)
-            add("pruned", std::to_string(repair.pruned), true);
-        if (counts.issues() > 0)
-            add("hint", "some findings remain — see the reasons above", true);
-    } else if (counts.issues() > 0 || counts.otherSubos > 0) {
-        add("hint", "run `xlings self doctor --fix` to repair", true);
-    }
-
-    // The nudge, for a home an older client set up. Last field of the same
-    // panel rather than a panel of its own: a second panel renders its own
-    // (empty) header, which reads as a broken frame rather than a footnote.
-    // Gated on the recorded version differing from the running one, which is
-    // what makes a successful `--fix` turn it off rather than merely quieten
-    // it.
-    if (auto hint = migration_hint(Config::recorded_client_version(),
-                                   Info::VERSION)) {
-        add(glyph::mark(glyph::note, "migration"), *hint);
-    }
-
-    nlohmann::json payload;
-    payload["title"]  = "xlings self doctor";
-    payload["fields"] = std::move(fields);
-    stream.emit(DataEvent{"info_panel", payload.dump()});
-}
-
 // ── the command ──────────────────────────────────────────────────────
 
 export int cmd_doctor(EventStream& stream, bool fix,
@@ -3331,365 +366,6 @@ export int cmd_doctor(EventStream& stream, bool fix,
                       bool dryRun = false,
                       bool verbose = false,
                       bool deep = false,
-                      std::optional<std::string> scope = std::nullopt) {
-    // `--fix` implies `--deep`. Deliberate and load-bearing: the repair must
-    // be able to act on findings only the payload audit produces, and
-    // self_doctor_depth_test asserts it ("--fix retains the historical deep
-    // detection surface").
-    //
-    // It is also expensive. Measured on a 124-package / 71 GB home: plain
-    // `self doctor` 0.75s, `--fix --dry-run` 148-191s WITHOUT repairing
-    // anything, because the audit walks every package at every version. That
-    // cost is what makes `--fix` look dead, and the progress below is the
-    // answer to THAT -- the user's complaint was silence, not duration.
-    //
-    // Decoupling the two would trade the wait for a quieter problem: a `--fix`
-    // that no longer detects what only a deep scan finds. Getting the speed
-    // without that trade means making the audit itself cheap -- payload
-    // directories are immutable, so their scan results are cacheable by path
-    // and mtime -- which is a separate change with its own risk surface.
-    // See .agents/docs/2026-08-10-doctor-fix-hang-and-537.md (D2 vs D3).
-    const bool deepAudit = deep || fix;
-    if (scope && !deepAudit) {
-        stream.emit(ErrorEvent{
-            .code = ErrorCode::InvalidInput,
-            .message = "`--scope` requires `--deep` (or `--fix`, which implies it)",
-            .recoverable = false,
-        });
-        return 2;
-    }
-
-    // Announce the boundary before catalog evaluation or payload walking. A
-    // deep audit can legitimately take time on a large store; silence before
-    // the first result is indistinguishable from the hang this mode replaces.
-    if (deepAudit) {
-        // `--scope` narrows the payload/runtime AUDIT. Every other check, and
-        // every repair `--fix` performs, still covers the whole home -- so the
-        // announce line says which, rather than letting the reader infer that
-        // the run is confined to one package.
-        stream.emit(LogEvent{
-            LogLevel::info,
-            scope
-                ? std::format("deep audit scope: {} "
-                              "(payload/runtime audit only; other checks and "
-                              "repairs still cover this home)", *scope)
-                : std::string("deep audit scope: all installed payloads"),
-        });
-        std::cout.flush();
-    }
-
-    std::optional<xim::PackageCatalog> localCatalog;
-    AuditSelection audit{.deep = deepAudit};
-    // Both kinds, deliberately: the plain CLI renders LogEvent and ignores
-    // ProgressEvent, while the TUI and the agent protocol consume
-    // ProgressEvent and would show nothing for a LogEvent. Emitting one leaves
-    // the other with the silence this exists to remove.
-    audit.onProgress = [&stream](std::size_t done, std::size_t total,
-                                 std::string_view target, std::string_view version) {
-        stream.emit(ProgressEvent{
-            .phase = "auditing",
-            .percent = total ? static_cast<float>(done) / static_cast<float>(total) : 0.0f,
-            .message = std::format("auditing payloads {}/{}", done, total),
-        });
-        stream.emit(LogEvent{
-            LogLevel::info,
-            std::format("auditing payloads {}/{} — {}@{}", done, total, target, version),
-        });
-        std::cout.flush();
-    };
-    // The catalog is needed by the REPAIR, not only by the audit — it is how a
-    // broken payload's owning package is found so `xlings install` can be run
-    // against it. Gating it on `deepAudit` alone was the bug in the first cut
-    // of this change: decoupling `--fix` from `--deep` silently took the
-    // catalog away too, and `--fix` stopped repairing a payload whose
-    // directory was simply gone. Caught by self_doctor_test S8b, which asserts
-    // the repair by looking at the filesystem rather than at what doctor
-    // claimed — which is why it could catch it at all.
-    if (deepAudit || fix) {
-        localCatalog.emplace();
-        const auto rebuilt = localCatalog->rebuild();
-        if (!rebuilt) {
-            if (scope) {
-                stream.emit(ErrorEvent{
-                    .code = ErrorCode::InvalidInput,
-                    .message = std::format(
-                        "cannot resolve deep audit scope '{}': {}",
-                        *scope, rebuilt.error()),
-                    .recoverable = false,
-                });
-                return 2;
-            }
-            localCatalog.reset();
-        } else if (scope) {
-            auto resolved = localCatalog->resolve_target(
-                *scope, std::string(platform::build_os()));
-            if (!resolved) {
-                stream.emit(ErrorEvent{
-                    .code = ErrorCode::InvalidInput,
-                    .message = std::format(
-                        "deep audit scope '{}' is missing or ambiguous: {}",
-                        *scope, resolved.error()),
-                    .recoverable = false,
-                });
-                return 2;
-            }
-            const auto payloadDir = audit_payload_dir_(*resolved);
-            std::error_code ec;
-            if (!fs::is_directory(payloadDir, ec)
-                || !xim::payload_has_content(payloadDir)) {
-                stream.emit(ErrorEvent{
-                    .code = ErrorCode::InvalidInput,
-                    .message = std::format(
-                        "deep audit scope '{}' has no local payload at {}",
-                        *scope, Config::display_path(payloadDir)),
-                    .recoverable = false,
-                });
-                return 2;
-            }
-            audit.scope = std::move(*resolved);
-        }
-    }
-
-    // One in-process probe cache for the whole command. The same candidate is
-    // asked about once per finding it owns and again after repair passes.
-    std::map<std::string, bool> probed;
-    std::string client = "xlings";
-    {
-        const auto self = platform::get_executable_path().string();
-        if (!self.empty() && is_shell_safe_token(self)) client = self;
-    }
-    const CoordinateProbe probe =
-        [&](const xvm::InstallCoordinate& coord) {
-            const auto key = coord.canonical();
-            if (const auto it = probed.find(key); it != probed.end()) {
-                return it->second;
-            }
-            const bool ok = localCatalog
-                && xim::resolve_local_coordinate(*localCatalog, key).has_value();
-            probed.emplace(key, ok);
-            return ok;
-        };
-
-    auto state = load_state_();
-
-    // --reset-metadata runs before detection: an entry whose group is
-    // unreadable makes its release unresolvable, which detection would
-    // otherwise report as a different problem. It is the one repair that loses
-    // information, which is why it has its own flag.
-    RepairReport repair;
-    if (resetMetadata) {
-        if (auto reset = xvm::plan_metadata_reset(state.db); !reset.empty()) {
-            auto lock = xvm::acquire_state_lock(Config::paths().homeDir);
-            if (!lock) {
-                repair.notes.emplace_back(glyph::mark(glyph::failed, "binding state"), std::format(
-                    "cannot reset binding metadata: {}", lock.error()));
-            } else {
-                Config::reload_state();
-                auto& mutableDb = Config::versions_mut();
-                const auto replanned = xvm::plan_metadata_reset(mutableDb);
-                if (xvm::apply_metadata_reset(mutableDb, replanned) > 0) {
-                    Config::save_versions();
-                    for (const auto& entry : replanned.entries) {
-                        std::string codes;
-                        for (const auto& code : entry.codes) {
-                            if (!codes.empty()) codes += ", ";
-                            codes += code;
-                        }
-                        // Name what was discarded. This is the one repair that
-                        // loses information, so a bare count would be the
-                        // wrong report.
-                        repair.notes.emplace_back(glyph::mark(glyph::bullet, "metadata reset"),
-                            std::format(
-                                "{} dropped its release metadata ({}) and is "
-                                "now switchable on its own — reinstall it to "
-                                "restore the release",
-                                xvm::display_coordinate(entry.target,
-                                                        entry.version),
-                                codes));
-                    }
-                }
-            }
-        }
-        state = load_state_();
-    }
-
-    auto scan = detect_(state, probe, audit);
-
-    if (!fix) {
-        render_(scan, repair, fix, dryRun, verbose, stream);
-            return count_(scan).issues() == 0 ? 0 : 1;
-    }
-
-    const int before = count_(scan).issues();
-
-    const CommandRunner run = [](const std::string& cmd) {
-        return platform::exec(cmd);
-    };
-
-    if (dryRun) {
-        repair_payloads_(state, scan, probe, /*dryRun=*/true, repair);
-        repair_incomplete_(scan, run, /*dryRun=*/true, repair);
-        repair_inactive_(scan, client, run, /*dryRun=*/true, repair);
-        render_(scan, repair, fix, dryRun, verbose, stream);
-            return count_(scan).issues() == 0 ? 0 : 1;
-    }
-
-    // Re-read and re-detect between phases.
-    //
-    // Not a precaution: the payload repairs run in SUBPROCESSES that write the
-    // state file, while this process still holds the copy it read at startup.
-    // Without the reload, a cure that is purely a re-registration -- which is
-    // what the ladder mostly does -- reads as a failure, and only repairs that
-    // happened to restore a directory on disk appear to work.
-    const auto refresh = [&] {
-        Config::reload_state();
-        state = load_state_();
-        scan  = detect_(state, probe, audit);
-    };
-
-    // Phase 1: the cheap metadata repairs, BEFORE the ladder.
-    //
-    // A dangling edge is not only a finding of its own -- it makes its
-    // release unresolvable, and registration validates the whole release. So
-    // an unpruned edge makes `xlings install` refuse, which is the ladder's
-    // R2 failing for a reason the ladder cannot see and R3 then reacting to by
-    // removing a working package. Clearing them first is what lets the install
-    // that follows actually succeed.
-    repair_state_(repair);
-    repair_other_subos_(state, repair);
-    repair_local_(state, scan, repair);
-    refresh();
-
-    // Phase 2: the payload ladder.
-    const auto announce = [&stream](std::string_view msg) {
-        stream.emit(LogEvent{LogLevel::info, std::string(msg)});
-        std::cout.flush();
-    };
-    repair_payloads_(state, scan, probe, /*dryRun=*/false, repair, announce);
-    refresh();
-
-    // Phase 2b: payloads whose own stamp records a failed install.
-    //
-    // After the ladder and after a reload, so a payload the ladder already
-    // reinstalled is no longer reported here -- the refresh above re-reads the
-    // stamp, and a successful install overwrites the failure marker.
-    repair_incomplete_(scan, run, /*dryRun=*/false, repair, announce);
-    refresh();
-
-
-    // Phase 3: the cheap repairs again, on what the ladder left behind.
-    //
-    // Re-registering a package creates state: shims for programs that are
-    // registered but not active, and a release whose members are not all
-    // active because the entry point already was. Both are things phase 1
-    // repairs -- they just did not exist yet when phase 1 ran. Measured: one
-    // llvm re-registration produced 29 orphan shims and 29 incoherent-release
-    // findings that a single-pass repair reported as unfixed.
-    repair_state_(repair);
-    repair_local_(state, scan, repair);
-    refresh();
-
-    // Phase 3.5: activate what is installed and inactive.
-    //
-    // LAST among the repairs that write the workspace, and that placement is
-    // the fix for a real bug rather than a preference. It used to run before
-    // the final `repair_state_`, so it activated a release and the
-    // deactivation repair immediately afterwards took down whatever that
-    // activation had knocked out of step -- the two traded the workspace back
-    // and forth and `--fix` ended with more issues than it began with
-    // (2026.8.1.1, measured: `gcc` and `ld` left with no active version).
-    //
-    // Running last means every teardown has already settled, so this acts on a
-    // workspace nothing else is about to rewrite. The preflight in detection
-    // (activation_conflict_) is what stops it from creating a NEW disagreement
-    // for the next run to trip over; the ordering here is what stops it from
-    // being undone within this one.
-    //
-    // Still after the payload ladder for the original reason: a package whose
-    // payload was missing is both broken AND inactive, and `use` on a payload
-    // that is not there fails for a reason the user cannot act on.
-    repair_inactive_(scan, client, run, /*dryRun=*/false, repair);
-    refresh();
-
-    // Phase 4: whatever is STILL a broken payload after the ladder had its
-    // turn is dead. Prune it, then re-detect once more so the report shows the
-    // result rather than the intent.
-    prune_dead_registrations_(state, scan, repair);
-    if (repair.pruned > 0) {
-        refresh();
-        // A prune can orphan a shim of its own -- the entry is gone, the file
-        // is not.
-        repair_local_(state, scan, repair);
-        refresh();
-    }
-
-    const auto after = count_(scan);
-    repair.healed = std::max(0, before - after.issues() - repair.pruned);
-
-    // Did `--fix` actually leave the home better than it found it?
-    //
-    // Nothing asked this until 2026.8.1.2, and the release before it shipped a
-    // repair that undid another one: activating a release stranded members of
-    // a second release, the deactivation repair then took those members down,
-    // and the resulting "installed but inactive" entries were reported as new
-    // findings. `--fix` ended with MORE issues than it started with, having
-    // printed a hundred lines of `deactivated`, and the two repairs would go on
-    // trading the workspace back and forth on every subsequent run.
-    //
-    // This does not fix anything. It is the assertion that makes that class of
-    // bug announce itself on its FIRST run instead of hiding inside a long
-    // successful-looking report. Repairs that can conflict are prevented from
-    // conflicting elsewhere (see the preflight in repair_inactive_); this is
-    // the backstop for the next one nobody predicted.
-    if (after.issues() > before) {
-        repair.regressed = true;
-        repair.notes.emplace_back(
-            glyph::mark(glyph::failed, "not converging"),
-            std::format(
-                "--fix started with {} issue(s) and ended with {} — a repair "
-                "undid another. This is a bug in doctor, not in the home; "
-                "please report it with the output above.",
-                before, after.issues()));
-    }
-
-    // A ladder failure only still counts if the entry it covered is still a
-    // finding somewhere. An entry that was pruned, or that a later phase
-    // cured, is not an outstanding failure -- but one that merely moved to
-    // another subos's ledger IS, which is why this asks the findings rather
-    // than the counters.
-    std::set<std::pair<std::string, std::string>> stillFound;
-    for (const auto& f : scan.findings) {
-        if (f.kind == FindingKind::BrokenPayload
-            || f.kind == FindingKind::ForeignPayload) {
-            stillFound.emplace(f.target, f.version);
-        }
-    }
-    int outstanding = 0;
-    for (const auto& entry : repair.failedEntries) {
-        if (stillFound.contains(entry)) ++outstanding;
-    }
-
-    render_(scan, repair, fix, dryRun, verbose, stream);
-
-    // Stamp the home with the client that just checked it.
-    //
-    // `.xlings.json:version` records which xlings set the home up. Only `self
-    // install` ever wrote it, so `self update` -- which installs xlings@latest
-    // as a package -- left it reading the old version forever. Stamped here it
-    // becomes the migration marker: the hint appears while the home is behind
-    // and stops once a --fix has actually migrated the packages.
-    //
-    // Gated on the repairs this pass OWNS, not on a spotless home. doctor also
-    // reports things --fix is not responsible for -- unresolvable aliases,
-    // shim anchoring, another subos's broken payload -- and requiring zero of
-    // those would mean the marker never lands and the hint nags forever about
-    // a migration that already happened.
-    if (outstanding == 0 && after.foreignPayloads == 0) {
-        Config::record_client_version(std::string(Info::VERSION));
-    }
-
-    return (after.issues() == 0 && outstanding == 0 && !repair.regressed)
-        ? 0 : 1;
-}
+                      std::optional<std::string> scope = std::nullopt);
 
 } // namespace xlings::xself
diff --git a/src/core/xself/init.cpp b/src/core/xself/init.cpp
new file mode 100644
index 00000000..576dcb77
--- /dev/null
+++ b/src/core/xself/init.cpp
@@ -0,0 +1,340 @@
+module xlings.core.xself.init;
+
+import std;
+import xlings.core.config;
+import xlings.libs.json;
+import xlings.core.log;
+import xlings.platform;
+import xlings.core.xself.compat;
+import xlings.core.xself.profile_resources;
+import xlings.core.subos.manifest;
+
+namespace xlings::xself {
+
+bool is_builtin_shim(std::string_view name) {
+    for (auto n : SHIM_NAMES_BASE)
+        if (n == name) return true;
+    for (auto n : SHIM_NAMES_OPTIONAL)
+        if (n == name) return true;
+    return false;
+}
+
+bool is_bootstrap_home_root(const fs::path& root) {
+    std::error_code ec;
+    if (root.empty() || !fs::exists(root / ".xlings.json", ec)) return false;
+    if (!fs::exists(root / "bin", ec) || !fs::is_directory(root / "bin", ec)) return false;
+#ifdef _WIN32
+    return fs::exists(root / "bin" / "xlings.exe", ec);
+#else
+    return fs::exists(root / "bin" / "xlings", ec);
+#endif
+}
+
+fs::path xlings_binary_in_home(const fs::path& home_dir) {
+#ifdef _WIN32
+    auto bin = home_dir / "bin" / "xlings.exe";
+#else
+    auto bin = home_dir / "bin" / "xlings";
+#endif
+    if (fs::exists(bin)) return bin;
+    return {};
+}
+
+LinkResult create_shim(const fs::path& source, const fs::path& target) {
+    std::error_code ec;
+
+    if (!fs::exists(source, ec)) return LinkResult::Failed;
+
+    // Free the target path. `fs::remove` alone is not enough on Windows: it
+    // cannot delete a running executable, and the shim being rewritten here is
+    // frequently `xlings.exe` itself during `self update`. The failure was
+    // discarded, so the code went on to hard-link and copy over a path that
+    // was still occupied and reported "failed to create shim ... the process
+    // cannot access the file because it is being used by another process"
+    // (issue #473) -- with the update half-applied.
+    //
+    // displace_locked_file renames the occupant aside on Windows, which works
+    // on a running image, and is a plain unlink on POSIX.
+    if (!platform::displace_locked_file(target)) {
+        log::error("[xlings:self]: cannot free shim path {} "
+                   "(a process is holding it open)", target.string());
+        return LinkResult::Failed;
+    }
+    ec.clear();
+
+#if !defined(_WIN32)
+    // Unix: prefer relative symlink
+    auto rel = fs::relative(source, target.parent_path(), ec);
+    if (!ec && !rel.empty()) {
+        fs::create_symlink(rel, target, ec);
+        if (!ec) return LinkResult::Symlink;
+    }
+    ec.clear();
+    // Fallback: absolute symlink
+    fs::create_symlink(source, target, ec);
+    if (!ec) return LinkResult::Symlink;
+    ec.clear();
+#endif
+
+    // Hardlink (Unix fallback / Windows primary)
+    fs::create_hard_link(source, target, ec);
+    if (!ec) return LinkResult::Hardlink;
+    ec.clear();
+
+    // Final fallback: copy
+    fs::copy_file(source, target, fs::copy_options::overwrite_existing, ec);
+    if (!ec) return LinkResult::Copy;
+
+    log::error("[xlings:self]: failed to create shim {} - {}",
+        target.string(), ec.message());
+    return LinkResult::Failed;
+}
+
+std::size_t ensure_subos_shims(const fs::path& target_bin_dir,
+                               const fs::path& shim_src,
+                               const fs::path& pkg_root) {
+    if (!fs::exists(shim_src)) return 0;
+
+    std::string ext = shim_src.extension().string();
+    std::size_t failures = 0;
+
+    for (auto name : SHIM_NAMES_BASE) {
+        auto dst = target_bin_dir / (std::string(name) + ext);
+        if (create_shim(shim_src, dst) == LinkResult::Failed) ++failures;
+    }
+
+    if (!pkg_root.empty()) {
+        auto bin_dir = pkg_root / "bin";
+        for (auto name : SHIM_NAMES_OPTIONAL) {
+            auto opt_bin = bin_dir / (std::string(name) + ext);
+            if (fs::exists(opt_bin)) {
+                auto dst = target_bin_dir / (std::string(name) + ext);
+                if (create_shim(shim_src, dst) == LinkResult::Failed) ++failures;
+            }
+        }
+    }
+
+    // COMPAT(0.4.8 → drop in 0.6.0): one-shot migration cleanup.
+    compat::v0_4_8::cleanup_legacy_alias_shims(target_bin_dir, shim_src);
+
+    platform::make_files_executable(target_bin_dir);
+    return failures;
+}
+
+void ensure_parent_dirs_(const fs::path& file) {
+    std::error_code ec;
+    if (!file.parent_path().empty()) fs::create_directories(file.parent_path(), ec);
+}
+
+void write_if_missing_(const fs::path& path, std::string_view content) {
+    if (fs::exists(path)) return;
+    ensure_parent_dirs_(path);
+    platform::write_string_to_file(path.string(), std::string(content));
+}
+
+// Give a subos directory a valid `subos_info`, preserving everything else in
+// the file. Idempotent: a block that already validates is left alone, so the
+// envs packages declared into it survive.
+void ensure_subos_manifest_(const fs::path& subos_dir) {
+    namespace mf = xlings::subos::manifest;
+    auto path = subos_dir / ".xlings.json";
+
+    nlohmann::json json = nlohmann::json::object();
+    if (fs::exists(path)) {
+        try {
+            auto parsed = nlohmann::json::parse(
+                platform::read_file_to_string(path.string()), nullptr, false);
+            if (parsed.is_discarded() || !parsed.is_object()) {
+                // Unreadable, not absent. Overwriting would throw away a
+                // workspace we cannot see; leave it for doctor to report.
+                log::warn("[xlings:self]: {} is not readable JSON; leaving it "
+                          "alone (run `xlings self doctor`)",
+                          Config::display_path(path));
+                return;
+            }
+            json = std::move(parsed);
+        } catch (...) { return; }
+    }
+    if (!json.contains("workspace")) json["workspace"] = nlohmann::json::object();
+    if (mf::validate_block(json).empty()) return;
+
+    json[std::string(mf::BLOCK)] =
+        mf::make_block(mf::preserved_runtime(json, mf::DEFAULT_RUNTIME),
+                       std::format("xlings {}", Info::VERSION),
+                       platform::host_glibc_version());
+    ensure_parent_dirs_(path);
+    platform::write_string_to_file(path.string(), json.dump(2));
+}
+
+// Extract the value following `# xlings-profile-version: ` on any line of
+// `text`. Returns an empty string when the marker is absent, which we
+// interpret as "legacy v1" — anything older than the time we started
+// shipping a version marker.
+std::string extract_profile_version_(std::string_view text) {
+    constexpr std::string_view marker = "# xlings-profile-version:";
+    auto pos = text.find(marker);
+    if (pos == std::string_view::npos) return {};
+    auto value_start = pos + marker.size();
+    while (value_start < text.size() &&
+           (text[value_start] == ' ' || text[value_start] == '\t')) {
+        ++value_start;
+    }
+    auto eol = text.find_first_of("\r\n", value_start);
+    auto end = (eol == std::string_view::npos) ? text.size() : eol;
+    auto value = std::string{text.substr(value_start, end - value_start)};
+    while (!value.empty() &&
+           (value.back() == ' ' || value.back() == '\t')) {
+        value.pop_back();
+    }
+    return value;
+}
+
+// Profile-aware writer. Behavior:
+//
+//   1. Path doesn't exist  → write fresh.
+//   2. Path exists, version matches `target_version` → leave alone (we
+//      respect any user edits made after install).
+//   3. Path exists with older or missing version marker → overwrite, log
+//      the upgrade. This is how shell-level subos switching reaches users
+//      who installed before v2 of the profile shipped.
+//
+// The version of the bytes we're shipping comes from
+// xlings::xself::profile_resources::kVersion; the on-disk value comes from
+// the marker line we inject as the first comment of every profile.
+void write_or_upgrade_profile_(const fs::path& path,
+                                      std::string_view content,
+                                      std::string_view target_version) {
+    if (!fs::exists(path)) {
+        ensure_parent_dirs_(path);
+        platform::write_string_to_file(path.string(), std::string(content));
+        return;
+    }
+
+    auto existing = platform::read_file_to_string(path.string());
+    auto existing_version = extract_profile_version_(existing);
+    if (existing_version == target_version) return;
+
+    log::debug("upgrading {} (was: {}, now: {})",
+               path.filename().string(),
+               existing_version.empty() ? "<no marker, treated as v1>"
+                                        : existing_version,
+               target_version);
+    platform::write_string_to_file(path.string(), std::string(content));
+}
+
+// Read-modify-writes `<home>/.xlings.json` without taking the state lock
+// itself. Both callers reach it through `ensure_home_layout`, and the only
+// caller of that is `xself::cmd_install`, which holds the lock for its whole
+// home-rewriting stretch. Acquiring here as well would be harmless (the lock
+// is re-entrant within a process) but would suggest this is safe to call
+// from somewhere unlocked, which it is not.
+void ensure_home_config_defaults_(const fs::path& home_dir) {
+    auto config_path = home_dir / ".xlings.json";
+    nlohmann::json json = nlohmann::json::object();
+
+    if (fs::exists(config_path)) {
+        try {
+            auto content = platform::read_file_to_string(config_path.string());
+            auto parsed = nlohmann::json::parse(content, nullptr, false);
+            if (!parsed.is_discarded() && parsed.is_object()) json = std::move(parsed);
+        } catch (...) {}
+    }
+
+    if (!json.contains("activeSubos") || !json["activeSubos"].is_string() ||
+        json["activeSubos"].get<std::string>().empty()) {
+        json["activeSubos"] = "default";
+    }
+    if (!json.contains("subos") || !json["subos"].is_object()) {
+        json["subos"] = nlohmann::json::object();
+    }
+    if (!json["subos"].contains("default") || !json["subos"]["default"].is_object()) {
+        json["subos"]["default"] = {{"dir", ""}};
+    }
+
+    ensure_parent_dirs_(config_path);
+    platform::write_string_to_file(config_path.string(), json.dump(2));
+}
+
+bool ensure_home_layout(const fs::path& home_dir) {
+    std::error_code ec;
+    if (home_dir.empty()) return false;
+
+    auto default_subos = home_dir / "subos" / "default";
+    auto dirs = {
+        home_dir,
+        home_dir / "bin",
+        home_dir / "config" / "shell",
+        home_dir / "data" / "xpkgs",
+        home_dir / "data" / "runtimedir",
+        home_dir / "data" / "xim-index-repos",
+        home_dir / "data" / "local-indexrepo",
+        default_subos / "bin",
+        default_subos / "lib",
+        default_subos / "usr",
+        default_subos / "generations",
+    };
+
+    for (auto& dir : dirs) {
+        fs::create_directories(dir, ec);
+        if (ec) {
+            log::error("[xlings:self]: failed to create {} - {}",
+                       Config::display_path(dir), ec.message());
+            return false;
+        }
+    }
+
+    auto current_link = home_dir / "subos" / "current";
+    platform::create_directory_link(current_link, default_subos);
+
+    // Not write_if_missing_: every home that predates `subos_info` already has
+    // this file, so "missing" is exactly the case that never fires on the
+    // subos that matters most. `default` is where an ordinary user installs
+    // everything, and a default without the block would make the whole
+    // configuration layer inert on upgrade while looking installed.
+    //
+    // This is also the migration: `self init` runs on install and update, so an
+    // old home repairs its default subos on the next either. Other subos in
+    // that home are `subos doctor --fix`'s job -- init does not enumerate them.
+    ensure_subos_manifest_(default_subos);
+    write_if_missing_(home_dir / "data" / "xim-index-repos" / "xim-indexrepos.json", "{}");
+    // Profile content lives in xlings.core.xself.profile_resources. We use
+    // the version-aware writer so users who installed an older xlings get
+    // their profile auto-upgraded on the next `self init` / `self update`,
+    // while users on the current version preserve any local edits.
+    write_or_upgrade_profile_(home_dir / "config" / "shell" / "xlings-profile.sh",
+                              profile_resources::bash_sh,
+                              profile_resources::kVersion);
+    write_or_upgrade_profile_(home_dir / "config" / "shell" / "xlings-profile.fish",
+                              profile_resources::fish,
+                              profile_resources::kVersion);
+    write_or_upgrade_profile_(home_dir / "config" / "shell" / "xlings-profile.ps1",
+                              profile_resources::pwsh,
+                              profile_resources::kVersion);
+
+    ensure_home_config_defaults_(home_dir);
+
+    auto xlings_bin = xlings_binary_in_home(home_dir);
+    if (!xlings_bin.empty()) {
+        // A home whose shims could not be written is not a laid-out home. It
+        // used to report success anyway, which is how a failed Windows update
+        // produced "healed" alongside the state that made it fail.
+        if (auto failures = ensure_subos_shims(default_subos / "bin",
+                                               xlings_bin, home_dir);
+            failures != 0) {
+            log::error("[xlings:self]: {} shim(s) could not be written into {}",
+                       failures, (default_subos / "bin").string());
+            return false;
+        }
+    }
+
+    return true;
+}
+
+int cmd_init() {
+    auto& p = Config::paths();
+    if (!ensure_home_layout(p.homeDir)) return 1;
+    log::info("init ok");
+    return 0;
+}
+
+}
diff --git a/src/core/xself/init.cppm b/src/core/xself/init.cppm
index 08e2f3a8..329a6746 100644
--- a/src/core/xself/init.cppm
+++ b/src/core/xself/init.cppm
@@ -3,9 +3,6 @@ export module xlings.core.xself.init;
 import std;
 
 import xlings.core.config;
-import xlings.libs.json;
-import xlings.core.log;
-import xlings.platform;
 // Cross-version compat (currently: legacy alias cleanup, profile upgrade).
 // See compact/xself.cppm — each compat lives in its own version sub-namespace.
 import xlings.core.xself.compat;
@@ -45,335 +42,25 @@ export std::size_t ensure_subos_shims(const fs::path& target_bin_dir,
                                       const fs::path& pkg_root);
 export bool ensure_home_layout(const fs::path& home_dir);
 
-bool is_builtin_shim(std::string_view name) {
-    for (auto n : SHIM_NAMES_BASE)
-        if (n == name) return true;
-    for (auto n : SHIM_NAMES_OPTIONAL)
-        if (n == name) return true;
-    return false;
-}
+bool is_builtin_shim(std::string_view name);
 
-bool is_bootstrap_home_root(const fs::path& root) {
-    std::error_code ec;
-    if (root.empty() || !fs::exists(root / ".xlings.json", ec)) return false;
-    if (!fs::exists(root / "bin", ec) || !fs::is_directory(root / "bin", ec)) return false;
-#ifdef _WIN32
-    return fs::exists(root / "bin" / "xlings.exe", ec);
-#else
-    return fs::exists(root / "bin" / "xlings", ec);
-#endif
-}
+bool is_bootstrap_home_root(const fs::path& root);
 
-fs::path xlings_binary_in_home(const fs::path& home_dir) {
-#ifdef _WIN32
-    auto bin = home_dir / "bin" / "xlings.exe";
-#else
-    auto bin = home_dir / "bin" / "xlings";
-#endif
-    if (fs::exists(bin)) return bin;
-    return {};
-}
+fs::path xlings_binary_in_home(const fs::path& home_dir);
 
 // Unified shim creation: symlink (Unix) > hardlink > copy
-LinkResult create_shim(const fs::path& source, const fs::path& target) {
-    std::error_code ec;
-
-    if (!fs::exists(source, ec)) return LinkResult::Failed;
-
-    // Free the target path. `fs::remove` alone is not enough on Windows: it
-    // cannot delete a running executable, and the shim being rewritten here is
-    // frequently `xlings.exe` itself during `self update`. The failure was
-    // discarded, so the code went on to hard-link and copy over a path that
-    // was still occupied and reported "failed to create shim ... the process
-    // cannot access the file because it is being used by another process"
-    // (issue #473) -- with the update half-applied.
-    //
-    // displace_locked_file renames the occupant aside on Windows, which works
-    // on a running image, and is a plain unlink on POSIX.
-    if (!platform::displace_locked_file(target)) {
-        log::error("[xlings:self]: cannot free shim path {} "
-                   "(a process is holding it open)", target.string());
-        return LinkResult::Failed;
-    }
-    ec.clear();
-
-#if !defined(_WIN32)
-    // Unix: prefer relative symlink
-    auto rel = fs::relative(source, target.parent_path(), ec);
-    if (!ec && !rel.empty()) {
-        fs::create_symlink(rel, target, ec);
-        if (!ec) return LinkResult::Symlink;
-    }
-    ec.clear();
-    // Fallback: absolute symlink
-    fs::create_symlink(source, target, ec);
-    if (!ec) return LinkResult::Symlink;
-    ec.clear();
-#endif
-
-    // Hardlink (Unix fallback / Windows primary)
-    fs::create_hard_link(source, target, ec);
-    if (!ec) return LinkResult::Hardlink;
-    ec.clear();
-
-    // Final fallback: copy
-    fs::copy_file(source, target, fs::copy_options::overwrite_existing, ec);
-    if (!ec) return LinkResult::Copy;
-
-    log::error("[xlings:self]: failed to create shim {} - {}",
-        target.string(), ec.message());
-    return LinkResult::Failed;
-}
+LinkResult create_shim(const fs::path& source, const fs::path& target);
 
 std::size_t ensure_subos_shims(const fs::path& target_bin_dir,
                                const fs::path& shim_src,
-                               const fs::path& pkg_root) {
-    if (!fs::exists(shim_src)) return 0;
-
-    std::string ext = shim_src.extension().string();
-    std::size_t failures = 0;
-
-    for (auto name : SHIM_NAMES_BASE) {
-        auto dst = target_bin_dir / (std::string(name) + ext);
-        if (create_shim(shim_src, dst) == LinkResult::Failed) ++failures;
-    }
-
-    if (!pkg_root.empty()) {
-        auto bin_dir = pkg_root / "bin";
-        for (auto name : SHIM_NAMES_OPTIONAL) {
-            auto opt_bin = bin_dir / (std::string(name) + ext);
-            if (fs::exists(opt_bin)) {
-                auto dst = target_bin_dir / (std::string(name) + ext);
-                if (create_shim(shim_src, dst) == LinkResult::Failed) ++failures;
-            }
-        }
-    }
-
-    // COMPAT(0.4.8 → drop in 0.6.0): one-shot migration cleanup.
-    compat::v0_4_8::cleanup_legacy_alias_shims(target_bin_dir, shim_src);
-
-    platform::make_files_executable(target_bin_dir);
-    return failures;
-}
-
-static void ensure_parent_dirs_(const fs::path& file) {
-    std::error_code ec;
-    if (!file.parent_path().empty()) fs::create_directories(file.parent_path(), ec);
-}
-
-static void write_if_missing_(const fs::path& path, std::string_view content) {
-    if (fs::exists(path)) return;
-    ensure_parent_dirs_(path);
-    platform::write_string_to_file(path.string(), std::string(content));
-}
-
-// Give a subos directory a valid `subos_info`, preserving everything else in
-// the file. Idempotent: a block that already validates is left alone, so the
-// envs packages declared into it survive.
-static void ensure_subos_manifest_(const fs::path& subos_dir) {
-    namespace mf = xlings::subos::manifest;
-    auto path = subos_dir / ".xlings.json";
-
-    nlohmann::json json = nlohmann::json::object();
-    if (fs::exists(path)) {
-        try {
-            auto parsed = nlohmann::json::parse(
-                platform::read_file_to_string(path.string()), nullptr, false);
-            if (parsed.is_discarded() || !parsed.is_object()) {
-                // Unreadable, not absent. Overwriting would throw away a
-                // workspace we cannot see; leave it for doctor to report.
-                log::warn("[xlings:self]: {} is not readable JSON; leaving it "
-                          "alone (run `xlings self doctor`)",
-                          Config::display_path(path));
-                return;
-            }
-            json = std::move(parsed);
-        } catch (...) { return; }
-    }
-    if (!json.contains("workspace")) json["workspace"] = nlohmann::json::object();
-    if (mf::validate_block(json).empty()) return;
-
-    json[std::string(mf::BLOCK)] =
-        mf::make_block(mf::preserved_runtime(json, mf::DEFAULT_RUNTIME),
-                       std::format("xlings {}", Info::VERSION),
-                       platform::host_glibc_version());
-    ensure_parent_dirs_(path);
-    platform::write_string_to_file(path.string(), json.dump(2));
-}
-
-// Extract the value following `# xlings-profile-version: ` on any line of
-// `text`. Returns an empty string when the marker is absent, which we
-// interpret as "legacy v1" — anything older than the time we started
-// shipping a version marker.
-static std::string extract_profile_version_(std::string_view text) {
-    constexpr std::string_view marker = "# xlings-profile-version:";
-    auto pos = text.find(marker);
-    if (pos == std::string_view::npos) return {};
-    auto value_start = pos + marker.size();
-    while (value_start < text.size() &&
-           (text[value_start] == ' ' || text[value_start] == '\t')) {
-        ++value_start;
-    }
-    auto eol = text.find_first_of("\r\n", value_start);
-    auto end = (eol == std::string_view::npos) ? text.size() : eol;
-    auto value = std::string{text.substr(value_start, end - value_start)};
-    while (!value.empty() &&
-           (value.back() == ' ' || value.back() == '\t')) {
-        value.pop_back();
-    }
-    return value;
-}
-
-// Profile-aware writer. Behavior:
-//
-//   1. Path doesn't exist  → write fresh.
-//   2. Path exists, version matches `target_version` → leave alone (we
-//      respect any user edits made after install).
-//   3. Path exists with older or missing version marker → overwrite, log
-//      the upgrade. This is how shell-level subos switching reaches users
-//      who installed before v2 of the profile shipped.
-//
-// The version of the bytes we're shipping comes from
-// xlings::xself::profile_resources::kVersion; the on-disk value comes from
-// the marker line we inject as the first comment of every profile.
-static void write_or_upgrade_profile_(const fs::path& path,
-                                      std::string_view content,
-                                      std::string_view target_version) {
-    if (!fs::exists(path)) {
-        ensure_parent_dirs_(path);
-        platform::write_string_to_file(path.string(), std::string(content));
-        return;
-    }
-
-    auto existing = platform::read_file_to_string(path.string());
-    auto existing_version = extract_profile_version_(existing);
-    if (existing_version == target_version) return;
-
-    log::debug("upgrading {} (was: {}, now: {})",
-               path.filename().string(),
-               existing_version.empty() ? "<no marker, treated as v1>"
-                                        : existing_version,
-               target_version);
-    platform::write_string_to_file(path.string(), std::string(content));
-}
-
-// Read-modify-writes `<home>/.xlings.json` without taking the state lock
-// itself. Both callers reach it through `ensure_home_layout`, and the only
-// caller of that is `xself::cmd_install`, which holds the lock for its whole
-// home-rewriting stretch. Acquiring here as well would be harmless (the lock
-// is re-entrant within a process) but would suggest this is safe to call
-// from somewhere unlocked, which it is not.
-static void ensure_home_config_defaults_(const fs::path& home_dir) {
-    auto config_path = home_dir / ".xlings.json";
-    nlohmann::json json = nlohmann::json::object();
-
-    if (fs::exists(config_path)) {
-        try {
-            auto content = platform::read_file_to_string(config_path.string());
-            auto parsed = nlohmann::json::parse(content, nullptr, false);
-            if (!parsed.is_discarded() && parsed.is_object()) json = std::move(parsed);
-        } catch (...) {}
-    }
-
-    if (!json.contains("activeSubos") || !json["activeSubos"].is_string() ||
-        json["activeSubos"].get<std::string>().empty()) {
-        json["activeSubos"] = "default";
-    }
-    if (!json.contains("subos") || !json["subos"].is_object()) {
-        json["subos"] = nlohmann::json::object();
-    }
-    if (!json["subos"].contains("default") || !json["subos"]["default"].is_object()) {
-        json["subos"]["default"] = {{"dir", ""}};
-    }
-
-    ensure_parent_dirs_(config_path);
-    platform::write_string_to_file(config_path.string(), json.dump(2));
-}
-
-bool ensure_home_layout(const fs::path& home_dir) {
-    std::error_code ec;
-    if (home_dir.empty()) return false;
-
-    auto default_subos = home_dir / "subos" / "default";
-    auto dirs = {
-        home_dir,
-        home_dir / "bin",
-        home_dir / "config" / "shell",
-        home_dir / "data" / "xpkgs",
-        home_dir / "data" / "runtimedir",
-        home_dir / "data" / "xim-index-repos",
-        home_dir / "data" / "local-indexrepo",
-        default_subos / "bin",
-        default_subos / "lib",
-        default_subos / "usr",
-        default_subos / "generations",
-    };
-
-    for (auto& dir : dirs) {
-        fs::create_directories(dir, ec);
-        if (ec) {
-            log::error("[xlings:self]: failed to create {} - {}",
-                       Config::display_path(dir), ec.message());
-            return false;
-        }
-    }
-
-    auto current_link = home_dir / "subos" / "current";
-    platform::create_directory_link(current_link, default_subos);
-
-    // Not write_if_missing_: every home that predates `subos_info` already has
-    // this file, so "missing" is exactly the case that never fires on the
-    // subos that matters most. `default` is where an ordinary user installs
-    // everything, and a default without the block would make the whole
-    // configuration layer inert on upgrade while looking installed.
-    //
-    // This is also the migration: `self init` runs on install and update, so an
-    // old home repairs its default subos on the next either. Other subos in
-    // that home are `subos doctor --fix`'s job -- init does not enumerate them.
-    ensure_subos_manifest_(default_subos);
-    write_if_missing_(home_dir / "data" / "xim-index-repos" / "xim-indexrepos.json", "{}");
-    // Profile content lives in xlings.core.xself.profile_resources. We use
-    // the version-aware writer so users who installed an older xlings get
-    // their profile auto-upgraded on the next `self init` / `self update`,
-    // while users on the current version preserve any local edits.
-    write_or_upgrade_profile_(home_dir / "config" / "shell" / "xlings-profile.sh",
-                              profile_resources::bash_sh,
-                              profile_resources::kVersion);
-    write_or_upgrade_profile_(home_dir / "config" / "shell" / "xlings-profile.fish",
-                              profile_resources::fish,
-                              profile_resources::kVersion);
-    write_or_upgrade_profile_(home_dir / "config" / "shell" / "xlings-profile.ps1",
-                              profile_resources::pwsh,
-                              profile_resources::kVersion);
-
-    ensure_home_config_defaults_(home_dir);
-
-    auto xlings_bin = xlings_binary_in_home(home_dir);
-    if (!xlings_bin.empty()) {
-        // A home whose shims could not be written is not a laid-out home. It
-        // used to report success anyway, which is how a failed Windows update
-        // produced "healed" alongside the state that made it fail.
-        if (auto failures = ensure_subos_shims(default_subos / "bin",
-                                               xlings_bin, home_dir);
-            failures != 0) {
-            log::error("[xlings:self]: {} shim(s) could not be written into {}",
-                       failures, (default_subos / "bin").string());
-            return false;
-        }
-    }
+                               const fs::path& pkg_root);
 
-    return true;
-}
+bool ensure_home_layout(const fs::path& home_dir);
 
 // `xlings self init` — bootstrap (or repair) the home directory layout.
 // Thin wrapper over ensure_home_layout; kept here so the dispatcher in
 // xself.cppm can route by command name without pulling Config into a
 // separate translation unit.
-export int cmd_init() {
-    auto& p = Config::paths();
-    if (!ensure_home_layout(p.homeDir)) return 1;
-    log::info("init ok");
-    return 0;
-}
+export int cmd_init();
 
 } // namespace xlings::xself
diff --git a/src/core/xself/install.cpp b/src/core/xself/install.cpp
new file mode 100644
index 00000000..b17d1dee
--- /dev/null
+++ b/src/core/xself/install.cpp
@@ -0,0 +1,814 @@
+module xlings.core.xself.install;
+
+import std;
+import xlings.core.xself.init;
+import xlings.core.xself.shell_profile;
+import xlings.core.config;
+import xlings.core.xvm.lock;
+import xlings.libs.json;
+import xlings.libs.tinyhttps;
+import xlings.core.log;
+import xlings.platform;
+import xlings.core.utils;
+import xlings.core.version_order;
+
+namespace xlings::xself {
+
+std::string read_version_from_json(const fs::path& homeDir) {
+    auto conf = homeDir / ".xlings.json";
+    if (!fs::exists(conf)) return "";
+    try {
+        auto content = platform::read_file_to_string(conf.string());
+        auto j = nlohmann::json::parse(content, nullptr, false);
+        if (!j.is_discarded() && j.contains("version") && j["version"].is_string()) {
+            auto v = j["version"].get<std::string>();
+            if (v.starts_with("v")) v = v.substr(1);
+            return v;
+        }
+    } catch (...) {}
+    return "";
+}
+
+std::optional<std::string> normalize_mirror_(std::string mirror) {
+    mirror = utils::trim_string(mirror);
+    std::ranges::transform(mirror, mirror.begin(), [](unsigned char c) {
+        return static_cast<char>(std::toupper(c));
+    });
+    if (mirror == "GLOBAL" || mirror == "CN") return mirror;
+    return std::nullopt;
+}
+
+std::string read_mirror_from_json_(const fs::path& configPath) {
+    if (!fs::exists(configPath)) return {};
+    try {
+        auto content = platform::read_file_to_string(configPath.string());
+        auto json = nlohmann::json::parse(content, nullptr, false);
+        if (!json.is_discarded() && json.is_object() &&
+            json.contains("mirror") && json["mirror"].is_string()) {
+            if (auto mirror = normalize_mirror_(json["mirror"].get<std::string>()))
+                return *mirror;
+        }
+    } catch (...) {}
+    return {};
+}
+
+std::optional<std::string> env_install_mirror_() {
+    for (auto name : {"XLINGS_INSTALL_MIRROR", "XLINGS_MIRROR", "XLINGS_RELEASE_MIRROR"}) {
+        if (auto value = utils::get_env_or_default(name); !value.empty()) {
+            if (auto mirror = normalize_mirror_(value)) return mirror;
+        }
+    }
+    return std::nullopt;
+}
+
+std::string detect_install_mirror_() {
+    if (auto mirror = env_install_mirror_()) return *mirror;
+
+    constexpr int timeoutMs = 1000;
+    constexpr double preferCnDeltaSec = 0.02;  // 20ms
+    auto to_latency_ms_text = [](double sec) {
+        if (!std::isfinite(sec)) return std::string("timeout");
+        auto ms = static_cast<long long>(std::llround(sec * 1000.0));
+        return std::to_string(ms);
+    };
+
+    // Probe the actual RESOURCE host of each mirror — that's what package
+    // downloads (the bulk of install traffic) hit. GLOBAL serves from
+    // github.com, CN from gitcode.com. (Earlier this probed gitee.com — the CN
+    // *index* host — which on some China-mobile / Termux links is throttled even
+    // though gitcode.com is fine, so GLOBAL was wrongly kept and every xim
+    // download then stalled on the unreachable github.)
+    auto globalLatencySec = tinyhttps::probe_latency("https://github.com", timeoutMs);
+    log::println("[xlings:self] https://github.com: {} ms", to_latency_ms_text(globalLatencySec));
+
+    auto cnLatencySec = tinyhttps::probe_latency("https://gitcode.com", timeoutMs);
+    log::println("[xlings:self] https://gitcode.com: {} ms", to_latency_ms_text(cnLatencySec));
+
+    // Pick CN when its resource host is reachable AND GitHub is either
+    // unreachable or meaningfully slower. This makes a github-blocked link
+    // (gitcode reachable) auto-select CN instead of falling back to a dead
+    // GLOBAL.
+    if (std::isfinite(cnLatencySec) &&
+        (!std::isfinite(globalLatencySec) || cnLatencySec + preferCnDeltaSec < globalLatencySec)) {
+        return "CN";
+    }
+    return "GLOBAL";
+}
+
+void set_mirror_fields_(nlohmann::json& json, const std::string& mirror) {
+    json["mirror"] = mirror;
+    json["xim"]["mirrors"]["index-repo"]["GLOBAL"] =
+        "https://github.com/openxlings/xim-pkgindex.git";
+    json["xim"]["mirrors"]["index-repo"]["CN"] =
+        "https://gitee.com/sunrisepeak/xim-pkgindex.git";
+    json["xim"]["mirrors"]["res-server"]["GLOBAL"] =
+        "https://github.com/xlings-res";
+    json["xim"]["mirrors"]["res-server"]["CN"] =
+        "https://gitcode.com/xlings-res";
+
+    if (mirror == "CN") {
+        json["xim"]["res-server"] = "https://gitcode.com/xlings-res";
+        json["xim"]["index-repo"] = "https://gitee.com/sunrisepeak/xim-pkgindex.git";
+        json["repo"] = "https://gitee.com/sunrisepeak/xlings.git";
+    } else {
+        json["xim"]["res-server"] = "https://github.com/xlings-res";
+        json["xim"]["index-repo"] = "https://github.com/openxlings/xim-pkgindex.git";
+        json["repo"] = "https://github.com/openxlings/xlings.git";
+    }
+}
+
+void configure_install_mirror_(const fs::path& targetHome,
+                                      const std::string& existingMirror,
+                                      bool overwriteDataSubos) {
+    auto envMirror = env_install_mirror_();
+    if (!envMirror && !overwriteDataSubos && !existingMirror.empty()) {
+        return;
+    }
+
+    auto mirror = envMirror ? *envMirror : detect_install_mirror_();
+    auto configPath = targetHome / ".xlings.json";
+
+    nlohmann::json json = nlohmann::json::object();
+    if (fs::exists(configPath)) {
+        try {
+            auto content = platform::read_file_to_string(configPath.string());
+            auto parsed = nlohmann::json::parse(content, nullptr, false);
+            if (!parsed.is_discarded() && parsed.is_object()) json = std::move(parsed);
+        } catch (...) {}
+    }
+
+    set_mirror_fields_(json, mirror);
+    platform::write_string_to_file(configPath.string(), json.dump(2));
+    log::println("[xlings:self] mirror: {}", mirror);
+}
+
+/// True if path is under a temp dir (e.g. /tmp, $TMPDIR, $TEMP, $RUNNER_TEMP). Used to detect
+/// quick_install extract dir — we must install to ~/.xlings, not "fix links" in place.
+bool is_under_temp_dir(const fs::path& p) {
+    auto s = p.generic_string();  // forward slashes for portable comparison
+    // quick_install uses "xlings-install" in temp dir name — definitive indicator
+    if (s.find("xlings-install") != std::string::npos) return true;
+    if (s.find("/tmp/") == 0 || s.find("/tmp") == 0) return true;
+#if defined(__APPLE__)
+    // macOS: /var/folders/... is system temp; canonical paths may use /private/var
+    if (s.find("/var/folders/") != std::string::npos ||
+        s.find("/private/var/folders/") != std::string::npos)
+        return true;
+#endif
+#if defined(_WIN32)
+    // Windows: match path segments /Temp/ or /Tmp/ (GetTempPath uses these)
+    if (s.find("/Temp/") != std::string::npos || s.find("/Tmp/") != std::string::npos ||
+        s.find("/temp/") != std::string::npos || s.find("/tmp/") != std::string::npos)
+        return true;
+#endif
+    for (const char* env : {"TMPDIR", "TEMP", "TMP", "RUNNER_TEMP"}) {
+        if (const char* v = std::getenv(env)) {
+            auto prefix = fs::path(v).generic_string();
+            if (prefix.empty()) continue;
+            auto prefixSlash = prefix;
+            if (prefixSlash.back() != '/') prefixSlash += '/';
+            if (s.starts_with(prefixSlash) || s == prefix) return true;
+#if defined(__APPLE__)
+            // macOS: /var resolves to /private/var; canonical paths may have /private prefix
+            if (prefix.starts_with("/var/") && s.starts_with("/private" + prefixSlash))
+                return true;
+#endif
+        }
+    }
+    return false;
+}
+
+fs::path detect_source_dir() {
+    // Check CWD first: on Windows/PowerShell, `xlings` resolves to the PATH-installed
+    // binary even when the user is inside a new release package directory.
+    std::error_code ec;
+    auto cwd = fs::current_path(ec);
+    if (!ec && !cwd.empty() && is_bootstrap_home_root(cwd)) {
+        return fs::weakly_canonical(cwd);
+    }
+
+    auto exe = platform::get_executable_path();
+    if (exe.empty()) return {};
+    auto binDir = exe.parent_path();
+    auto candidate = binDir.parent_path();
+    log::debug("[xlings:self]: candidate: {}", candidate.string());
+    if (is_bootstrap_home_root(candidate)) {
+        return fs::weakly_canonical(candidate);
+    }
+    return {};
+}
+
+fs::path detect_existing_home() {
+    auto envHome = utils::get_env_or_default("XLINGS_HOME");
+    if (!envHome.empty()) {
+        auto p = fs::path(envHome);
+        // An explicit target is authoritative even for the first install.
+        // PATH discovery is only a convenience when the caller did not name
+        // a destination; otherwise an unrelated older xlings can hijack a
+        // cold-home bootstrap.
+        std::error_code ec;
+        auto absolute = fs::absolute(p, ec);
+        if (ec) return p.lexically_normal();
+        if (fs::exists(absolute, ec)) {
+            auto canonical = fs::weakly_canonical(absolute, ec);
+            return ec ? absolute.lexically_normal() : canonical;
+        }
+        return absolute.lexically_normal();
+    }
+    auto [rc, out] = platform::run_command_capture(
+#ifdef _WIN32
+        "where xlings 2>nul"
+#else
+        "command -v xlings 2>/dev/null"
+#endif
+    );
+    (void)rc;
+    // "where"/"command -v" may return multiple lines; use first valid path
+    auto lines = utils::split_string(out, '\n');
+    for (const auto& line : lines) {
+        auto binPath = utils::trim_string(line);
+        if (binPath.empty() || !fs::exists(binPath)) continue;
+        auto p = fs::weakly_canonical(fs::path(binPath));
+        // Walk upward from the executable directory and locate install root by markers.
+        // Note: path("/").parent_path() returns "/" on Unix (root's parent is itself) — must check to avoid infinite loop.
+        for (auto cur = p.parent_path(); cur != cur.parent_path(); cur = cur.parent_path()) {
+            if (!fs::exists(cur / "bin") || !fs::exists(cur / "subos")) continue;
+            // Ignore temp extract dir (quick_install) — install to ~/.xlings instead.
+            if (!is_under_temp_dir(cur))
+                return cur;
+            break;
+        }
+    }
+    return {};
+}
+
+fs::path default_home() {
+    return fs::path(platform::get_home_dir()) / ".xlings";
+}
+
+void copy_directory_contents(const fs::path& src, const fs::path& dst) {
+    std::error_code ec;
+    fs::create_directories(dst, ec);
+    for (auto& entry : platform::dir_entries(src)) {
+        auto target = dst / entry.path().filename();
+        if (entry.is_directory()) {
+            fs::copy(entry.path(), target,
+                     fs::copy_options::recursive | fs::copy_options::overwrite_existing, ec);
+        } else {
+            fs::copy_file(entry.path(), target,
+                          fs::copy_options::overwrite_existing, ec);
+        }
+        if (ec) {
+            log::error("[xlings:self] copy failed: {} -> {} ({})",
+                       entry.path().string(), target.string(), ec.message());
+            ec.clear();
+        }
+    }
+}
+
+void setup_shell_profiles(const fs::path& homeDir) {
+#if defined(__linux__) || defined(__APPLE__)
+    auto profileSh   = homeDir / "config" / "shell" / "xlings-profile.sh";
+    auto profileFish = homeDir / "config" / "shell" / "xlings-profile.fish";
+
+    auto sourceLine = "test -f \"" + profileSh.string() + "\" && source \"" + profileSh.string() + "\"";
+
+    // rc files belong to the INVOKING user. Under `sudo` this is the real
+    // user's home (not root's $HOME), so the person who ran the install
+    // actually gets xlings on their PATH. Identical to get_home_dir() when
+    // not running via sudo, so non-sudo behavior is unchanged.
+    fs::path rcHome(platform::target_home());
+
+    std::vector<fs::path> profiles;
+#if defined(__APPLE__)
+    profiles = {
+        rcHome / ".zshrc",
+        rcHome / ".bashrc",
+        rcHome / ".zprofile",
+    };
+#else
+    profiles = {
+        rcHome / ".bashrc",
+        rcHome / ".zshrc",
+        rcHome / ".profile",
+    };
+#endif
+
+    bool added = false;
+    for (auto& prof : profiles) {
+        if (!fs::exists(prof)) continue;
+        auto content = platform::read_file_to_string(prof.string());
+        if (content.find("xlings-profile") != std::string::npos) {
+            log::debug("[xlings:self] profile ok ({})", prof.filename().string());
+            added = true;
+            break;
+        }
+        std::string appendStr = "\n# xlings\n" + sourceLine + "\n";
+        platform::write_string_to_file(prof.string(), content + appendStr);
+        // If we ran via sudo, hand the rc file back to its real owner.
+        platform::chown_to_invoker(prof, /*recursive=*/false);
+        log::println("[xlings:self] added profile ({})", prof.filename().string());
+        added = true;
+        break;
+    }
+
+    auto fishConfig = rcHome / ".config" / "fish" / "config.fish";
+    auto fishSourceLine = "test -f \"" + profileFish.string() + "\"; and source \"" + profileFish.string() + "\"";
+    if (fs::exists(fishConfig) ||
+        platform::run_command_capture("command -v fish 2>/dev/null").first == 0) {
+        fs::create_directories(fishConfig.parent_path());
+        std::string fishContent;
+        if (fs::exists(fishConfig))
+            fishContent = platform::read_file_to_string(fishConfig.string());
+        if (fishContent.find("xlings-profile") == std::string::npos) {
+            platform::write_string_to_file(fishConfig.string(),
+                                           fishContent + "\n# xlings\n" + fishSourceLine + "\n");
+            log::println("[xlings:self] added profile (config.fish)");
+        } else {
+            log::debug("[xlings:self] profile ok (fish)");
+        }
+        // Restore ownership of the fish config tree we may have created.
+        platform::chown_to_invoker(rcHome / ".config" / "fish");
+        added = true;
+    }
+
+    if (!added) {
+        // No existing shell rc — e.g. a fresh Termux / minimal container, where
+        // ~/.bashrc isn't created until the user edits it. Rather than dump a
+        // manual step (which breaks the zero-config promise: the very next
+        // command `xlings` would be "command not found"), create the default rc
+        // ourselves so xlings lands on PATH on first login.
+        //
+        // Best-effort: only when the home dir actually exists and the write
+        // succeeds. A throwing write (e.g. simulated-sudo to a non-existent
+        // home) must NOT abort `self install` — fall back to the manual hint.
+        bool created = false;
+        auto prof = rcHome / ".bashrc";
+        std::error_code ec;
+        if (fs::exists(rcHome, ec) && !ec) {
+            try {
+                std::string content;
+                if (fs::exists(prof)) content = platform::read_file_to_string(prof.string());
+                platform::write_string_to_file(prof.string(),
+                                               content + "\n# xlings\n" + sourceLine + "\n");
+                platform::chown_to_invoker(prof, /*recursive=*/false);
+                created = true;
+            } catch (const std::exception& e) {
+                log::debug("[xlings:self] could not create {}: {}", prof.string(), e.what());
+            }
+        }
+        if (created) {
+            log::println("[xlings:self] created profile ({})", prof.filename().string());
+            log::println("[xlings:self] open a new shell or: source \"{}\"", profileSh.string());
+        } else {
+            std::println("[xlings:self] no shell profile found, add manually:");
+            std::println("  {}", sourceLine);
+        }
+    }
+#elif defined(_WIN32)
+    auto xlingsBin = homeDir / "subos" / "current" / "bin";
+    std::string setHomeCmd = "powershell -NoProfile -Command \""
+        "[System.Environment]::SetEnvironmentVariable('XLINGS_HOME','"
+        + homeDir.string() + "','User');"
+        "Write-Host 'XLINGS_HOME updated'\"";
+    platform::exec(setHomeCmd);
+
+    std::string checkCmd = "powershell -NoProfile -Command \""
+        "$p=[System.Environment]::GetEnvironmentVariable('Path','User');"
+        "if($p -notlike '*" + xlingsBin.string() + "*'){"
+        "[System.Environment]::SetEnvironmentVariable('Path','"
+        + xlingsBin.string() + ";'+$p,'User');"
+        "Write-Host 'PATH updated'"
+        "}else{Write-Host 'PATH already set'}\"";
+    platform::exec(checkCmd);
+
+    // Hook every PowerShell host on the box, not just the one xlings happens
+    // to shell out to. Windows PowerShell 5.1 and PowerShell 7+ read different
+    // startup files, and `xlings subos use` spawns pwsh.exe first -- so the
+    // 5.1-only hook this used to be left the shell xlings itself launches
+    // without XLINGS_BIN on PATH (#387). Policy and mechanics live in
+    // xlings.core.xself.shell_profile, which is unit-tested; what stays here
+    // is the process spawning and the reporting.
+    auto profilePs1 = homeDir / "config" / "shell" / "xlings-profile.ps1";
+    auto snippet = shell_profile::powershell_snippet(profilePs1);
+
+    auto probes = shell_profile::probe_hosts(
+        shell_profile::kPowerShellHosts,
+        [](const std::string& cmd) {
+            auto result = platform::run_command_capture(cmd);
+            log::debug("[xlings:self] probe: {} -> rc={} out={}",
+                       cmd, result.first, result.second);
+            return result;
+        });
+
+    int hooked = 0;
+    for (const auto& p : probes) {
+        if (p.status == shell_profile::ProbeStatus::NotInstalled) {
+            // The ordinary shape of a machine without PowerShell 7. Not news.
+            log::debug("[xlings:self] {} not installed", p.host);
+            continue;
+        }
+        if (p.status == shell_profile::ProbeStatus::Unusable) {
+            // It started and said something we cannot hook. That is a defect,
+            // not a machine shape, so it is shown with what it actually said.
+            log::warn("[xlings:self] {} did not report $PROFILE: {}",
+                      p.host, p.output);
+            continue;
+        }
+        switch (shell_profile::hook(p.path, snippet)) {
+        case shell_profile::HookResult::Added:
+            ++hooked;
+            log::println("[xlings:self] added profile ({})", p.host);
+            log::debug("[xlings:self]   {}", p.path.string());
+            break;
+        case shell_profile::HookResult::AlreadyHooked:
+            ++hooked;
+            log::debug("[xlings:self] profile ok ({})", p.host);
+            break;
+        case shell_profile::HookResult::Failed:
+            // Reported rather than swallowed: the old one-liner discarded its
+            // exit code, so a profile that was never written looked exactly
+            // like one that was.
+            log::warn("[xlings:self] could not write {} profile: {}",
+                      p.host, p.path.string());
+            break;
+        }
+    }
+
+    if (hooked == 0) {
+        std::println("[xlings:self] no PowerShell host was configured, add manually to $PROFILE:");
+        std::println("  {}", snippet);
+    }
+#endif
+}
+
+// Advise when running as root, distinguishing the two failure-prone cases:
+// pure root (files land in /root/.xlings, invisible to normal users) vs sudo
+// (we redirect rc files + chown ~/.xlings back to the real user). No-op for
+// the ordinary non-root install, so existing behavior is untouched.
+void warn_root_context_() {
+    // Cross-platform by construction: is_root() is false on Windows (and for
+    // any non-root POSIX run), so this returns immediately and adds no
+    // behavior off the root path — no platform macro needed.
+    if (!platform::is_root()) return;
+    if (auto inv = platform::sudo_invoker()) {
+        log::warn("[xlings:self] running via sudo (user '{}')", inv->user);
+        log::warn("  rc files target {}'s home; ~/.xlings is chowned back to it",
+                  inv->user.empty() ? "the invoking user" : inv->user.c_str());
+        log::warn("  tip: xlings is user-space — running without sudo also works");
+    } else {
+        log::warn("[xlings:self] running as root — installing to root's home");
+        log::warn("  this install is only on root's PATH; normal users won't see it");
+    }
+}
+
+// `XLINGS_HOME` as the CALLER set it, canonicalized the same way
+// detect_existing_home does, so the two can be compared without a spurious
+// mismatch from a trailing slash or a symlinked prefix. Empty when the caller
+// did not name one.
+//
+// xlings::ambient_home_env(), NOT getenv: main.cpp exports XLINGS_HOME to the
+// home it resolved before any command runs, so getenv here answers "what did
+// xlings decide" and never "what did the user ask for". Reading it was a
+// second answerer to a question that already had one -- and it made this guard
+// refuse a caller who had explicitly passed `env -u XLINGS_HOME`.
+fs::path explicit_home_() {
+    const auto& ambient = xlings::ambient_home_env();
+    if (!ambient) return {};
+    const auto& envHome = *ambient;
+    if (envHome.empty()) return {};
+    std::error_code ec;
+    auto absolute = fs::absolute(fs::path(envHome), ec);
+    if (ec) return fs::path(envHome).lexically_normal();
+    auto canonical = fs::weakly_canonical(absolute, ec);
+    return ec ? absolute.lexically_normal() : canonical;
+}
+
+// Do these two paths name the same directory?
+//
+// `fs::equivalent` FIRST, and only then string comparison. Comparing
+// canonicalized strings is wrong on Windows, where the filesystem is
+// case-insensitive and `weakly_canonical` does not fold case: `c:\users\me`
+// and `C:\Users\Me` are one directory and two strings. This guard REFUSES on
+// a difference, so a false difference is a refused install -- the failure mode
+// is louder than the one it was added to prevent.
+//
+// `equivalent` needs both to exist, which is exactly when the question is
+// answerable; when one does not, a normalized string compare is all there is,
+// and a non-existent target cannot be the home someone is worried about
+// overwriting anyway.
+bool same_dir_(const fs::path& a, const fs::path& b) {
+    if (a.empty() || b.empty()) return false;
+    std::error_code ec;
+    if (fs::exists(a, ec) && fs::exists(b, ec)) {
+        std::error_code eqEc;
+        if (bool eq = fs::equivalent(a, b, eqEc); !eqEc) return eq;
+    }
+    ec.clear();
+    auto ca = fs::weakly_canonical(a, ec);
+    auto cb = fs::weakly_canonical(b, ec);
+    if (ec) return a.lexically_normal() == b.lexically_normal();
+    return ca == cb;
+}
+
+int cmd_install() {
+    warn_root_context_();
+    auto srcDir = detect_source_dir();
+    if (srcDir.empty()) {
+        log::error("[xlings:self] cannot detect source package directory.");
+        log::error("  run this command from inside a valid xlings release package");
+        return 1;
+    }
+
+    auto pkgVersion = read_version_from_json(srcDir);
+    if (pkgVersion.empty()) pkgVersion = std::string(Info::VERSION);
+    auto existingHome = detect_existing_home();
+    auto targetHome = existingHome.empty() ? default_home() : existingHome;
+    auto installedVersion = read_version_from_json(targetHome);
+
+    // When running from a temp extract (quick_install), install to ~/.xlings — temp dir will be deleted.
+    std::error_code cmp_ec;
+    bool sameDir = fs::equivalent(srcDir, targetHome, cmp_ec);
+    bool fromTempExtract = false;
+    fs::path existingPath = targetHome;  // path of existing install (may differ from target)
+    if (!cmp_ec && sameDir && is_under_temp_dir(srcDir)) {
+        targetHome = default_home();
+        installedVersion = read_version_from_json(targetHome);
+        existingPath = targetHome;
+        fromTempExtract = true;  // no TTY in CI, skip prompts, always proceed
+    }
+    if (!cmp_ec && sameDir && !fromTempExtract) {
+        auto fallbackHome = default_home();
+        std::error_code homeEc;
+        bool sourceIsDefaultHome = fs::equivalent(srcDir, fallbackHome, homeEc);
+        if (homeEc || !sourceIsDefaultHome) {
+            targetHome = fallbackHome;
+            installedVersion = read_version_from_json(targetHome);
+            existingPath = targetHome;
+            cmp_ec.clear();
+            sameDir = false;
+        }
+    }
+    auto existingMirror = read_mirror_from_json_(targetHome / ".xlings.json");
+
+    // Install header: show existing (if any) and install target; paths may differ
+    std::println("\n[xlings:self] install");
+    if (!installedVersion.empty()) {
+        std::println("  existing: v{} -> {}", installedVersion, existingPath.string());
+    }
+    std::println("  install:  v{} -> {}", pkgVersion, targetHome.string());
+
+    // An explicit XLINGS_HOME that this command is NOT going to honour.
+    //
+    // XLINGS_HOME is honoured in the ordinary case -- detect_existing_home
+    // takes it as authoritative -- but the two `sameDir` branches above
+    // silently retarget to `$HOME/.xlings`, and silently is the problem. The
+    // rest of this repository isolates by XLINGS_HOME, so a verification step
+    // that sets it and then watches this command write somewhere else is
+    // writing into a home it believed it had ruled out.
+    //
+    // REFUSE, do not retarget-and-warn. A warning scrolls past under the
+    // progress output (measured: the header above was already invisible in a
+    // real run), and by the time anyone reads it the home has been
+    // overwritten. Non-zero exit with the two paths named is recoverable; a
+    // warning is not.
+    //
+    // Only when they DISAGREE -- so the ordinary install, and every install
+    // that does not set XLINGS_HOME, is untouched.
+    if (auto envHome = explicit_home_();
+        !envHome.empty() && !same_dir_(envHome, targetHome)) {
+        log::error("[xlings:self] XLINGS_HOME and the install target disagree");
+        log::error("  XLINGS_HOME: {}", envHome.string());
+        log::error("  would write: {}", targetHome.string());
+        log::error("  refusing, because the rest of xlings isolates by "
+                   "XLINGS_HOME and this command would not have");
+        log::error("  hint: to install into XLINGS_HOME, run it from outside "
+                   "that directory; to install into the target above, unset "
+                   "XLINGS_HOME");
+        return 1;
+    }
+
+    // Skip if source == target and not temp — "fix links" in place (e.g. dev from source).
+    if (!cmp_ec && sameDir && !fromTempExtract) {
+        log::println("\n[xlings:self] already in target dir, fixing links");
+        auto lock = xvm::acquire_state_lock(targetHome);
+        if (!lock) {
+            log::error("[xlings:self] {}", lock.error());
+            return 1;
+        }
+        if (!ensure_home_layout(targetHome)) {
+            log::error("[xlings:self] failed to initialize {}", targetHome.string());
+            return 1;
+        }
+        setup_shell_profiles(targetHome);
+        platform::chown_to_invoker(targetHome);
+        log::println("[xlings:self] {} ({}) - ok\n", targetHome.string(), pkgVersion);
+        return 0;
+    }
+
+    // Version / overwrite confirmation (skip when from temp extract — CI / quick_install)
+    bool overwriteDataSubos = false;
+    if (!fromTempExtract) {
+        if (!pkgVersion.empty() && !installedVersion.empty() && pkgVersion == installedVersion) {
+            if (!utils::ask_yes_no("\n[xlings:self] same version installed, reinstall? ", false)) {
+                std::println("[xlings:self] cancelled\n");
+                return 0;
+            }
+            if (fs::exists(targetHome / "data") || fs::exists(targetHome / "subos")) {
+                overwriteDataSubos = utils::ask_yes_no("[xlings:self] overwrite data and subos? ", false);
+            }
+        } else if (fs::exists(targetHome / "bin") && fs::exists(targetHome / "subos")) {
+            // Name both versions, and say which DIRECTION this is.
+            //
+            // The prompt used to read "overwrite existing installation?" with
+            // a default of yes, and an upgrade and a six-week downgrade were
+            // worded identically. That is how a June payload's `self install`
+            // replaced a current entry binary on this machine: the entry then
+            // predated `${XLINGS_DYNAMIC_SUBOS_DIR}`, so every alias in the
+            // home lost its expansion and the first visible symptom was a
+            // toolchain that could not find crt1.o.
+            //
+            // Note the old default was INVERTED against the risk: reinstalling
+            // the same version defaulted to NO, while going backwards
+            // defaulted to YES. Going backwards is the one that needs the
+            // deliberate keystroke.
+            const bool downgrade =
+                !pkgVersion.empty() && !installedVersion.empty()
+                && version_order::compare(pkgVersion, installedVersion) < 0;
+            std::string question;
+            if (installedVersion.empty()) {
+                question = "\n[xlings:self] overwrite existing installation? ";
+            } else if (downgrade) {
+                question = std::format(
+                    "\n[xlings:self] DOWNGRADE v{} -> v{}, overwrite? ",
+                    installedVersion, pkgVersion);
+            } else {
+                question = std::format(
+                    "\n[xlings:self] replace v{} with v{}? ",
+                    installedVersion, pkgVersion);
+            }
+            if (!utils::ask_yes_no(question, !downgrade)) {
+                std::println("[xlings:self] cancelled\n");
+                return 0;
+            }
+        }
+    }
+
+    // Everything past this point rewrites the home: the binary, the layout,
+    // and three separate read-modify-writes of `.xlings.json` (mirror,
+    // version, subos defaults). An install running in another terminal reads
+    // and writes the same file, so hold the home-wide state lock across the
+    // lot -- one lock rather than three, since the writes are interleaved
+    // with the tree replacement and only the whole sequence is meaningful.
+    //
+    // Taken here rather than at the top of the function on purpose: the
+    // confirmation prompts above would otherwise hold the lock for as long as
+    // the user takes to answer, and a lock held on human time is a lock that
+    // makes `xlings install` fail in the next terminal over.
+    //
+    // The patchelf-runtime-dep step below spawns `xlings install -g`. That
+    // child inherits the re-entrancy marker (xvm/lock.cppm) and works under
+    // this lock instead of waiting for one this process cannot release until
+    // the child returns.
+    auto stateLock = xvm::acquire_state_lock(targetHome);
+    if (!stateLock) {
+        log::error("[xlings:self] {}", stateLock.error());
+        return 1;
+    }
+
+    // Selective install: preserve data/ and subos/ unless user chose to overwrite
+    log::println("[xlings:self] copying binaries and config ...");
+    fs::create_directories(targetHome);
+
+    std::error_code ec;
+
+    // 1. Remove non-user dirs; preserve data/subos and .xlings.json unless user chose overwrite
+    if (fs::exists(targetHome)) {
+        for (auto& entry : platform::dir_entries(targetHome)) {
+            auto name = entry.path().filename().string();
+            if (name == "data" || name == "subos") {
+                if (!overwriteDataSubos) continue;
+            }
+            // Preserve .xlings.json — it contains the xvm versions DB and user config.
+            // We merge the new version into it after copying (step 2).
+            if (name == ".xlings.json" && !overwriteDataSubos) continue;
+            fs::remove_all(entry.path(), ec);
+            ec.clear();
+        }
+    }
+
+    // 2. Copy from release, skip data/subos when target already has them; merge subos static parts if exists
+    for (auto& entry : platform::dir_entries(srcDir)) {
+        auto name = entry.path().filename().string();
+        if (name == "data") {
+            if (fs::exists(targetHome / "data") && fs::is_directory(targetHome / "data"))
+                continue;
+        }
+        if (name == "subos") {
+            if (fs::exists(targetHome / "subos") && fs::is_directory(targetHome / "subos")) {
+                continue;  // 已有 subos 则完全保留，不合并（多 subos 且 bin 等无需覆盖）
+            }
+        }
+        // Skip .xlings.json when preserved — we update version below
+        if (name == ".xlings.json" && !overwriteDataSubos && fs::exists(targetHome / name)) {
+            continue;
+        }
+        auto target = targetHome / name;
+        if (entry.is_directory()) {
+            fs::copy(entry.path(), target,
+                     fs::copy_options::recursive | fs::copy_options::overwrite_existing, ec);
+        } else {
+            fs::copy_file(entry.path(), target, fs::copy_options::overwrite_existing, ec);
+        }
+        if (ec) {
+            log::error("[xlings:self] copy failed: {} -> {} ({})",
+                       entry.path().string(), target.string(), ec.message());
+            ec.clear();
+        }
+    }
+
+    // 2b. Update version in preserved .xlings.json
+    {
+        auto configPath = targetHome / ".xlings.json";
+        if (fs::exists(configPath) && !pkgVersion.empty()) {
+            try {
+                auto content = platform::read_file_to_string(configPath.string());
+                auto json = nlohmann::json::parse(content, nullptr, false);
+                if (!json.is_discarded() && json.is_object()) {
+                    json["version"] = "v" + pkgVersion;
+                    platform::write_string_to_file(configPath.string(), json.dump(2));
+                }
+            } catch (...) {}
+        }
+    }
+    configure_install_mirror_(targetHome, existingMirror, overwriteDataSubos);
+
+    // 3. First install: preserve extra trees if the source package still ships them.
+    if (!fs::exists(targetHome / "data") && fs::exists(srcDir / "data")) {
+        copy_directory_contents(srcDir / "data", targetHome / "data");
+    }
+    if (!fs::exists(targetHome / "subos") && fs::exists(srcDir / "subos")) {
+        copy_directory_contents(srcDir / "subos", targetHome / "subos");
+    }
+    if (!fs::exists(targetHome / "config") && fs::exists(srcDir / "config")) {
+        copy_directory_contents(srcDir / "config", targetHome / "config");
+    }
+
+    // 4. Fix permissions (platform-dispatched)
+    platform::make_files_executable(targetHome / "bin");
+
+    // 5. Materialize a complete home layout even if the source package is minimal.
+    if (!ensure_home_layout(targetHome)) {
+        log::error("[xlings:self] failed to initialize {}", targetHome.string());
+        return 1;
+    }
+
+    setup_shell_profiles(targetHome);
+
+    auto verifyBin = targetHome / "bin" /
+#ifdef _WIN32
+        "xlings.exe";
+#else
+        "xlings";
+#endif
+    if (fs::exists(verifyBin)) {
+        auto [rc, out] = platform::run_command_capture(
+            "\"" + verifyBin.string() + "\" -h");
+        if (rc != 0)
+            log::warn("[xlings:self] verification failed");
+    }
+
+#if defined(__linux__)
+    if (fs::exists(verifyBin)) {
+        platform::set_env_variable("XLINGS_HOME", targetHome.string());
+        auto binDir = (targetHome / "subos" / "current" / "bin").string();
+        auto existingPath = std::string(std::getenv("PATH") ? std::getenv("PATH") : "");
+        platform::set_env_variable("PATH", binDir + platform::PATH_SEPARATOR + existingPath);
+
+        log::println("[xlings:self] installing patchelf (runtime dependency) ...");
+        auto rc = platform::exec("xlings install xim:patchelf@0.18.0 -y -g");
+        if (rc != 0) {
+            log::warn("[xlings:self] patchelf install failed (rc={})", rc);
+            log::warn("  hint: run manually: xlings install xim:patchelf@0.18.0 -y");
+        }
+    }
+#endif
+
+    // Hand the freshly-written ~/.xlings back to the invoking user when we
+    // ran via sudo, so a later non-sudo `xlings install` isn't locked out by
+    // root-owned files. No-op for pure root / non-root installs.
+    platform::chown_to_invoker(targetHome);
+
+    std::println("\n[xlings:self] install: {} ({}) - ok", targetHome.string(), pkgVersion);
+    std::println("");
+    std::println("  run 'xlings -h' to get started");
+#if defined(__linux__) || defined(__APPLE__)
+    std::println("  restart shell or: source ~/.bashrc");
+#else
+    std::println("  restart terminal to refresh PATH");
+#endif
+    std::println("");
+    return 0;
+}
+
+}
diff --git a/src/core/xself/install.cppm b/src/core/xself/install.cppm
index 6498393c..c7cbc1d8 100644
--- a/src/core/xself/install.cppm
+++ b/src/core/xself/install.cppm
@@ -4,814 +4,11 @@ import std;
 import xlings.core.xself.init;
 import xlings.core.xself.shell_profile;
 
-import xlings.core.config;
-import xlings.core.xvm.lock;
-import xlings.libs.json;
-import xlings.libs.tinyhttps;
-import xlings.core.log;
-import xlings.platform;
-import xlings.core.utils;
-import xlings.core.version_order;
 
 namespace xlings::xself {
 
 namespace fs = std::filesystem;
 
-static std::string read_version_from_json(const fs::path& homeDir) {
-    auto conf = homeDir / ".xlings.json";
-    if (!fs::exists(conf)) return "";
-    try {
-        auto content = platform::read_file_to_string(conf.string());
-        auto j = nlohmann::json::parse(content, nullptr, false);
-        if (!j.is_discarded() && j.contains("version") && j["version"].is_string()) {
-            auto v = j["version"].get<std::string>();
-            if (v.starts_with("v")) v = v.substr(1);
-            return v;
-        }
-    } catch (...) {}
-    return "";
-}
-
-static std::optional<std::string> normalize_mirror_(std::string mirror) {
-    mirror = utils::trim_string(mirror);
-    std::ranges::transform(mirror, mirror.begin(), [](unsigned char c) {
-        return static_cast<char>(std::toupper(c));
-    });
-    if (mirror == "GLOBAL" || mirror == "CN") return mirror;
-    return std::nullopt;
-}
-
-static std::string read_mirror_from_json_(const fs::path& configPath) {
-    if (!fs::exists(configPath)) return {};
-    try {
-        auto content = platform::read_file_to_string(configPath.string());
-        auto json = nlohmann::json::parse(content, nullptr, false);
-        if (!json.is_discarded() && json.is_object() &&
-            json.contains("mirror") && json["mirror"].is_string()) {
-            if (auto mirror = normalize_mirror_(json["mirror"].get<std::string>()))
-                return *mirror;
-        }
-    } catch (...) {}
-    return {};
-}
-
-static std::optional<std::string> env_install_mirror_() {
-    for (auto name : {"XLINGS_INSTALL_MIRROR", "XLINGS_MIRROR", "XLINGS_RELEASE_MIRROR"}) {
-        if (auto value = utils::get_env_or_default(name); !value.empty()) {
-            if (auto mirror = normalize_mirror_(value)) return mirror;
-        }
-    }
-    return std::nullopt;
-}
-
-static std::string detect_install_mirror_() {
-    if (auto mirror = env_install_mirror_()) return *mirror;
-
-    constexpr int timeoutMs = 1000;
-    constexpr double preferCnDeltaSec = 0.02;  // 20ms
-    auto to_latency_ms_text = [](double sec) {
-        if (!std::isfinite(sec)) return std::string("timeout");
-        auto ms = static_cast<long long>(std::llround(sec * 1000.0));
-        return std::to_string(ms);
-    };
-
-    // Probe the actual RESOURCE host of each mirror — that's what package
-    // downloads (the bulk of install traffic) hit. GLOBAL serves from
-    // github.com, CN from gitcode.com. (Earlier this probed gitee.com — the CN
-    // *index* host — which on some China-mobile / Termux links is throttled even
-    // though gitcode.com is fine, so GLOBAL was wrongly kept and every xim
-    // download then stalled on the unreachable github.)
-    auto globalLatencySec = tinyhttps::probe_latency("https://github.com", timeoutMs);
-    log::println("[xlings:self] https://github.com: {} ms", to_latency_ms_text(globalLatencySec));
-
-    auto cnLatencySec = tinyhttps::probe_latency("https://gitcode.com", timeoutMs);
-    log::println("[xlings:self] https://gitcode.com: {} ms", to_latency_ms_text(cnLatencySec));
-
-    // Pick CN when its resource host is reachable AND GitHub is either
-    // unreachable or meaningfully slower. This makes a github-blocked link
-    // (gitcode reachable) auto-select CN instead of falling back to a dead
-    // GLOBAL.
-    if (std::isfinite(cnLatencySec) &&
-        (!std::isfinite(globalLatencySec) || cnLatencySec + preferCnDeltaSec < globalLatencySec)) {
-        return "CN";
-    }
-    return "GLOBAL";
-}
-
-static void set_mirror_fields_(nlohmann::json& json, const std::string& mirror) {
-    json["mirror"] = mirror;
-    json["xim"]["mirrors"]["index-repo"]["GLOBAL"] =
-        "https://github.com/openxlings/xim-pkgindex.git";
-    json["xim"]["mirrors"]["index-repo"]["CN"] =
-        "https://gitee.com/sunrisepeak/xim-pkgindex.git";
-    json["xim"]["mirrors"]["res-server"]["GLOBAL"] =
-        "https://github.com/xlings-res";
-    json["xim"]["mirrors"]["res-server"]["CN"] =
-        "https://gitcode.com/xlings-res";
-
-    if (mirror == "CN") {
-        json["xim"]["res-server"] = "https://gitcode.com/xlings-res";
-        json["xim"]["index-repo"] = "https://gitee.com/sunrisepeak/xim-pkgindex.git";
-        json["repo"] = "https://gitee.com/sunrisepeak/xlings.git";
-    } else {
-        json["xim"]["res-server"] = "https://github.com/xlings-res";
-        json["xim"]["index-repo"] = "https://github.com/openxlings/xim-pkgindex.git";
-        json["repo"] = "https://github.com/openxlings/xlings.git";
-    }
-}
-
-static void configure_install_mirror_(const fs::path& targetHome,
-                                      const std::string& existingMirror,
-                                      bool overwriteDataSubos) {
-    auto envMirror = env_install_mirror_();
-    if (!envMirror && !overwriteDataSubos && !existingMirror.empty()) {
-        return;
-    }
-
-    auto mirror = envMirror ? *envMirror : detect_install_mirror_();
-    auto configPath = targetHome / ".xlings.json";
-
-    nlohmann::json json = nlohmann::json::object();
-    if (fs::exists(configPath)) {
-        try {
-            auto content = platform::read_file_to_string(configPath.string());
-            auto parsed = nlohmann::json::parse(content, nullptr, false);
-            if (!parsed.is_discarded() && parsed.is_object()) json = std::move(parsed);
-        } catch (...) {}
-    }
-
-    set_mirror_fields_(json, mirror);
-    platform::write_string_to_file(configPath.string(), json.dump(2));
-    log::println("[xlings:self] mirror: {}", mirror);
-}
-
-/// True if path is under a temp dir (e.g. /tmp, $TMPDIR, $TEMP, $RUNNER_TEMP). Used to detect
-/// quick_install extract dir — we must install to ~/.xlings, not "fix links" in place.
-static bool is_under_temp_dir(const fs::path& p) {
-    auto s = p.generic_string();  // forward slashes for portable comparison
-    // quick_install uses "xlings-install" in temp dir name — definitive indicator
-    if (s.find("xlings-install") != std::string::npos) return true;
-    if (s.find("/tmp/") == 0 || s.find("/tmp") == 0) return true;
-#if defined(__APPLE__)
-    // macOS: /var/folders/... is system temp; canonical paths may use /private/var
-    if (s.find("/var/folders/") != std::string::npos ||
-        s.find("/private/var/folders/") != std::string::npos)
-        return true;
-#endif
-#if defined(_WIN32)
-    // Windows: match path segments /Temp/ or /Tmp/ (GetTempPath uses these)
-    if (s.find("/Temp/") != std::string::npos || s.find("/Tmp/") != std::string::npos ||
-        s.find("/temp/") != std::string::npos || s.find("/tmp/") != std::string::npos)
-        return true;
-#endif
-    for (const char* env : {"TMPDIR", "TEMP", "TMP", "RUNNER_TEMP"}) {
-        if (const char* v = std::getenv(env)) {
-            auto prefix = fs::path(v).generic_string();
-            if (prefix.empty()) continue;
-            auto prefixSlash = prefix;
-            if (prefixSlash.back() != '/') prefixSlash += '/';
-            if (s.starts_with(prefixSlash) || s == prefix) return true;
-#if defined(__APPLE__)
-            // macOS: /var resolves to /private/var; canonical paths may have /private prefix
-            if (prefix.starts_with("/var/") && s.starts_with("/private" + prefixSlash))
-                return true;
-#endif
-        }
-    }
-    return false;
-}
-
-static fs::path detect_source_dir() {
-    // Check CWD first: on Windows/PowerShell, `xlings` resolves to the PATH-installed
-    // binary even when the user is inside a new release package directory.
-    std::error_code ec;
-    auto cwd = fs::current_path(ec);
-    if (!ec && !cwd.empty() && is_bootstrap_home_root(cwd)) {
-        return fs::weakly_canonical(cwd);
-    }
-
-    auto exe = platform::get_executable_path();
-    if (exe.empty()) return {};
-    auto binDir = exe.parent_path();
-    auto candidate = binDir.parent_path();
-    log::debug("[xlings:self]: candidate: {}", candidate.string());
-    if (is_bootstrap_home_root(candidate)) {
-        return fs::weakly_canonical(candidate);
-    }
-    return {};
-}
-
-static fs::path detect_existing_home() {
-    auto envHome = utils::get_env_or_default("XLINGS_HOME");
-    if (!envHome.empty()) {
-        auto p = fs::path(envHome);
-        // An explicit target is authoritative even for the first install.
-        // PATH discovery is only a convenience when the caller did not name
-        // a destination; otherwise an unrelated older xlings can hijack a
-        // cold-home bootstrap.
-        std::error_code ec;
-        auto absolute = fs::absolute(p, ec);
-        if (ec) return p.lexically_normal();
-        if (fs::exists(absolute, ec)) {
-            auto canonical = fs::weakly_canonical(absolute, ec);
-            return ec ? absolute.lexically_normal() : canonical;
-        }
-        return absolute.lexically_normal();
-    }
-    auto [rc, out] = platform::run_command_capture(
-#ifdef _WIN32
-        "where xlings 2>nul"
-#else
-        "command -v xlings 2>/dev/null"
-#endif
-    );
-    (void)rc;
-    // "where"/"command -v" may return multiple lines; use first valid path
-    auto lines = utils::split_string(out, '\n');
-    for (const auto& line : lines) {
-        auto binPath = utils::trim_string(line);
-        if (binPath.empty() || !fs::exists(binPath)) continue;
-        auto p = fs::weakly_canonical(fs::path(binPath));
-        // Walk upward from the executable directory and locate install root by markers.
-        // Note: path("/").parent_path() returns "/" on Unix (root's parent is itself) — must check to avoid infinite loop.
-        for (auto cur = p.parent_path(); cur != cur.parent_path(); cur = cur.parent_path()) {
-            if (!fs::exists(cur / "bin") || !fs::exists(cur / "subos")) continue;
-            // Ignore temp extract dir (quick_install) — install to ~/.xlings instead.
-            if (!is_under_temp_dir(cur))
-                return cur;
-            break;
-        }
-    }
-    return {};
-}
-
-static fs::path default_home() {
-    return fs::path(platform::get_home_dir()) / ".xlings";
-}
-
-static void copy_directory_contents(const fs::path& src, const fs::path& dst) {
-    std::error_code ec;
-    fs::create_directories(dst, ec);
-    for (auto& entry : platform::dir_entries(src)) {
-        auto target = dst / entry.path().filename();
-        if (entry.is_directory()) {
-            fs::copy(entry.path(), target,
-                     fs::copy_options::recursive | fs::copy_options::overwrite_existing, ec);
-        } else {
-            fs::copy_file(entry.path(), target,
-                          fs::copy_options::overwrite_existing, ec);
-        }
-        if (ec) {
-            log::error("[xlings:self] copy failed: {} -> {} ({})",
-                       entry.path().string(), target.string(), ec.message());
-            ec.clear();
-        }
-    }
-}
-
-static void setup_shell_profiles(const fs::path& homeDir) {
-#if defined(__linux__) || defined(__APPLE__)
-    auto profileSh   = homeDir / "config" / "shell" / "xlings-profile.sh";
-    auto profileFish = homeDir / "config" / "shell" / "xlings-profile.fish";
-
-    auto sourceLine = "test -f \"" + profileSh.string() + "\" && source \"" + profileSh.string() + "\"";
-
-    // rc files belong to the INVOKING user. Under `sudo` this is the real
-    // user's home (not root's $HOME), so the person who ran the install
-    // actually gets xlings on their PATH. Identical to get_home_dir() when
-    // not running via sudo, so non-sudo behavior is unchanged.
-    fs::path rcHome(platform::target_home());
-
-    std::vector<fs::path> profiles;
-#if defined(__APPLE__)
-    profiles = {
-        rcHome / ".zshrc",
-        rcHome / ".bashrc",
-        rcHome / ".zprofile",
-    };
-#else
-    profiles = {
-        rcHome / ".bashrc",
-        rcHome / ".zshrc",
-        rcHome / ".profile",
-    };
-#endif
-
-    bool added = false;
-    for (auto& prof : profiles) {
-        if (!fs::exists(prof)) continue;
-        auto content = platform::read_file_to_string(prof.string());
-        if (content.find("xlings-profile") != std::string::npos) {
-            log::debug("[xlings:self] profile ok ({})", prof.filename().string());
-            added = true;
-            break;
-        }
-        std::string appendStr = "\n# xlings\n" + sourceLine + "\n";
-        platform::write_string_to_file(prof.string(), content + appendStr);
-        // If we ran via sudo, hand the rc file back to its real owner.
-        platform::chown_to_invoker(prof, /*recursive=*/false);
-        log::println("[xlings:self] added profile ({})", prof.filename().string());
-        added = true;
-        break;
-    }
-
-    auto fishConfig = rcHome / ".config" / "fish" / "config.fish";
-    auto fishSourceLine = "test -f \"" + profileFish.string() + "\"; and source \"" + profileFish.string() + "\"";
-    if (fs::exists(fishConfig) ||
-        platform::run_command_capture("command -v fish 2>/dev/null").first == 0) {
-        fs::create_directories(fishConfig.parent_path());
-        std::string fishContent;
-        if (fs::exists(fishConfig))
-            fishContent = platform::read_file_to_string(fishConfig.string());
-        if (fishContent.find("xlings-profile") == std::string::npos) {
-            platform::write_string_to_file(fishConfig.string(),
-                                           fishContent + "\n# xlings\n" + fishSourceLine + "\n");
-            log::println("[xlings:self] added profile (config.fish)");
-        } else {
-            log::debug("[xlings:self] profile ok (fish)");
-        }
-        // Restore ownership of the fish config tree we may have created.
-        platform::chown_to_invoker(rcHome / ".config" / "fish");
-        added = true;
-    }
-
-    if (!added) {
-        // No existing shell rc — e.g. a fresh Termux / minimal container, where
-        // ~/.bashrc isn't created until the user edits it. Rather than dump a
-        // manual step (which breaks the zero-config promise: the very next
-        // command `xlings` would be "command not found"), create the default rc
-        // ourselves so xlings lands on PATH on first login.
-        //
-        // Best-effort: only when the home dir actually exists and the write
-        // succeeds. A throwing write (e.g. simulated-sudo to a non-existent
-        // home) must NOT abort `self install` — fall back to the manual hint.
-        bool created = false;
-        auto prof = rcHome / ".bashrc";
-        std::error_code ec;
-        if (fs::exists(rcHome, ec) && !ec) {
-            try {
-                std::string content;
-                if (fs::exists(prof)) content = platform::read_file_to_string(prof.string());
-                platform::write_string_to_file(prof.string(),
-                                               content + "\n# xlings\n" + sourceLine + "\n");
-                platform::chown_to_invoker(prof, /*recursive=*/false);
-                created = true;
-            } catch (const std::exception& e) {
-                log::debug("[xlings:self] could not create {}: {}", prof.string(), e.what());
-            }
-        }
-        if (created) {
-            log::println("[xlings:self] created profile ({})", prof.filename().string());
-            log::println("[xlings:self] open a new shell or: source \"{}\"", profileSh.string());
-        } else {
-            std::println("[xlings:self] no shell profile found, add manually:");
-            std::println("  {}", sourceLine);
-        }
-    }
-#elif defined(_WIN32)
-    auto xlingsBin = homeDir / "subos" / "current" / "bin";
-    std::string setHomeCmd = "powershell -NoProfile -Command \""
-        "[System.Environment]::SetEnvironmentVariable('XLINGS_HOME','"
-        + homeDir.string() + "','User');"
-        "Write-Host 'XLINGS_HOME updated'\"";
-    platform::exec(setHomeCmd);
-
-    std::string checkCmd = "powershell -NoProfile -Command \""
-        "$p=[System.Environment]::GetEnvironmentVariable('Path','User');"
-        "if($p -notlike '*" + xlingsBin.string() + "*'){"
-        "[System.Environment]::SetEnvironmentVariable('Path','"
-        + xlingsBin.string() + ";'+$p,'User');"
-        "Write-Host 'PATH updated'"
-        "}else{Write-Host 'PATH already set'}\"";
-    platform::exec(checkCmd);
-
-    // Hook every PowerShell host on the box, not just the one xlings happens
-    // to shell out to. Windows PowerShell 5.1 and PowerShell 7+ read different
-    // startup files, and `xlings subos use` spawns pwsh.exe first -- so the
-    // 5.1-only hook this used to be left the shell xlings itself launches
-    // without XLINGS_BIN on PATH (#387). Policy and mechanics live in
-    // xlings.core.xself.shell_profile, which is unit-tested; what stays here
-    // is the process spawning and the reporting.
-    auto profilePs1 = homeDir / "config" / "shell" / "xlings-profile.ps1";
-    auto snippet = shell_profile::powershell_snippet(profilePs1);
-
-    auto probes = shell_profile::probe_hosts(
-        shell_profile::kPowerShellHosts,
-        [](const std::string& cmd) {
-            auto result = platform::run_command_capture(cmd);
-            log::debug("[xlings:self] probe: {} -> rc={} out={}",
-                       cmd, result.first, result.second);
-            return result;
-        });
-
-    int hooked = 0;
-    for (const auto& p : probes) {
-        if (p.status == shell_profile::ProbeStatus::NotInstalled) {
-            // The ordinary shape of a machine without PowerShell 7. Not news.
-            log::debug("[xlings:self] {} not installed", p.host);
-            continue;
-        }
-        if (p.status == shell_profile::ProbeStatus::Unusable) {
-            // It started and said something we cannot hook. That is a defect,
-            // not a machine shape, so it is shown with what it actually said.
-            log::warn("[xlings:self] {} did not report $PROFILE: {}",
-                      p.host, p.output);
-            continue;
-        }
-        switch (shell_profile::hook(p.path, snippet)) {
-        case shell_profile::HookResult::Added:
-            ++hooked;
-            log::println("[xlings:self] added profile ({})", p.host);
-            log::debug("[xlings:self]   {}", p.path.string());
-            break;
-        case shell_profile::HookResult::AlreadyHooked:
-            ++hooked;
-            log::debug("[xlings:self] profile ok ({})", p.host);
-            break;
-        case shell_profile::HookResult::Failed:
-            // Reported rather than swallowed: the old one-liner discarded its
-            // exit code, so a profile that was never written looked exactly
-            // like one that was.
-            log::warn("[xlings:self] could not write {} profile: {}",
-                      p.host, p.path.string());
-            break;
-        }
-    }
-
-    if (hooked == 0) {
-        std::println("[xlings:self] no PowerShell host was configured, add manually to $PROFILE:");
-        std::println("  {}", snippet);
-    }
-#endif
-}
-
-// Advise when running as root, distinguishing the two failure-prone cases:
-// pure root (files land in /root/.xlings, invisible to normal users) vs sudo
-// (we redirect rc files + chown ~/.xlings back to the real user). No-op for
-// the ordinary non-root install, so existing behavior is untouched.
-static void warn_root_context_() {
-    // Cross-platform by construction: is_root() is false on Windows (and for
-    // any non-root POSIX run), so this returns immediately and adds no
-    // behavior off the root path — no platform macro needed.
-    if (!platform::is_root()) return;
-    if (auto inv = platform::sudo_invoker()) {
-        log::warn("[xlings:self] running via sudo (user '{}')", inv->user);
-        log::warn("  rc files target {}'s home; ~/.xlings is chowned back to it",
-                  inv->user.empty() ? "the invoking user" : inv->user.c_str());
-        log::warn("  tip: xlings is user-space — running without sudo also works");
-    } else {
-        log::warn("[xlings:self] running as root — installing to root's home");
-        log::warn("  this install is only on root's PATH; normal users won't see it");
-    }
-}
-
-// `XLINGS_HOME` as the CALLER set it, canonicalized the same way
-// detect_existing_home does, so the two can be compared without a spurious
-// mismatch from a trailing slash or a symlinked prefix. Empty when the caller
-// did not name one.
-//
-// xlings::ambient_home_env(), NOT getenv: main.cpp exports XLINGS_HOME to the
-// home it resolved before any command runs, so getenv here answers "what did
-// xlings decide" and never "what did the user ask for". Reading it was a
-// second answerer to a question that already had one -- and it made this guard
-// refuse a caller who had explicitly passed `env -u XLINGS_HOME`.
-static fs::path explicit_home_() {
-    const auto& ambient = xlings::ambient_home_env();
-    if (!ambient) return {};
-    const auto& envHome = *ambient;
-    if (envHome.empty()) return {};
-    std::error_code ec;
-    auto absolute = fs::absolute(fs::path(envHome), ec);
-    if (ec) return fs::path(envHome).lexically_normal();
-    auto canonical = fs::weakly_canonical(absolute, ec);
-    return ec ? absolute.lexically_normal() : canonical;
-}
-
-// Do these two paths name the same directory?
-//
-// `fs::equivalent` FIRST, and only then string comparison. Comparing
-// canonicalized strings is wrong on Windows, where the filesystem is
-// case-insensitive and `weakly_canonical` does not fold case: `c:\users\me`
-// and `C:\Users\Me` are one directory and two strings. This guard REFUSES on
-// a difference, so a false difference is a refused install -- the failure mode
-// is louder than the one it was added to prevent.
-//
-// `equivalent` needs both to exist, which is exactly when the question is
-// answerable; when one does not, a normalized string compare is all there is,
-// and a non-existent target cannot be the home someone is worried about
-// overwriting anyway.
-static bool same_dir_(const fs::path& a, const fs::path& b) {
-    if (a.empty() || b.empty()) return false;
-    std::error_code ec;
-    if (fs::exists(a, ec) && fs::exists(b, ec)) {
-        std::error_code eqEc;
-        if (bool eq = fs::equivalent(a, b, eqEc); !eqEc) return eq;
-    }
-    ec.clear();
-    auto ca = fs::weakly_canonical(a, ec);
-    auto cb = fs::weakly_canonical(b, ec);
-    if (ec) return a.lexically_normal() == b.lexically_normal();
-    return ca == cb;
-}
-
-export int cmd_install() {
-    warn_root_context_();
-    auto srcDir = detect_source_dir();
-    if (srcDir.empty()) {
-        log::error("[xlings:self] cannot detect source package directory.");
-        log::error("  run this command from inside a valid xlings release package");
-        return 1;
-    }
-
-    auto pkgVersion = read_version_from_json(srcDir);
-    if (pkgVersion.empty()) pkgVersion = std::string(Info::VERSION);
-    auto existingHome = detect_existing_home();
-    auto targetHome = existingHome.empty() ? default_home() : existingHome;
-    auto installedVersion = read_version_from_json(targetHome);
-
-    // When running from a temp extract (quick_install), install to ~/.xlings — temp dir will be deleted.
-    std::error_code cmp_ec;
-    bool sameDir = fs::equivalent(srcDir, targetHome, cmp_ec);
-    bool fromTempExtract = false;
-    fs::path existingPath = targetHome;  // path of existing install (may differ from target)
-    if (!cmp_ec && sameDir && is_under_temp_dir(srcDir)) {
-        targetHome = default_home();
-        installedVersion = read_version_from_json(targetHome);
-        existingPath = targetHome;
-        fromTempExtract = true;  // no TTY in CI, skip prompts, always proceed
-    }
-    if (!cmp_ec && sameDir && !fromTempExtract) {
-        auto fallbackHome = default_home();
-        std::error_code homeEc;
-        bool sourceIsDefaultHome = fs::equivalent(srcDir, fallbackHome, homeEc);
-        if (homeEc || !sourceIsDefaultHome) {
-            targetHome = fallbackHome;
-            installedVersion = read_version_from_json(targetHome);
-            existingPath = targetHome;
-            cmp_ec.clear();
-            sameDir = false;
-        }
-    }
-    auto existingMirror = read_mirror_from_json_(targetHome / ".xlings.json");
-
-    // Install header: show existing (if any) and install target; paths may differ
-    std::println("\n[xlings:self] install");
-    if (!installedVersion.empty()) {
-        std::println("  existing: v{} -> {}", installedVersion, existingPath.string());
-    }
-    std::println("  install:  v{} -> {}", pkgVersion, targetHome.string());
-
-    // An explicit XLINGS_HOME that this command is NOT going to honour.
-    //
-    // XLINGS_HOME is honoured in the ordinary case -- detect_existing_home
-    // takes it as authoritative -- but the two `sameDir` branches above
-    // silently retarget to `$HOME/.xlings`, and silently is the problem. The
-    // rest of this repository isolates by XLINGS_HOME, so a verification step
-    // that sets it and then watches this command write somewhere else is
-    // writing into a home it believed it had ruled out.
-    //
-    // REFUSE, do not retarget-and-warn. A warning scrolls past under the
-    // progress output (measured: the header above was already invisible in a
-    // real run), and by the time anyone reads it the home has been
-    // overwritten. Non-zero exit with the two paths named is recoverable; a
-    // warning is not.
-    //
-    // Only when they DISAGREE -- so the ordinary install, and every install
-    // that does not set XLINGS_HOME, is untouched.
-    if (auto envHome = explicit_home_();
-        !envHome.empty() && !same_dir_(envHome, targetHome)) {
-        log::error("[xlings:self] XLINGS_HOME and the install target disagree");
-        log::error("  XLINGS_HOME: {}", envHome.string());
-        log::error("  would write: {}", targetHome.string());
-        log::error("  refusing, because the rest of xlings isolates by "
-                   "XLINGS_HOME and this command would not have");
-        log::error("  hint: to install into XLINGS_HOME, run it from outside "
-                   "that directory; to install into the target above, unset "
-                   "XLINGS_HOME");
-        return 1;
-    }
-
-    // Skip if source == target and not temp — "fix links" in place (e.g. dev from source).
-    if (!cmp_ec && sameDir && !fromTempExtract) {
-        log::println("\n[xlings:self] already in target dir, fixing links");
-        auto lock = xvm::acquire_state_lock(targetHome);
-        if (!lock) {
-            log::error("[xlings:self] {}", lock.error());
-            return 1;
-        }
-        if (!ensure_home_layout(targetHome)) {
-            log::error("[xlings:self] failed to initialize {}", targetHome.string());
-            return 1;
-        }
-        setup_shell_profiles(targetHome);
-        platform::chown_to_invoker(targetHome);
-        log::println("[xlings:self] {} ({}) - ok\n", targetHome.string(), pkgVersion);
-        return 0;
-    }
-
-    // Version / overwrite confirmation (skip when from temp extract — CI / quick_install)
-    bool overwriteDataSubos = false;
-    if (!fromTempExtract) {
-        if (!pkgVersion.empty() && !installedVersion.empty() && pkgVersion == installedVersion) {
-            if (!utils::ask_yes_no("\n[xlings:self] same version installed, reinstall? ", false)) {
-                std::println("[xlings:self] cancelled\n");
-                return 0;
-            }
-            if (fs::exists(targetHome / "data") || fs::exists(targetHome / "subos")) {
-                overwriteDataSubos = utils::ask_yes_no("[xlings:self] overwrite data and subos? ", false);
-            }
-        } else if (fs::exists(targetHome / "bin") && fs::exists(targetHome / "subos")) {
-            // Name both versions, and say which DIRECTION this is.
-            //
-            // The prompt used to read "overwrite existing installation?" with
-            // a default of yes, and an upgrade and a six-week downgrade were
-            // worded identically. That is how a June payload's `self install`
-            // replaced a current entry binary on this machine: the entry then
-            // predated `${XLINGS_DYNAMIC_SUBOS_DIR}`, so every alias in the
-            // home lost its expansion and the first visible symptom was a
-            // toolchain that could not find crt1.o.
-            //
-            // Note the old default was INVERTED against the risk: reinstalling
-            // the same version defaulted to NO, while going backwards
-            // defaulted to YES. Going backwards is the one that needs the
-            // deliberate keystroke.
-            const bool downgrade =
-                !pkgVersion.empty() && !installedVersion.empty()
-                && version_order::compare(pkgVersion, installedVersion) < 0;
-            std::string question;
-            if (installedVersion.empty()) {
-                question = "\n[xlings:self] overwrite existing installation? ";
-            } else if (downgrade) {
-                question = std::format(
-                    "\n[xlings:self] DOWNGRADE v{} -> v{}, overwrite? ",
-                    installedVersion, pkgVersion);
-            } else {
-                question = std::format(
-                    "\n[xlings:self] replace v{} with v{}? ",
-                    installedVersion, pkgVersion);
-            }
-            if (!utils::ask_yes_no(question, !downgrade)) {
-                std::println("[xlings:self] cancelled\n");
-                return 0;
-            }
-        }
-    }
-
-    // Everything past this point rewrites the home: the binary, the layout,
-    // and three separate read-modify-writes of `.xlings.json` (mirror,
-    // version, subos defaults). An install running in another terminal reads
-    // and writes the same file, so hold the home-wide state lock across the
-    // lot -- one lock rather than three, since the writes are interleaved
-    // with the tree replacement and only the whole sequence is meaningful.
-    //
-    // Taken here rather than at the top of the function on purpose: the
-    // confirmation prompts above would otherwise hold the lock for as long as
-    // the user takes to answer, and a lock held on human time is a lock that
-    // makes `xlings install` fail in the next terminal over.
-    //
-    // The patchelf-runtime-dep step below spawns `xlings install -g`. That
-    // child inherits the re-entrancy marker (xvm/lock.cppm) and works under
-    // this lock instead of waiting for one this process cannot release until
-    // the child returns.
-    auto stateLock = xvm::acquire_state_lock(targetHome);
-    if (!stateLock) {
-        log::error("[xlings:self] {}", stateLock.error());
-        return 1;
-    }
-
-    // Selective install: preserve data/ and subos/ unless user chose to overwrite
-    log::println("[xlings:self] copying binaries and config ...");
-    fs::create_directories(targetHome);
-
-    std::error_code ec;
-
-    // 1. Remove non-user dirs; preserve data/subos and .xlings.json unless user chose overwrite
-    if (fs::exists(targetHome)) {
-        for (auto& entry : platform::dir_entries(targetHome)) {
-            auto name = entry.path().filename().string();
-            if (name == "data" || name == "subos") {
-                if (!overwriteDataSubos) continue;
-            }
-            // Preserve .xlings.json — it contains the xvm versions DB and user config.
-            // We merge the new version into it after copying (step 2).
-            if (name == ".xlings.json" && !overwriteDataSubos) continue;
-            fs::remove_all(entry.path(), ec);
-            ec.clear();
-        }
-    }
-
-    // 2. Copy from release, skip data/subos when target already has them; merge subos static parts if exists
-    for (auto& entry : platform::dir_entries(srcDir)) {
-        auto name = entry.path().filename().string();
-        if (name == "data") {
-            if (fs::exists(targetHome / "data") && fs::is_directory(targetHome / "data"))
-                continue;
-        }
-        if (name == "subos") {
-            if (fs::exists(targetHome / "subos") && fs::is_directory(targetHome / "subos")) {
-                continue;  // 已有 subos 则完全保留，不合并（多 subos 且 bin 等无需覆盖）
-            }
-        }
-        // Skip .xlings.json when preserved — we update version below
-        if (name == ".xlings.json" && !overwriteDataSubos && fs::exists(targetHome / name)) {
-            continue;
-        }
-        auto target = targetHome / name;
-        if (entry.is_directory()) {
-            fs::copy(entry.path(), target,
-                     fs::copy_options::recursive | fs::copy_options::overwrite_existing, ec);
-        } else {
-            fs::copy_file(entry.path(), target, fs::copy_options::overwrite_existing, ec);
-        }
-        if (ec) {
-            log::error("[xlings:self] copy failed: {} -> {} ({})",
-                       entry.path().string(), target.string(), ec.message());
-            ec.clear();
-        }
-    }
-
-    // 2b. Update version in preserved .xlings.json
-    {
-        auto configPath = targetHome / ".xlings.json";
-        if (fs::exists(configPath) && !pkgVersion.empty()) {
-            try {
-                auto content = platform::read_file_to_string(configPath.string());
-                auto json = nlohmann::json::parse(content, nullptr, false);
-                if (!json.is_discarded() && json.is_object()) {
-                    json["version"] = "v" + pkgVersion;
-                    platform::write_string_to_file(configPath.string(), json.dump(2));
-                }
-            } catch (...) {}
-        }
-    }
-    configure_install_mirror_(targetHome, existingMirror, overwriteDataSubos);
-
-    // 3. First install: preserve extra trees if the source package still ships them.
-    if (!fs::exists(targetHome / "data") && fs::exists(srcDir / "data")) {
-        copy_directory_contents(srcDir / "data", targetHome / "data");
-    }
-    if (!fs::exists(targetHome / "subos") && fs::exists(srcDir / "subos")) {
-        copy_directory_contents(srcDir / "subos", targetHome / "subos");
-    }
-    if (!fs::exists(targetHome / "config") && fs::exists(srcDir / "config")) {
-        copy_directory_contents(srcDir / "config", targetHome / "config");
-    }
-
-    // 4. Fix permissions (platform-dispatched)
-    platform::make_files_executable(targetHome / "bin");
-
-    // 5. Materialize a complete home layout even if the source package is minimal.
-    if (!ensure_home_layout(targetHome)) {
-        log::error("[xlings:self] failed to initialize {}", targetHome.string());
-        return 1;
-    }
-
-    setup_shell_profiles(targetHome);
-
-    auto verifyBin = targetHome / "bin" /
-#ifdef _WIN32
-        "xlings.exe";
-#else
-        "xlings";
-#endif
-    if (fs::exists(verifyBin)) {
-        auto [rc, out] = platform::run_command_capture(
-            "\"" + verifyBin.string() + "\" -h");
-        if (rc != 0)
-            log::warn("[xlings:self] verification failed");
-    }
-
-#if defined(__linux__)
-    if (fs::exists(verifyBin)) {
-        platform::set_env_variable("XLINGS_HOME", targetHome.string());
-        auto binDir = (targetHome / "subos" / "current" / "bin").string();
-        auto existingPath = std::string(std::getenv("PATH") ? std::getenv("PATH") : "");
-        platform::set_env_variable("PATH", binDir + platform::PATH_SEPARATOR + existingPath);
-
-        log::println("[xlings:self] installing patchelf (runtime dependency) ...");
-        auto rc = platform::exec("xlings install xim:patchelf@0.18.0 -y -g");
-        if (rc != 0) {
-            log::warn("[xlings:self] patchelf install failed (rc={})", rc);
-            log::warn("  hint: run manually: xlings install xim:patchelf@0.18.0 -y");
-        }
-    }
-#endif
-
-    // Hand the freshly-written ~/.xlings back to the invoking user when we
-    // ran via sudo, so a later non-sudo `xlings install` isn't locked out by
-    // root-owned files. No-op for pure root / non-root installs.
-    platform::chown_to_invoker(targetHome);
-
-    std::println("\n[xlings:self] install: {} ({}) - ok", targetHome.string(), pkgVersion);
-    std::println("");
-    std::println("  run 'xlings -h' to get started");
-#if defined(__linux__) || defined(__APPLE__)
-    std::println("  restart shell or: source ~/.bashrc");
-#else
-    std::println("  restart terminal to refresh PATH");
-#endif
-    std::println("");
-    return 0;
-}
+export int cmd_install();
 
 } // namespace xlings::xself
diff --git a/src/core/xself/migrate.cpp b/src/core/xself/migrate.cpp
new file mode 100644
index 00000000..9cd2ef3b
--- /dev/null
+++ b/src/core/xself/migrate.cpp
@@ -0,0 +1,84 @@
+module xlings.core.xself.migrate;
+
+import std;
+import xlings.core.config;
+import xlings.core.home_config;
+import xlings.libs.json;
+import xlings.core.log;
+import xlings.platform;
+
+namespace xlings::xself {
+
+int cmd_migrate() {
+    namespace fs = std::filesystem;
+    auto& p = Config::paths();
+    auto subosDir   = p.homeDir / "subos";
+    auto defaultDir = subosDir / "default";
+
+    if (fs::exists(defaultDir / "bin")) {
+        log::info("already migrated (subos/default/bin exists)");
+        return 0;
+    }
+
+    fs::create_directories(defaultDir);
+
+    auto oldDataDir = p.homeDir / "data";
+    bool moved = false;
+
+    auto move_if_exists = [&](const std::string& name) {
+        auto src = oldDataDir / name;
+        auto dst = defaultDir / name;
+        if (fs::exists(src)) {
+            std::error_code ec;
+            fs::rename(src, dst, ec);
+            if (ec) {
+                fs::copy(src, dst, fs::copy_options::recursive | fs::copy_options::overwrite_existing, ec);
+                if (ec) {
+                    log::error("failed to move {}: {}", name, ec.message());
+                    return;
+                }
+                fs::remove_all(src, ec);
+            }
+            log::info("migrated data/{} -> subos/default/{}", name, name);
+            moved = true;
+        }
+    };
+
+    move_if_exists("bin");
+    move_if_exists("lib");
+    move_if_exists("xvm");
+
+    fs::create_directories(defaultDir / "usr");
+    fs::create_directories(defaultDir / "generations");
+
+    // The data-tree move above is the slow part; commit the config edit
+    // afterwards under the state lock rather than rewriting a document read
+    // before it. See core/home_config.cppm.
+    auto committed = update_home_config(p.homeDir, [](nlohmann::json& json) {
+        json["activeSubos"] = "default";
+        if (!json.contains("subos") || !json["subos"].is_object()) {
+            json["subos"] = nlohmann::json::object();
+        }
+        json["subos"]["default"] = {{"dir", ""}};
+        return true;
+    });
+    if (!committed) {
+        log::error("migration moved the data tree but could not update "
+                   "the config: {}", committed.error());
+        return 1;
+    }
+
+    auto currentLink = subosDir / "current";
+    std::error_code lec;
+    fs::remove(currentLink, lec);
+    fs::create_directory_symlink(defaultDir, currentLink, lec);
+
+    if (moved) {
+        log::info("migration complete");
+    } else {
+        log::info("no legacy data found; initialized subos/default");
+    }
+    return 0;
+}
+
+}
diff --git a/src/core/xself/migrate.cppm b/src/core/xself/migrate.cppm
index 81576f5a..cdec280f 100644
--- a/src/core/xself/migrate.cppm
+++ b/src/core/xself/migrate.cppm
@@ -2,86 +2,11 @@ export module xlings.core.xself.migrate;
 
 import std;
 
-import xlings.core.config;
-import xlings.core.home_config;
-import xlings.libs.json;
-import xlings.core.log;
-import xlings.platform;
 
 namespace xlings::xself {
 
 // `xlings self migrate` — one-shot migration of the legacy `data/` layout
 // to `subos/default/`. Idempotent: a no-op once `subos/default/bin` exists.
-export int cmd_migrate() {
-    namespace fs = std::filesystem;
-    auto& p = Config::paths();
-    auto subosDir   = p.homeDir / "subos";
-    auto defaultDir = subosDir / "default";
-
-    if (fs::exists(defaultDir / "bin")) {
-        log::info("already migrated (subos/default/bin exists)");
-        return 0;
-    }
-
-    fs::create_directories(defaultDir);
-
-    auto oldDataDir = p.homeDir / "data";
-    bool moved = false;
-
-    auto move_if_exists = [&](const std::string& name) {
-        auto src = oldDataDir / name;
-        auto dst = defaultDir / name;
-        if (fs::exists(src)) {
-            std::error_code ec;
-            fs::rename(src, dst, ec);
-            if (ec) {
-                fs::copy(src, dst, fs::copy_options::recursive | fs::copy_options::overwrite_existing, ec);
-                if (ec) {
-                    log::error("failed to move {}: {}", name, ec.message());
-                    return;
-                }
-                fs::remove_all(src, ec);
-            }
-            log::info("migrated data/{} -> subos/default/{}", name, name);
-            moved = true;
-        }
-    };
-
-    move_if_exists("bin");
-    move_if_exists("lib");
-    move_if_exists("xvm");
-
-    fs::create_directories(defaultDir / "usr");
-    fs::create_directories(defaultDir / "generations");
-
-    // The data-tree move above is the slow part; commit the config edit
-    // afterwards under the state lock rather than rewriting a document read
-    // before it. See core/home_config.cppm.
-    auto committed = update_home_config(p.homeDir, [](nlohmann::json& json) {
-        json["activeSubos"] = "default";
-        if (!json.contains("subos") || !json["subos"].is_object()) {
-            json["subos"] = nlohmann::json::object();
-        }
-        json["subos"]["default"] = {{"dir", ""}};
-        return true;
-    });
-    if (!committed) {
-        log::error("migration moved the data tree but could not update "
-                   "the config: {}", committed.error());
-        return 1;
-    }
-
-    auto currentLink = subosDir / "current";
-    std::error_code lec;
-    fs::remove(currentLink, lec);
-    fs::create_directory_symlink(defaultDir, currentLink, lec);
-
-    if (moved) {
-        log::info("migration complete");
-    } else {
-        log::info("no legacy data found; initialized subos/default");
-    }
-    return 0;
-}
+export int cmd_migrate();
 
 } // namespace xlings::xself
diff --git a/src/core/xself/repair.cpp b/src/core/xself/repair.cpp
new file mode 100644
index 00000000..6fd737e0
--- /dev/null
+++ b/src/core/xself/repair.cpp
@@ -0,0 +1,150 @@
+module xlings.core.xself.repair;
+
+import std;
+import xlings.core.log;
+import xlings.platform;
+
+namespace xlings::xself {
+
+bool is_shell_safe_token(std::string_view s) {
+    if (s.empty()) return false;
+    if (s.front() == '-') return false;  // would be read as an option
+    return std::ranges::all_of(s, [](unsigned char c) {
+        return std::isalnum(c) || c == '.' || c == '-' || c == '_'
+            || c == '+' || c == ':' || c == '@' || c == '/';
+    });
+}
+
+std::string quiet_suffix() {
+#if defined(_WIN32)
+    return " >NUL 2>&1";
+#else
+    return " >/dev/null 2>&1";
+#endif
+}
+
+bool probe_reinstallable(const std::string& target, const std::string& version, const CommandRunner& run, const std::string& client) {
+    if (!is_shell_safe_token(target) || !is_shell_safe_token(version)) {
+        return false;
+    }
+    return run(std::format("{} info {}@{}{}",
+                           client, target, version, quiet_suffix())) == 0;
+}
+
+std::optional<std::string> migration_hint(std::string_view recorded,
+                                          std::string_view running) {
+    auto strip_v = [](std::string_view s) {
+        return (!s.empty() && (s.front() == 'v' || s.front() == 'V'))
+            ? s.substr(1) : s;
+    };
+    const auto a = strip_v(recorded);
+    const auto b = strip_v(running);
+    // An absent record is not a mismatch. A home too old to carry the field
+    // at all, or one written by a build that never set it, would otherwise
+    // nag forever with nothing to compare against.
+    if (a.empty() || b.empty() || a == b) return std::nullopt;
+    return std::format(
+        "this home was set up by {}; packages installed then may still be "
+        "registered in its format\n  run  xlings self doctor --fix", a);
+}
+
+RepairResult repair_one(const RepairTask& task, const RepairPolicy& policy, const CommandRunner& run, const RemovalVerifier& removalDone) {
+    const auto coordinate = task.coordinate.empty()
+        ? std::format("{}@{}", task.target, task.version)
+        : task.coordinate;
+    if (task.coordinate.empty()
+        ? (!is_shell_safe_token(task.target)
+           || !is_shell_safe_token(task.version))
+        : !is_shell_safe_token(task.coordinate)) {
+        return {false, "none",
+                "refusing to repair: the recorded name or version contains "
+                "characters that are not safe to pass to a shell"};
+    }
+    if (!policy.allowNetwork) {
+        return {false, "none", "skipped: repairs that may reach the network "
+                               "are disabled for this pass"};
+    }
+
+    const auto install = std::format("{} install {} -y",
+                                     policy.client, coordinate);
+    const auto remove  = std::format("{} remove {} -y",
+                                     policy.client, coordinate);
+
+    // R2
+    if (run(install) == 0) return {true, "re-register", {}};
+
+    // R3
+    if (!policy.allowReinstall) {
+        return {false, "none",
+                "re-register failed; reinstall was not permitted"};
+    }
+    if (!task.reinstallable) {
+        return {false, "none",
+                "re-register failed, and the package is not available from "
+                "the index — removing it could not be undone"};
+    }
+    if (run(remove) != 0) {
+        return {false, "none",
+                "re-register failed and the entry could not be removed"};
+    }
+    // The command exited 0. Two independent questions follow, and the order
+    // they are asked in is the whole safety property.
+    //
+    // WHETHER the install runs must not depend on the verifier. It used to,
+    // and returning early on "the records survived" performed the destructive
+    // half of remove-and-reinstall while skipping the half that puts it back.
+    // Measured on a real home, that uninstalled a working `musl-gcc`: its
+    // recipe names targets the release does not own, those are skipped, the
+    // finding's entry therefore outlived the removal, and the ladder read that
+    // as a reason not to reinstall the package it had just taken out.
+    //
+    // WHAT IS REPORTED does depend on the verifier, because "REMOVED but could
+    // not reinstall" is a claim about the user's disk. `xlings remove` exits 0
+    // when it merely detaches this subos (another subos still references the
+    // version), when the recipe names targets outside the selection, and when
+    // the payload is already gone -- in none of those was anything removed,
+    // and saying so is the message a user is most likely to act on.
+    const bool recordsSurvived =
+        removalDone && !removalDone(task.target, task.version);
+    const bool installed = run(install) == 0;
+
+    if (installed && !recordsSurvived) return {true, "reinstall", {}};
+
+    if (recordsSurvived) {
+        return {false, installed ? "reinstall" : "none",
+                std::format(
+                    "`remove` exited 0 without dropping {} — it is still "
+                    "registered{}. Removal exits 0 when it only detaches this "
+                    "subos (another subos still references the version), when "
+                    "the recipe names targets the release does not own, and "
+                    "when the payload is already gone; none of those clears "
+                    "the record this repair needs cleared. Take it out where "
+                    "it lives (`xlings subos use <name>` then `xlings remove "
+                    "{}`) and rerun",
+                    coordinate,
+                    installed ? ", and the reinstall that followed did not "
+                                "clear it either"
+                              : " and the reinstall failed too",
+                    coordinate)};
+    }
+
+    // Removed for real, and could not be put back. The one outcome that leaves
+    // the user worse off than before the repair, so it is never folded into a
+    // generic failure: name it and hand back the command that finishes the job.
+    return {false, "reinstall",
+            std::format("REMOVED but could not reinstall — run "
+                        "`xlings install {}`", coordinate)};
+}
+
+void print_migration_hint_once(std::string_view recorded,
+                               std::string_view running) {
+    static bool shown = false;
+    if (shown) return;
+    if (!platform::supports_rewrite_output()) return;  // not a terminal
+    auto hint = migration_hint(recorded, running);
+    if (!hint) return;
+    shown = true;
+    log::info("{}", *hint);
+}
+
+}
diff --git a/src/core/xself/repair.cppm b/src/core/xself/repair.cppm
index b73c479a..7323ebdc 100644
--- a/src/core/xself/repair.cppm
+++ b/src/core/xself/repair.cppm
@@ -1,8 +1,6 @@
 export module xlings.core.xself.repair;
 
 import std;
-import xlings.core.log;
-import xlings.platform;
 
 // The repair ladder behind `xlings self doctor --fix`.
 //
@@ -82,14 +80,7 @@ struct RepairResult {
 // refused rather than quoted: a package name with a shell metacharacter in it
 // is not a repair case, it is a broken or hostile index entry, and running it
 // through a quoting function would be trusting the same input twice.
-bool is_shell_safe_token(std::string_view s) {
-    if (s.empty()) return false;
-    if (s.front() == '-') return false;  // would be read as an option
-    return std::ranges::all_of(s, [](unsigned char c) {
-        return std::isalnum(c) || c == '.' || c == '-' || c == '_'
-            || c == '+' || c == ':' || c == '@' || c == '/';
-    });
-}
+bool is_shell_safe_token(std::string_view s);
 
 // Runs a command, returns its exit code. Injected so the ladder can be tested
 // as the pure decision table it is.
@@ -114,13 +105,7 @@ using RemovalVerifier =
 
 // Silences a probe. The probe's output is not part of doctor's report and
 // would interleave with it.
-std::string quiet_suffix() {
-#if defined(_WIN32)
-    return " >NUL 2>&1";
-#else
-    return " >/dev/null 2>&1";
-#endif
-}
+std::string quiet_suffix();
 
 // Can the index supply this package again?
 //
@@ -132,13 +117,7 @@ std::string quiet_suffix() {
 bool probe_reinstallable(const std::string& target,
                          const std::string& version,
                          const CommandRunner& run,
-                         const std::string& client = "xlings") {
-    if (!is_shell_safe_token(target) || !is_shell_safe_token(version)) {
-        return false;
-    }
-    return run(std::format("{} info {}@{}{}",
-                           client, target, version, quiet_suffix())) == 0;
-}
+                         const std::string& client = "xlings");
 
 // The one-line nudge toward `self doctor --fix`.
 //
@@ -151,21 +130,7 @@ bool probe_reinstallable(const std::string& target,
 // Returns nothing when the versions agree, which is what makes the hint stop
 // appearing after a successful --fix stamps the field.
 std::optional<std::string> migration_hint(std::string_view recorded,
-                                          std::string_view running) {
-    auto strip_v = [](std::string_view s) {
-        return (!s.empty() && (s.front() == 'v' || s.front() == 'V'))
-            ? s.substr(1) : s;
-    };
-    const auto a = strip_v(recorded);
-    const auto b = strip_v(running);
-    // An absent record is not a mismatch. A home too old to carry the field
-    // at all, or one written by a build that never set it, would otherwise
-    // nag forever with nothing to compare against.
-    if (a.empty() || b.empty() || a == b) return std::nullopt;
-    return std::format(
-        "this home was set up by {}; packages installed then may still be "
-        "registered in its format\n  run  xlings self doctor --fix", a);
-}
+                                          std::string_view running);
 
 // One ladder, one (target, version). Rungs are tried in order and only if the
 // previous one failed:
@@ -193,93 +158,7 @@ std::optional<std::string> migration_hint(std::string_view recorded,
 RepairResult repair_one(const RepairTask& task,
                         const RepairPolicy& policy,
                         const CommandRunner& run,
-                        const RemovalVerifier& removalDone = nullptr) {
-    const auto coordinate = task.coordinate.empty()
-        ? std::format("{}@{}", task.target, task.version)
-        : task.coordinate;
-    if (task.coordinate.empty()
-        ? (!is_shell_safe_token(task.target)
-           || !is_shell_safe_token(task.version))
-        : !is_shell_safe_token(task.coordinate)) {
-        return {false, "none",
-                "refusing to repair: the recorded name or version contains "
-                "characters that are not safe to pass to a shell"};
-    }
-    if (!policy.allowNetwork) {
-        return {false, "none", "skipped: repairs that may reach the network "
-                               "are disabled for this pass"};
-    }
-
-    const auto install = std::format("{} install {} -y",
-                                     policy.client, coordinate);
-    const auto remove  = std::format("{} remove {} -y",
-                                     policy.client, coordinate);
-
-    // R2
-    if (run(install) == 0) return {true, "re-register", {}};
-
-    // R3
-    if (!policy.allowReinstall) {
-        return {false, "none",
-                "re-register failed; reinstall was not permitted"};
-    }
-    if (!task.reinstallable) {
-        return {false, "none",
-                "re-register failed, and the package is not available from "
-                "the index — removing it could not be undone"};
-    }
-    if (run(remove) != 0) {
-        return {false, "none",
-                "re-register failed and the entry could not be removed"};
-    }
-    // The command exited 0. Two independent questions follow, and the order
-    // they are asked in is the whole safety property.
-    //
-    // WHETHER the install runs must not depend on the verifier. It used to,
-    // and returning early on "the records survived" performed the destructive
-    // half of remove-and-reinstall while skipping the half that puts it back.
-    // Measured on a real home, that uninstalled a working `musl-gcc`: its
-    // recipe names targets the release does not own, those are skipped, the
-    // finding's entry therefore outlived the removal, and the ladder read that
-    // as a reason not to reinstall the package it had just taken out.
-    //
-    // WHAT IS REPORTED does depend on the verifier, because "REMOVED but could
-    // not reinstall" is a claim about the user's disk. `xlings remove` exits 0
-    // when it merely detaches this subos (another subos still references the
-    // version), when the recipe names targets outside the selection, and when
-    // the payload is already gone -- in none of those was anything removed,
-    // and saying so is the message a user is most likely to act on.
-    const bool recordsSurvived =
-        removalDone && !removalDone(task.target, task.version);
-    const bool installed = run(install) == 0;
-
-    if (installed && !recordsSurvived) return {true, "reinstall", {}};
-
-    if (recordsSurvived) {
-        return {false, installed ? "reinstall" : "none",
-                std::format(
-                    "`remove` exited 0 without dropping {} — it is still "
-                    "registered{}. Removal exits 0 when it only detaches this "
-                    "subos (another subos still references the version), when "
-                    "the recipe names targets the release does not own, and "
-                    "when the payload is already gone; none of those clears "
-                    "the record this repair needs cleared. Take it out where "
-                    "it lives (`xlings subos use <name>` then `xlings remove "
-                    "{}`) and rerun",
-                    coordinate,
-                    installed ? ", and the reinstall that followed did not "
-                                "clear it either"
-                              : " and the reinstall failed too",
-                    coordinate)};
-    }
-
-    // Removed for real, and could not be put back. The one outcome that leaves
-    // the user worse off than before the repair, so it is never folded into a
-    // generic failure: name it and hand back the command that finishes the job.
-    return {false, "reinstall",
-            std::format("REMOVED but could not reinstall — run "
-                        "`xlings install {}`", coordinate)};
-}
+                        const RemovalVerifier& removalDone = nullptr);
 
 // The nudge, emitted from the commands a user actually runs.
 //
@@ -301,14 +180,6 @@ RepairResult repair_one(const RepairTask& task,
 //
 // No network and no extra file read beyond the one the config already did.
 void print_migration_hint_once(std::string_view recorded,
-                               std::string_view running) {
-    static bool shown = false;
-    if (shown) return;
-    if (!platform::supports_rewrite_output()) return;  // not a terminal
-    auto hint = migration_hint(recorded, running);
-    if (!hint) return;
-    shown = true;
-    log::info("{}", *hint);
-}
+                               std::string_view running);
 
 } // namespace xlings::xself
diff --git a/src/core/xself/uninstall.cpp b/src/core/xself/uninstall.cpp
new file mode 100644
index 00000000..9c28c6eb
--- /dev/null
+++ b/src/core/xself/uninstall.cpp
@@ -0,0 +1,357 @@
+module xlings.core.xself.uninstall;
+
+import std;
+import xlings.core.config;
+import xlings.core.log;
+import xlings.core.xself.shell_profile;
+import xlings.platform;
+
+namespace xlings::xself {
+
+// Best-effort directory size in bytes. Errors are silently treated as 0.
+std::uintmax_t dir_size_bytes_(const fs::path& dir) {
+    std::error_code ec;
+    if (!fs::exists(dir, ec) || !fs::is_directory(dir, ec)) return 0;
+    std::uintmax_t total = 0;
+    for (auto& entry : fs::recursive_directory_iterator(dir, fs::directory_options::skip_permission_denied, ec)) {
+        if (ec) { ec.clear(); continue; }
+        if (entry.is_regular_file(ec)) {
+            auto sz = entry.file_size(ec);
+            if (!ec) total += sz;
+        }
+        ec.clear();
+    }
+    return total;
+}
+
+std::string format_bytes_(std::uintmax_t bytes) {
+    static constexpr const char* units[] = { "B", "KB", "MB", "GB", "TB" };
+    constexpr std::size_t kNumUnits = sizeof(units) / sizeof(units[0]);
+    double v = static_cast<double>(bytes);
+    std::size_t u = 0;
+    while (v >= 1024.0 && u + 1 < kNumUnits) { v /= 1024.0; ++u; }
+    char buf[32];
+    std::snprintf(buf, sizeof(buf), (u == 0 ? "%.0f %s" : "%.1f %s"), v, units[u]);
+    return buf;
+}
+
+// Refuse to operate on suspicious XLINGS_HOME values that could nuke
+// large parts of the filesystem if the env var was set wrong.
+bool home_dir_safe_to_remove_(const fs::path& home) {
+    std::error_code ec;
+    auto canonical = fs::weakly_canonical(home, ec);
+    if (ec) canonical = home;
+
+    // Reject root / common system roots.
+    static const std::vector<std::string> blacklist = {
+        "/", "/usr", "/usr/local", "/etc", "/opt", "/var", "/home", "/root",
+        "/bin", "/sbin", "/lib", "/lib64",
+        "C:/", "C:\\", "C:/Windows", "C:/Program Files",
+    };
+    auto canonStr = canonical.generic_string();
+    for (auto& b : blacklist) {
+        auto bn = fs::path(b).generic_string();
+        if (canonStr == bn) return false;
+    }
+
+    // Reject if it's exactly $HOME (the user's home dir, not a subdir of it).
+    auto userHome = fs::path(platform::get_home_dir());
+    if (!userHome.empty()) {
+        auto userHomeCanon = fs::weakly_canonical(userHome, ec);
+        if (ec) userHomeCanon = userHome;
+        if (canonical == userHomeCanon) return false;
+    }
+
+    // Must be an absolute, non-empty path with at least 2 components.
+    // (Catches e.g. XLINGS_HOME=. or XLINGS_HOME=foo)
+    if (!canonical.is_absolute()) return false;
+    int component_count = 0;
+    for ([[maybe_unused]] const auto& _ : canonical) ++component_count;
+    if (component_count < 2) return false;
+
+    return true;
+}
+
+// chdir to a safe location so the process doesn't have a cwd inside
+// the directory we're about to delete. Returns the path it moved to.
+fs::path chdir_to_safe_() {
+    std::error_code ec;
+#ifdef _WIN32
+    fs::path safe = "C:\\";
+    if (auto* tmp = std::getenv("TEMP")) safe = tmp;
+#else
+    fs::path safe = "/";
+    if (auto* tmp = std::getenv("TMPDIR")) safe = tmp;
+#endif
+    fs::current_path(safe, ec);
+    return safe;
+}
+
+#ifdef _WIN32
+
+// Move xlings.exe out of XLINGS_HOME and schedule the moved copy for
+// delete-on-reboot. Returns true on success (or no-op if file already
+// gone), false on hard failure.
+bool windows_self_displace_(const fs::path& xlingsExe) {
+    std::error_code ec;
+    if (!fs::exists(xlingsExe, ec)) return true;  // nothing to do
+
+    // Compute pending-delete path in %TEMP%
+    fs::path tempDir;
+    if (auto* t = std::getenv("TEMP")) tempDir = t;
+    else if (auto* t = std::getenv("TMP")) tempDir = t;
+    else tempDir = "C:\\Windows\\Temp";
+
+    auto pid = static_cast<unsigned>(platform::get_pid());
+    auto pending = tempDir / ("xlings-pending-delete-" + std::to_string(pid) + ".exe");
+
+    // MoveFileW handles running exe (same volume) via internal trick.
+    fs::rename(xlingsExe, pending, ec);
+    if (ec) {
+        log::warn("self uninstall: could not move running xlings.exe to {}: {}",
+                  pending.string(), ec.message());
+        return false;
+    }
+
+    // Schedule the temp copy for delete on next reboot.
+    // We can't call MoveFileExW directly without windows.h; fall back to
+    // best-effort attempt via the platform layer. If that's not exposed,
+    // at least the user gets the info that the temp file lingers.
+    log::info("self uninstall: launcher moved to {}; will be cleaned on next restart",
+              pending.string());
+    // TODO: route a platform::schedule_delete_on_reboot(pending) call
+    // through xlings.platform to invoke MoveFileExW(MOVEFILE_DELAY_UNTIL_REBOOT).
+    // For now, the temp file lingers harmlessly until reboot or manual delete.
+    return true;
+}
+
+#endif
+
+int print_summary_(const fs::path& home,
+                          const UninstallOpts& opts,
+                          std::uintmax_t dataSize,
+                          std::uintmax_t totalSize) {
+    log::println("");
+    log::println("This will permanently remove your xlings installation:");
+    log::println("");
+    log::println("  XLINGS_HOME:    {}", home.string());
+    log::println("  total size:     {}", format_bytes_(totalSize));
+    if (opts.keepData) {
+        log::println("  data:           KEEP ({}) — pkgs preserved", format_bytes_(dataSize));
+    } else {
+        log::println("  data:           remove ({})", format_bytes_(dataSize));
+    }
+    log::println("");
+    log::println("The following will NOT be touched:");
+    log::println("  - shell init lines in ~/.bashrc / ~/.zshrc / ~/.profile");
+    log::println("    (you can clean those manually after uninstall)");
+    log::println("  - project-local .xlings/ directories under your projects");
+    log::println("");
+    if (opts.dryRun) log::println("[DRY RUN] no changes will be made.");
+    return 0;
+}
+
+bool prompt_yes_no_(const std::string& question) {
+    log::println("{} [y/N] ", question);
+    std::string line;
+    if (!std::getline(std::cin, line)) return false;
+    if (line.empty()) return false;
+    return line[0] == 'y' || line[0] == 'Y';
+}
+
+// Every startup file `self install` may have hooked, so the advisory covers
+// the same set the install wrote to. The list used to be POSIX-only, which on
+// Windows meant uninstall reported nothing at all while leaving a source line
+// behind in one or two PowerShell profiles.
+std::vector<fs::path> hooked_startup_files_(const fs::path& userHome) {
+    static const std::vector<std::string> rc_files = {
+        ".bashrc", ".zshrc", ".profile", ".config/fish/config.fish"
+    };
+    std::vector<fs::path> files;
+    for (auto& rel : rc_files) files.push_back(userHome / rel);
+
+#ifdef _WIN32
+    // Not a fixed path under the home: each PowerShell host reports its own
+    // $PROFILE, and OneDrive folder redirection can move both. Same probe
+    // install used to find them.
+    for (const auto& p : shell_profile::probe_hosts(
+             shell_profile::kPowerShellHosts,
+             [](const std::string& cmd) {
+                 return platform::run_command_capture(cmd);
+             })) {
+        if (p.status == shell_profile::ProbeStatus::Answered) files.push_back(p.path);
+    }
+#endif
+    return files;
+}
+
+void emit_shell_advisory_(const fs::path& home) {
+    // Detect startup-file lines that source xlings's shell init scripts and
+    // print them so the user can clean up manually.
+    auto userHome = fs::path(platform::get_home_dir());
+    if (userHome.empty()) return;
+
+    // Both spellings: POSIX rc files carry the generic form, PowerShell
+    // profiles carry the native backslash form. On POSIX the two are equal
+    // and the second check costs nothing.
+    const auto homeGeneric = home.generic_string();
+    const auto homeNative  = home.string();
+    bool found_any = false;
+    std::error_code ec;
+    for (auto& rc : hooked_startup_files_(userHome)) {
+        if (!fs::exists(rc, ec) || !fs::is_regular_file(rc, ec)) continue;
+        std::ifstream in(rc);
+        if (!in) continue;
+        std::string line;
+        while (std::getline(in, line)) {
+            // Match lines that reference our XLINGS_HOME path (source / export PATH /
+            // env XLINGS_HOME=...). Substring match is enough — false positives are
+            // rare and the consequence is just a manual-cleanup hint.
+            if (line.find(homeGeneric) != std::string::npos ||
+                line.find(homeNative) != std::string::npos) {
+                if (!found_any) {
+                    log::println("");
+                    log::println("[info] shell startup files reference XLINGS_HOME — you may want to remove these lines manually:");
+                    found_any = true;
+                }
+                log::println("  {}: {}", rc.string(), line);
+            }
+        }
+    }
+}
+
+int cmd_uninstall(UninstallOpts opts) {
+    auto& p = Config::paths();
+    auto home = p.homeDir;
+
+    std::error_code ec;
+    if (!fs::exists(home, ec)) {
+        log::error("XLINGS_HOME does not exist: {}", home.string());
+        return 1;
+    }
+    if (!fs::is_directory(home, ec)) {
+        log::error("XLINGS_HOME is not a directory: {}", home.string());
+        return 1;
+    }
+    if (!home_dir_safe_to_remove_(home)) {
+        log::error("refusing to uninstall — XLINGS_HOME points to a system / root path: {}", home.string());
+        log::error("  set XLINGS_HOME to a sane location first");
+        return 1;
+    }
+
+    auto lockFile = home / ".lock";
+    if (fs::exists(lockFile, ec)) {
+        log::error("another xlings operation is running ({})", lockFile.string());
+        log::error("  finish that operation, or remove the .lock manually if stale");
+        return 1;
+    }
+
+    auto dataSize  = dir_size_bytes_(home / "data");
+    auto totalSize = dir_size_bytes_(home);
+
+    print_summary_(home, opts, dataSize, totalSize);
+
+    if (opts.dryRun) {
+        log::println("(dry-run: nothing removed)");
+        return 0;
+    }
+
+    if (!opts.yes) {
+        if (!prompt_yes_no_("Proceed with full uninstall?")) {
+            log::println("cancelled.");
+            return 1;
+        }
+    }
+
+    // Collect rc-file advisories BEFORE we delete anything (path strings
+    // become invalid after the home dir is gone, and we want the user to
+    // see this even if removal fails partway).
+    emit_shell_advisory_(home);
+
+    // chdir away so we don't leave the process with a cwd inside what
+    // we're deleting.
+    auto safe = chdir_to_safe_();
+    log::debug("self uninstall: chdir → {}", safe.string());
+
+#ifdef _WIN32
+    // Displace the running xlings.exe before bulk-removing the home tree.
+    auto xlingsExe = home / "bin" / "xlings.exe";
+    if (!windows_self_displace_(xlingsExe)) {
+        log::error("self uninstall: failed to displace running xlings.exe; aborting");
+        return 1;
+    }
+#endif
+
+    // Sub-paths to remove. With --keep-data we skip data/ but still
+    // remove everything else (so the install is gone but pkg payloads
+    // survive for a quick reinstall).
+    std::vector<fs::path> targets = {
+        home / "bin",
+        home / "subos",
+        home / "config",
+        home / ".xlings.json",
+    };
+    if (!opts.keepData) {
+        targets.push_back(home / "data");
+    }
+
+    int failures = 0;
+    for (auto& t : targets) {
+        if (!fs::exists(t, ec)) continue;
+        std::error_code rmEc;
+        fs::remove_all(t, rmEc);
+        if (rmEc) {
+            log::warn("self uninstall: failed to remove {}: {}", t.string(), rmEc.message());
+            ++failures;
+        } else {
+            log::debug("self uninstall: removed {}", t.string());
+        }
+    }
+
+    // Sweep stray top-level files (e.g. lockfiles, leftover state).
+    if (fs::exists(home, ec)) {
+        for (auto& entry : fs::directory_iterator(home, ec)) {
+            // Skip data/ if we're keeping it.
+            if (opts.keepData && entry.path().filename() == "data") continue;
+            std::error_code rmEc;
+            fs::remove_all(entry.path(), rmEc);
+            if (rmEc) {
+                log::warn("self uninstall: failed to remove {}: {}",
+                          entry.path().string(), rmEc.message());
+                ++failures;
+            }
+        }
+    }
+
+    // Remove the home dir itself if it's now empty.
+    if (!opts.keepData && fs::exists(home, ec) && fs::is_empty(home, ec)) {
+        std::error_code rmEc;
+        fs::remove(home, rmEc);
+        if (rmEc) {
+            log::warn("self uninstall: failed to remove home dir {}: {}",
+                      home.string(), rmEc.message());
+            ++failures;
+        }
+    }
+
+    if (failures > 0) {
+        log::println("");
+        log::error("self uninstall completed with {} failure(s).", failures);
+        log::error("  inspect {} for leftover content", home.string());
+        log::error("  you may need to remove the rest manually: rm -rf {}", home.string());
+        return 1;
+    }
+
+    log::println("");
+    if (opts.keepData) {
+        log::println("xlings uninstalled. data/ preserved at {} (pkg payloads kept).", (home / "data").string());
+    } else {
+        log::println("xlings uninstalled. {} removed.", home.string());
+    }
+#ifdef _WIN32
+    log::println("the launcher binary will be cleaned up on next system restart.");
+#endif
+    return 0;
+}
+
+}
diff --git a/src/core/xself/uninstall.cppm b/src/core/xself/uninstall.cppm
index 3d7c54fa..29a58deb 100644
--- a/src/core/xself/uninstall.cppm
+++ b/src/core/xself/uninstall.cppm
@@ -2,9 +2,7 @@ export module xlings.core.xself.uninstall;
 
 import std;
 import xlings.core.config;
-import xlings.core.log;
 import xlings.core.xself.shell_profile;
-import xlings.platform;
 
 // `xlings self uninstall [-y] [--keep-data] [--dry-run]`
 //
@@ -34,348 +32,11 @@ export struct UninstallOpts {
     bool dryRun   = false;   // --dry-run: print plan, do nothing
 };
 
-// Best-effort directory size in bytes. Errors are silently treated as 0.
-static std::uintmax_t dir_size_bytes_(const fs::path& dir) {
-    std::error_code ec;
-    if (!fs::exists(dir, ec) || !fs::is_directory(dir, ec)) return 0;
-    std::uintmax_t total = 0;
-    for (auto& entry : fs::recursive_directory_iterator(dir, fs::directory_options::skip_permission_denied, ec)) {
-        if (ec) { ec.clear(); continue; }
-        if (entry.is_regular_file(ec)) {
-            auto sz = entry.file_size(ec);
-            if (!ec) total += sz;
-        }
-        ec.clear();
-    }
-    return total;
-}
-
-static std::string format_bytes_(std::uintmax_t bytes) {
-    static constexpr const char* units[] = { "B", "KB", "MB", "GB", "TB" };
-    constexpr std::size_t kNumUnits = sizeof(units) / sizeof(units[0]);
-    double v = static_cast<double>(bytes);
-    std::size_t u = 0;
-    while (v >= 1024.0 && u + 1 < kNumUnits) { v /= 1024.0; ++u; }
-    char buf[32];
-    std::snprintf(buf, sizeof(buf), (u == 0 ? "%.0f %s" : "%.1f %s"), v, units[u]);
-    return buf;
-}
-
-// Refuse to operate on suspicious XLINGS_HOME values that could nuke
-// large parts of the filesystem if the env var was set wrong.
-static bool home_dir_safe_to_remove_(const fs::path& home) {
-    std::error_code ec;
-    auto canonical = fs::weakly_canonical(home, ec);
-    if (ec) canonical = home;
-
-    // Reject root / common system roots.
-    static const std::vector<std::string> blacklist = {
-        "/", "/usr", "/usr/local", "/etc", "/opt", "/var", "/home", "/root",
-        "/bin", "/sbin", "/lib", "/lib64",
-        "C:/", "C:\\", "C:/Windows", "C:/Program Files",
-    };
-    auto canonStr = canonical.generic_string();
-    for (auto& b : blacklist) {
-        auto bn = fs::path(b).generic_string();
-        if (canonStr == bn) return false;
-    }
-
-    // Reject if it's exactly $HOME (the user's home dir, not a subdir of it).
-    auto userHome = fs::path(platform::get_home_dir());
-    if (!userHome.empty()) {
-        auto userHomeCanon = fs::weakly_canonical(userHome, ec);
-        if (ec) userHomeCanon = userHome;
-        if (canonical == userHomeCanon) return false;
-    }
-
-    // Must be an absolute, non-empty path with at least 2 components.
-    // (Catches e.g. XLINGS_HOME=. or XLINGS_HOME=foo)
-    if (!canonical.is_absolute()) return false;
-    int component_count = 0;
-    for ([[maybe_unused]] const auto& _ : canonical) ++component_count;
-    if (component_count < 2) return false;
-
-    return true;
-}
-
-// chdir to a safe location so the process doesn't have a cwd inside
-// the directory we're about to delete. Returns the path it moved to.
-static fs::path chdir_to_safe_() {
-    std::error_code ec;
-#ifdef _WIN32
-    fs::path safe = "C:\\";
-    if (auto* tmp = std::getenv("TEMP")) safe = tmp;
-#else
-    fs::path safe = "/";
-    if (auto* tmp = std::getenv("TMPDIR")) safe = tmp;
-#endif
-    fs::current_path(safe, ec);
-    return safe;
-}
-
 #ifdef _WIN32
-// Move xlings.exe out of XLINGS_HOME and schedule the moved copy for
-// delete-on-reboot. Returns true on success (or no-op if file already
-// gone), false on hard failure.
-static bool windows_self_displace_(const fs::path& xlingsExe) {
-    std::error_code ec;
-    if (!fs::exists(xlingsExe, ec)) return true;  // nothing to do
 
-    // Compute pending-delete path in %TEMP%
-    fs::path tempDir;
-    if (auto* t = std::getenv("TEMP")) tempDir = t;
-    else if (auto* t = std::getenv("TMP")) tempDir = t;
-    else tempDir = "C:\\Windows\\Temp";
-
-    auto pid = static_cast<unsigned>(platform::get_pid());
-    auto pending = tempDir / ("xlings-pending-delete-" + std::to_string(pid) + ".exe");
-
-    // MoveFileW handles running exe (same volume) via internal trick.
-    fs::rename(xlingsExe, pending, ec);
-    if (ec) {
-        log::warn("self uninstall: could not move running xlings.exe to {}: {}",
-                  pending.string(), ec.message());
-        return false;
-    }
-
-    // Schedule the temp copy for delete on next reboot.
-    // We can't call MoveFileExW directly without windows.h; fall back to
-    // best-effort attempt via the platform layer. If that's not exposed,
-    // at least the user gets the info that the temp file lingers.
-    log::info("self uninstall: launcher moved to {}; will be cleaned on next restart",
-              pending.string());
-    // TODO: route a platform::schedule_delete_on_reboot(pending) call
-    // through xlings.platform to invoke MoveFileExW(MOVEFILE_DELAY_UNTIL_REBOOT).
-    // For now, the temp file lingers harmlessly until reboot or manual delete.
-    return true;
-}
-#endif
-
-static int print_summary_(const fs::path& home,
-                          const UninstallOpts& opts,
-                          std::uintmax_t dataSize,
-                          std::uintmax_t totalSize) {
-    log::println("");
-    log::println("This will permanently remove your xlings installation:");
-    log::println("");
-    log::println("  XLINGS_HOME:    {}", home.string());
-    log::println("  total size:     {}", format_bytes_(totalSize));
-    if (opts.keepData) {
-        log::println("  data:           KEEP ({}) — pkgs preserved", format_bytes_(dataSize));
-    } else {
-        log::println("  data:           remove ({})", format_bytes_(dataSize));
-    }
-    log::println("");
-    log::println("The following will NOT be touched:");
-    log::println("  - shell init lines in ~/.bashrc / ~/.zshrc / ~/.profile");
-    log::println("    (you can clean those manually after uninstall)");
-    log::println("  - project-local .xlings/ directories under your projects");
-    log::println("");
-    if (opts.dryRun) log::println("[DRY RUN] no changes will be made.");
-    return 0;
-}
-
-static bool prompt_yes_no_(const std::string& question) {
-    log::println("{} [y/N] ", question);
-    std::string line;
-    if (!std::getline(std::cin, line)) return false;
-    if (line.empty()) return false;
-    return line[0] == 'y' || line[0] == 'Y';
-}
-
-// Every startup file `self install` may have hooked, so the advisory covers
-// the same set the install wrote to. The list used to be POSIX-only, which on
-// Windows meant uninstall reported nothing at all while leaving a source line
-// behind in one or two PowerShell profiles.
-static std::vector<fs::path> hooked_startup_files_(const fs::path& userHome) {
-    static const std::vector<std::string> rc_files = {
-        ".bashrc", ".zshrc", ".profile", ".config/fish/config.fish"
-    };
-    std::vector<fs::path> files;
-    for (auto& rel : rc_files) files.push_back(userHome / rel);
-
-#ifdef _WIN32
-    // Not a fixed path under the home: each PowerShell host reports its own
-    // $PROFILE, and OneDrive folder redirection can move both. Same probe
-    // install used to find them.
-    for (const auto& p : shell_profile::probe_hosts(
-             shell_profile::kPowerShellHosts,
-             [](const std::string& cmd) {
-                 return platform::run_command_capture(cmd);
-             })) {
-        if (p.status == shell_profile::ProbeStatus::Answered) files.push_back(p.path);
-    }
 #endif
-    return files;
-}
-
-static void emit_shell_advisory_(const fs::path& home) {
-    // Detect startup-file lines that source xlings's shell init scripts and
-    // print them so the user can clean up manually.
-    auto userHome = fs::path(platform::get_home_dir());
-    if (userHome.empty()) return;
 
-    // Both spellings: POSIX rc files carry the generic form, PowerShell
-    // profiles carry the native backslash form. On POSIX the two are equal
-    // and the second check costs nothing.
-    const auto homeGeneric = home.generic_string();
-    const auto homeNative  = home.string();
-    bool found_any = false;
-    std::error_code ec;
-    for (auto& rc : hooked_startup_files_(userHome)) {
-        if (!fs::exists(rc, ec) || !fs::is_regular_file(rc, ec)) continue;
-        std::ifstream in(rc);
-        if (!in) continue;
-        std::string line;
-        while (std::getline(in, line)) {
-            // Match lines that reference our XLINGS_HOME path (source / export PATH /
-            // env XLINGS_HOME=...). Substring match is enough — false positives are
-            // rare and the consequence is just a manual-cleanup hint.
-            if (line.find(homeGeneric) != std::string::npos ||
-                line.find(homeNative) != std::string::npos) {
-                if (!found_any) {
-                    log::println("");
-                    log::println("[info] shell startup files reference XLINGS_HOME — you may want to remove these lines manually:");
-                    found_any = true;
-                }
-                log::println("  {}: {}", rc.string(), line);
-            }
-        }
-    }
-}
 
-export int cmd_uninstall(UninstallOpts opts) {
-    auto& p = Config::paths();
-    auto home = p.homeDir;
-
-    std::error_code ec;
-    if (!fs::exists(home, ec)) {
-        log::error("XLINGS_HOME does not exist: {}", home.string());
-        return 1;
-    }
-    if (!fs::is_directory(home, ec)) {
-        log::error("XLINGS_HOME is not a directory: {}", home.string());
-        return 1;
-    }
-    if (!home_dir_safe_to_remove_(home)) {
-        log::error("refusing to uninstall — XLINGS_HOME points to a system / root path: {}", home.string());
-        log::error("  set XLINGS_HOME to a sane location first");
-        return 1;
-    }
-
-    auto lockFile = home / ".lock";
-    if (fs::exists(lockFile, ec)) {
-        log::error("another xlings operation is running ({})", lockFile.string());
-        log::error("  finish that operation, or remove the .lock manually if stale");
-        return 1;
-    }
-
-    auto dataSize  = dir_size_bytes_(home / "data");
-    auto totalSize = dir_size_bytes_(home);
-
-    print_summary_(home, opts, dataSize, totalSize);
-
-    if (opts.dryRun) {
-        log::println("(dry-run: nothing removed)");
-        return 0;
-    }
-
-    if (!opts.yes) {
-        if (!prompt_yes_no_("Proceed with full uninstall?")) {
-            log::println("cancelled.");
-            return 1;
-        }
-    }
-
-    // Collect rc-file advisories BEFORE we delete anything (path strings
-    // become invalid after the home dir is gone, and we want the user to
-    // see this even if removal fails partway).
-    emit_shell_advisory_(home);
-
-    // chdir away so we don't leave the process with a cwd inside what
-    // we're deleting.
-    auto safe = chdir_to_safe_();
-    log::debug("self uninstall: chdir → {}", safe.string());
-
-#ifdef _WIN32
-    // Displace the running xlings.exe before bulk-removing the home tree.
-    auto xlingsExe = home / "bin" / "xlings.exe";
-    if (!windows_self_displace_(xlingsExe)) {
-        log::error("self uninstall: failed to displace running xlings.exe; aborting");
-        return 1;
-    }
-#endif
-
-    // Sub-paths to remove. With --keep-data we skip data/ but still
-    // remove everything else (so the install is gone but pkg payloads
-    // survive for a quick reinstall).
-    std::vector<fs::path> targets = {
-        home / "bin",
-        home / "subos",
-        home / "config",
-        home / ".xlings.json",
-    };
-    if (!opts.keepData) {
-        targets.push_back(home / "data");
-    }
-
-    int failures = 0;
-    for (auto& t : targets) {
-        if (!fs::exists(t, ec)) continue;
-        std::error_code rmEc;
-        fs::remove_all(t, rmEc);
-        if (rmEc) {
-            log::warn("self uninstall: failed to remove {}: {}", t.string(), rmEc.message());
-            ++failures;
-        } else {
-            log::debug("self uninstall: removed {}", t.string());
-        }
-    }
-
-    // Sweep stray top-level files (e.g. lockfiles, leftover state).
-    if (fs::exists(home, ec)) {
-        for (auto& entry : fs::directory_iterator(home, ec)) {
-            // Skip data/ if we're keeping it.
-            if (opts.keepData && entry.path().filename() == "data") continue;
-            std::error_code rmEc;
-            fs::remove_all(entry.path(), rmEc);
-            if (rmEc) {
-                log::warn("self uninstall: failed to remove {}: {}",
-                          entry.path().string(), rmEc.message());
-                ++failures;
-            }
-        }
-    }
-
-    // Remove the home dir itself if it's now empty.
-    if (!opts.keepData && fs::exists(home, ec) && fs::is_empty(home, ec)) {
-        std::error_code rmEc;
-        fs::remove(home, rmEc);
-        if (rmEc) {
-            log::warn("self uninstall: failed to remove home dir {}: {}",
-                      home.string(), rmEc.message());
-            ++failures;
-        }
-    }
-
-    if (failures > 0) {
-        log::println("");
-        log::error("self uninstall completed with {} failure(s).", failures);
-        log::error("  inspect {} for leftover content", home.string());
-        log::error("  you may need to remove the rest manually: rm -rf {}", home.string());
-        return 1;
-    }
-
-    log::println("");
-    if (opts.keepData) {
-        log::println("xlings uninstalled. data/ preserved at {} (pkg payloads kept).", (home / "data").string());
-    } else {
-        log::println("xlings uninstalled. {} removed.", home.string());
-    }
-#ifdef _WIN32
-    log::println("the launcher binary will be cleaned up on next system restart.");
-#endif
-    return 0;
-}
+export int cmd_uninstall(UninstallOpts opts);
 
 } // namespace xlings::xself
diff --git a/src/core/xself/update.cpp b/src/core/xself/update.cpp
new file mode 100644
index 00000000..be82d050
--- /dev/null
+++ b/src/core/xself/update.cpp
@@ -0,0 +1,79 @@
+module xlings.core.xself.update;
+
+import std;
+import xlings.core.log;
+import xlings.platform;
+
+namespace xlings::xself {
+
+int cmd_update() {
+    log::info("updating package index...");
+    platform::set_env_variable("XLINGS_INDEX_PIN", "newest");
+    int rc = platform::exec("xlings update");
+    platform::set_env_variable("XLINGS_INDEX_PIN", "");
+    if (rc != 0) {
+        log::error("failed to update package index");
+        return rc;
+    }
+
+    // Reach the newest index snapshot for THIS step only.
+    //
+    // Routing (#476) can put an older client on an older index snapshot -- and
+    // that snapshot's own `pkgs/x/xlings.lua` names the `latest` of its era. A
+    // client routed back would therefore be told it is already current and
+    // could never upgrade, so it could never return to the newer index: a
+    // deadlock guaranteed by construction, not a rare race.
+    //
+    // The upgrade path is exempt from routing. Only one recipe has to be
+    // readable from the newer snapshot, and that recipe's shape (XLINGS_RES
+    // plus per-arch sha256) has been stable across every release so far. If
+    // the install fails partway the tree is newer than the client, and the
+    // next `xlings update` routes it back -- the state self-heals.
+    log::info("installing xlings@latest...");
+    platform::set_env_variable("XLINGS_INDEX_PIN", "newest");
+    rc = platform::exec("xlings install xlings@latest -y");
+    platform::set_env_variable("XLINGS_INDEX_PIN", "");
+    if (rc != 0) {
+        // This used to warn and return 0. A failed upgrade then looked
+        // exactly like a successful one: the install error scrolled past
+        // under the progress bar, `self update` exited 0, and the user went
+        // on running the old binary believing they were current. Observed
+        // for real -- 0.4.69 against a CN mirror that had not been topped up
+        // yet answered 404, and the command still reported success.
+        //
+        // Whichever way it failed -- absent from the index, download error,
+        // hook failure -- the user asked to be upgraded and was not, so say
+        // so and exit non-zero.
+        log::error("could not install xlings@latest — you are still on the "
+                   "current version");
+        log::error("  hint: run `xlings install xlings@latest -y` to see why");
+        return rc;
+    }
+
+    rc = platform::exec("xlings use xlings latest");
+    if (rc != 0) {
+        log::error("installed xlings@latest but could not activate it");
+        log::error("  hint: run `xlings use xlings latest` to see why");
+        return rc;
+    }
+
+    // The migration nudge, printed rather than performed.
+    //
+    // This function is running the OLD binary -- it has just replaced itself
+    // on disk and is about to exit. It cannot do the migration: the code that
+    // knows how is in the binary that is not running yet, and a half-finished
+    // pass over a home it can no longer reason about is worse than none.
+    //
+    // What it can do is say so at the moment the mismatch is created. The new
+    // client repeats it (see cmd_doctor's migration hint) until a --fix
+    // actually brings the home in line, so this is a nudge and not the only
+    // chance to see it.
+    log::info("");
+    log::info("packages installed by the previous client may still be "
+              "registered in its format");
+    log::info("  run  xlings self doctor --fix");
+
+    return 0;
+}
+
+}
diff --git a/src/core/xself/update.cppm b/src/core/xself/update.cppm
index 18f9e675..18c106fa 100644
--- a/src/core/xself/update.cppm
+++ b/src/core/xself/update.cppm
@@ -2,8 +2,6 @@ export module xlings.core.xself.update;
 
 import std;
 
-import xlings.core.log;
-import xlings.platform;
 
 namespace xlings::xself {
 
@@ -12,74 +10,6 @@ namespace xlings::xself {
 // platform::exec rather than calling cmd_install/cmd_use directly: that
 // avoids the circular module dependency that would otherwise arise
 // (xim.commands and xvm.commands both import xlings.core.xself).
-export int cmd_update() {
-    log::info("updating package index...");
-    platform::set_env_variable("XLINGS_INDEX_PIN", "newest");
-    int rc = platform::exec("xlings update");
-    platform::set_env_variable("XLINGS_INDEX_PIN", "");
-    if (rc != 0) {
-        log::error("failed to update package index");
-        return rc;
-    }
-
-    // Reach the newest index snapshot for THIS step only.
-    //
-    // Routing (#476) can put an older client on an older index snapshot -- and
-    // that snapshot's own `pkgs/x/xlings.lua` names the `latest` of its era. A
-    // client routed back would therefore be told it is already current and
-    // could never upgrade, so it could never return to the newer index: a
-    // deadlock guaranteed by construction, not a rare race.
-    //
-    // The upgrade path is exempt from routing. Only one recipe has to be
-    // readable from the newer snapshot, and that recipe's shape (XLINGS_RES
-    // plus per-arch sha256) has been stable across every release so far. If
-    // the install fails partway the tree is newer than the client, and the
-    // next `xlings update` routes it back -- the state self-heals.
-    log::info("installing xlings@latest...");
-    platform::set_env_variable("XLINGS_INDEX_PIN", "newest");
-    rc = platform::exec("xlings install xlings@latest -y");
-    platform::set_env_variable("XLINGS_INDEX_PIN", "");
-    if (rc != 0) {
-        // This used to warn and return 0. A failed upgrade then looked
-        // exactly like a successful one: the install error scrolled past
-        // under the progress bar, `self update` exited 0, and the user went
-        // on running the old binary believing they were current. Observed
-        // for real -- 0.4.69 against a CN mirror that had not been topped up
-        // yet answered 404, and the command still reported success.
-        //
-        // Whichever way it failed -- absent from the index, download error,
-        // hook failure -- the user asked to be upgraded and was not, so say
-        // so and exit non-zero.
-        log::error("could not install xlings@latest — you are still on the "
-                   "current version");
-        log::error("  hint: run `xlings install xlings@latest -y` to see why");
-        return rc;
-    }
-
-    rc = platform::exec("xlings use xlings latest");
-    if (rc != 0) {
-        log::error("installed xlings@latest but could not activate it");
-        log::error("  hint: run `xlings use xlings latest` to see why");
-        return rc;
-    }
-
-    // The migration nudge, printed rather than performed.
-    //
-    // This function is running the OLD binary -- it has just replaced itself
-    // on disk and is about to exit. It cannot do the migration: the code that
-    // knows how is in the binary that is not running yet, and a half-finished
-    // pass over a home it can no longer reason about is worse than none.
-    //
-    // What it can do is say so at the moment the mismatch is created. The new
-    // client repeats it (see cmd_doctor's migration hint) until a --fix
-    // actually brings the home in line, so this is a nudge and not the only
-    // chance to see it.
-    log::info("");
-    log::info("packages installed by the previous client may still be "
-              "registered in its format");
-    log::info("  run  xlings self doctor --fix");
-
-    return 0;
-}
+export int cmd_update();
 
 } // namespace xlings::xself
diff --git a/src/core/xvm/bindings.cpp b/src/core/xvm/bindings.cpp
new file mode 100644
index 00000000..78dfc579
--- /dev/null
+++ b/src/core/xvm/bindings.cpp
@@ -0,0 +1,582 @@
+module xlings.core.xvm.bindings;
+
+import std;
+import xlings.core.xvm.types;
+
+namespace xlings::xvm::detail_ {
+
+BindingError binding_error_(BindingErrorKind kind,
+                            const std::string& target,
+                            const std::string& version,
+                            std::string message) {
+    return {
+        .kind = kind,
+        .target = target,
+        .version = version,
+        .message = std::move(message),
+    };
+}
+
+bool same_group_identity_(const BindingGroupRef& lhs,
+                          const BindingGroupRef& rhs) {
+    return lhs.provider == rhs.provider
+        && lhs.providerVersion == rhs.providerVersion
+        && lhs.group == rhs.group;
+}
+
+bool same_group_(const BindingGroupRef& lhs, const BindingGroupRef& rhs) {
+    return same_group_identity_(lhs, rhs)
+        && lhs.rootTarget == rhs.rootTarget
+        && lhs.rootVersion == rhs.rootVersion;
+}
+
+bool supported_kind_(std::string_view kind) {
+    return kind == "program" || kind == "lib" || kind == "group"
+        || kind == "files";
+}
+
+std::optional<std::string_view>
+canonical_manifest_path_(const VData& data) {
+    if (data.bindingMembersDeclared || !data.bindingMembers.empty()) {
+        return "/bindingMembers";
+    }
+    if (data.bindingHeadersDeclared || !data.bindingHeaders.empty()) {
+        return "/bindingHeaders";
+    }
+    return std::nullopt;
+}
+
+bool has_canonical_manifest_(const VData& data) {
+    return canonical_manifest_path_(data).has_value();
+}
+
+BindingError metadata_integrity_error_(
+    const std::string& target,
+    const std::string& version,
+    std::string_view code,
+    std::string_view path) {
+    return binding_error_(
+        BindingErrorKind::MetadataIntegrityIssue,
+        target, version,
+        std::format("binding metadata integrity issue '{}' at '{}'",
+                    code, path));
+}
+
+std::optional<BindingError>
+binding_integrity_error_(const VData& data,
+                         const std::string& target,
+                         const std::string& version) {
+    if (data.bindingIntegrityIssues.empty()) return std::nullopt;
+    const auto& issue = data.bindingIntegrityIssues.front();
+    return metadata_integrity_error_(
+        target, version, issue.code, issue.path);
+}
+
+std::string json_pointer_token_(std::string_view token) {
+    std::string escaped;
+    escaped.reserve(token.size());
+    for (const auto ch : token) {
+        if (ch == '~') {
+            escaped += "~0";
+        } else if (ch == '/') {
+            escaped += "~1";
+        } else {
+            escaped += ch;
+        }
+    }
+    return escaped;
+}
+
+std::optional<BindingError>
+root_content_integrity_error_(const VData& root,
+                              const std::string& target,
+                              const std::string& version) {
+    for (const auto& [memberTarget, memberVersion] : root.bindingMembers) {
+        if (memberTarget.empty()) {
+            return metadata_integrity_error_(
+                target, version,
+                "binding-member-target-empty", "/bindingMembers/");
+        }
+        if (memberVersion.empty()) {
+            return metadata_integrity_error_(
+                target, version,
+                "binding-member-version-empty",
+                "/bindingMembers/" + json_pointer_token_(memberTarget));
+        }
+    }
+    for (std::size_t index = 0;
+         index < root.bindingHeaders.size(); ++index) {
+        if (root.bindingHeaders[index].sourceDir.empty()) {
+            return metadata_integrity_error_(
+                target, version,
+                "binding-header-source-dir-empty",
+                std::format("/bindingHeaders/{}/sourceDir", index));
+        }
+    }
+    return std::nullopt;
+}
+
+std::optional<std::string_view>
+invalid_group_identity_path_(const BindingGroupRef& group) {
+    if (group.provider.empty()) return "/bindingGroup/provider";
+    if (group.providerVersion.empty()) return "/bindingGroup/version";
+    if (group.group.empty()) return "/bindingGroup/group";
+    if (group.rootTarget.empty()) return "/bindingGroup/rootTarget";
+    if (group.rootVersion.empty()) return "/bindingGroup/rootVersion";
+    return std::nullopt;
+}
+
+std::optional<BindingError>
+group_identity_integrity_error_(const BindingGroupRef& group,
+                                const std::string& target,
+                                const std::string& version) {
+    const auto invalidPath = invalid_group_identity_path_(group);
+    if (!invalidPath) return std::nullopt;
+    return metadata_integrity_error_(
+        target, version, "binding-group-field-invalid", *invalidPath);
+}
+
+std::optional<BindingError>
+non_root_metadata_error_(const VData& data,
+                         const std::string& target,
+                         const std::string& version,
+                         const BindingGroupRef& group) {
+    if (target == group.rootTarget && version == group.rootVersion) {
+        return std::nullopt;
+    }
+    const auto metadataPath = canonical_manifest_path_(data);
+    if (!metadataPath) return std::nullopt;
+    return metadata_integrity_error_(
+        target, version, "binding-metadata-on-non-root", *metadataPath);
+}
+
+std::expected<BindingSelection, BindingError>
+resolve_provider_group_(const VersionDB& db,
+                        const std::string& target,
+                        const std::string& version,
+                        const BindingGroupRef& group) {
+    auto rootInfoIt = db.find(group.rootTarget);
+    if (rootInfoIt == db.end()) {
+        return std::unexpected(binding_error_(
+            BindingErrorKind::TargetNotFound,
+            group.rootTarget, group.rootVersion,
+            "binding root target is missing"));
+    }
+    auto rootIt = rootInfoIt->second.versions.find(group.rootVersion);
+    if (rootIt == rootInfoIt->second.versions.end()) {
+        return std::unexpected(binding_error_(
+            BindingErrorKind::VersionNotFound,
+            group.rootTarget, group.rootVersion,
+            "binding root version is missing"));
+    }
+
+    const auto& root = rootIt->second;
+    if (auto error = binding_integrity_error_(
+            root, group.rootTarget, group.rootVersion)) {
+        return std::unexpected(std::move(*error));
+    }
+    if (root.bindingGroup) {
+        if (auto error = group_identity_integrity_error_(
+                *root.bindingGroup,
+                group.rootTarget, group.rootVersion)) {
+            return std::unexpected(std::move(*error));
+        }
+    }
+    if (!root.bindingGroup
+        || root.bindingGroup->rootTarget != group.rootTarget
+        || root.bindingGroup->rootVersion != group.rootVersion) {
+        return std::unexpected(binding_error_(
+            BindingErrorKind::RootReferenceMismatch,
+            group.rootTarget, group.rootVersion,
+            "binding root does not reference itself"));
+    }
+    if (!same_group_identity_(*root.bindingGroup, group)) {
+        return std::unexpected(binding_error_(
+            BindingErrorKind::GroupIdentityMismatch,
+            group.rootTarget, group.rootVersion,
+            "binding root group identity is inconsistent"));
+    }
+    if (auto error = root_content_integrity_error_(
+            root, group.rootTarget, group.rootVersion)) {
+        return std::unexpected(std::move(*error));
+    }
+
+    auto startIt = root.bindingMembers.find(target);
+    if (startIt == root.bindingMembers.end() || startIt->second != version) {
+        return std::unexpected(binding_error_(
+            BindingErrorKind::StartMemberMissing,
+            target, version, "starting member is absent from binding manifest"));
+    }
+    auto manifestRootIt = root.bindingMembers.find(group.rootTarget);
+    if (manifestRootIt == root.bindingMembers.end()
+        || manifestRootIt->second != group.rootVersion) {
+        return std::unexpected(binding_error_(
+            BindingErrorKind::RootMissingFromManifest,
+            group.rootTarget, group.rootVersion,
+            "binding root is absent from binding manifest"));
+    }
+
+    for (const auto& [memberTarget, memberVersion] : root.bindingMembers) {
+        auto memberInfoIt = db.find(memberTarget);
+        if (memberInfoIt == db.end()) {
+            return std::unexpected(binding_error_(
+                BindingErrorKind::TargetNotFound,
+                memberTarget, memberVersion,
+                "binding member target is missing"));
+        }
+        auto memberIt = memberInfoIt->second.versions.find(memberVersion);
+        if (memberIt == memberInfoIt->second.versions.end()) {
+            return std::unexpected(binding_error_(
+                BindingErrorKind::VersionNotFound,
+                memberTarget, memberVersion,
+                "binding member version is missing"));
+        }
+        if (auto error = binding_integrity_error_(
+                memberIt->second, memberTarget, memberVersion)) {
+            return std::unexpected(std::move(*error));
+        }
+        if (memberIt->second.bindingGroup) {
+            if (auto error = group_identity_integrity_error_(
+                    *memberIt->second.bindingGroup,
+                    memberTarget, memberVersion)) {
+                return std::unexpected(std::move(*error));
+            }
+        }
+        if (!memberIt->second.bindingGroup
+            || !same_group_(*memberIt->second.bindingGroup, group)) {
+            return std::unexpected(binding_error_(
+                BindingErrorKind::MemberReferenceMismatch,
+                memberTarget, memberVersion,
+                "binding member back-reference is inconsistent"));
+        }
+        if (auto error = non_root_metadata_error_(
+                memberIt->second, memberTarget, memberVersion, group)) {
+            return std::unexpected(std::move(*error));
+        }
+        if (!supported_kind_(memberIt->second.kind)) {
+            return std::unexpected(binding_error_(
+                BindingErrorKind::UnsupportedKind,
+                memberTarget, memberVersion,
+                std::format("unsupported provider-group member kind '{}'",
+                            memberIt->second.kind)));
+        }
+    }
+
+    return BindingSelection{
+        .members = root.bindingMembers,
+        .source = BindingSource::ProviderGroup,
+    };
+}
+
+std::expected<BindingSelection, BindingError>
+resolve_legacy_graph_(const VersionDB& db,
+                      const std::string& target,
+                      const std::string& version,
+                      const std::map<
+                          std::pair<std::string, std::string>,
+                          std::vector<std::pair<
+                              std::string, std::string>>>& incomingEdges) {
+    BindingSelection selection{
+        .source = BindingSource::LegacyGraph,
+    };
+    std::vector<std::pair<std::string, std::string>> pending{
+        {target, version},
+    };
+    std::set<std::pair<std::string, std::string>> visited;
+    while (!pending.empty()) {
+        auto [currentTarget, currentVersion] = std::move(pending.back());
+        pending.pop_back();
+        if (!visited.emplace(currentTarget, currentVersion).second) continue;
+
+        auto infoIt = db.find(currentTarget);
+        if (infoIt == db.end()) {
+            return std::unexpected(binding_error_(
+                BindingErrorKind::TargetNotFound,
+                currentTarget, currentVersion,
+                "legacy target is missing"));
+        }
+        auto dataIt = infoIt->second.versions.find(currentVersion);
+        if (dataIt == infoIt->second.versions.end()) {
+            return std::unexpected(binding_error_(
+                BindingErrorKind::VersionNotFound,
+                currentTarget, currentVersion,
+                "legacy version is missing"));
+        }
+        if (auto error = binding_integrity_error_(
+                dataIt->second, currentTarget, currentVersion)) {
+            return std::unexpected(std::move(*error));
+        }
+        if (dataIt->second.bindingGroup) {
+            if (auto error = group_identity_integrity_error_(
+                    *dataIt->second.bindingGroup,
+                    currentTarget, currentVersion)) {
+                return std::unexpected(std::move(*error));
+            }
+            return std::unexpected(binding_error_(
+                BindingErrorKind::ProviderMetadataInLegacyGraph,
+                currentTarget, currentVersion,
+                "provider-aware version cannot participate in a legacy graph"));
+        }
+        if (has_canonical_manifest_(dataIt->second)) {
+            return std::unexpected(binding_error_(
+                BindingErrorKind::PartialProviderMetadata,
+                currentTarget, currentVersion,
+                "canonical binding manifest is missing its binding group"));
+        }
+        const auto kind = dataIt->second.kind.empty()
+            ? std::string_view{infoIt->second.type}
+            : std::string_view{dataIt->second.kind};
+        if (!supported_kind_(kind)) {
+            return std::unexpected(binding_error_(
+                BindingErrorKind::UnsupportedKind,
+                currentTarget, currentVersion,
+                std::format("unsupported legacy member kind '{}'", kind)));
+        }
+
+        const auto incomingIt =
+            incomingEdges.find({currentTarget, currentVersion});
+        if (incomingIt != incomingEdges.end()) {
+            for (const auto& [sourceTarget, sourceVersion] :
+                 incomingIt->second) {
+                if (sourceTarget == currentTarget) {
+                    return std::unexpected(binding_error_(
+                        BindingErrorKind::SelfEdge,
+                        currentTarget, currentVersion,
+                        "legacy binding contains a self-edge"));
+                }
+                const auto& sourceInfo = db.at(sourceTarget);
+                if (!sourceInfo.versions.contains(sourceVersion)) {
+                    return std::unexpected(binding_error_(
+                        BindingErrorKind::VersionNotFound,
+                        sourceTarget, sourceVersion,
+                        "legacy binding source version is missing"));
+                }
+
+                const auto reciprocalIt =
+                    infoIt->second.bindings.find(sourceTarget);
+                if (reciprocalIt == infoIt->second.bindings.end()) {
+                    return std::unexpected(binding_error_(
+                        BindingErrorKind::AsymmetricEdge,
+                        sourceTarget, sourceVersion,
+                        "legacy binding is asymmetric"));
+                }
+                const auto reciprocalVersionIt =
+                    reciprocalIt->second.find(currentVersion);
+                if (reciprocalVersionIt == reciprocalIt->second.end()
+                    || reciprocalVersionIt->second != sourceVersion) {
+                    return std::unexpected(binding_error_(
+                        BindingErrorKind::AsymmetricEdge,
+                        sourceTarget, sourceVersion,
+                        "legacy binding is asymmetric"));
+                }
+            }
+        }
+
+        if (auto selectedIt = selection.members.find(currentTarget);
+            selectedIt != selection.members.end()
+            && selectedIt->second != currentVersion) {
+            return std::unexpected(binding_error_(
+                BindingErrorKind::ConflictingTargetVersion,
+                currentTarget, currentVersion,
+                "legacy graph selects conflicting target versions"));
+        }
+        selection.members[currentTarget] = currentVersion;
+
+        for (const auto& [peerTarget, versions] : infoIt->second.bindings) {
+            auto edgeIt = versions.find(currentVersion);
+            if (edgeIt == versions.end()) continue;
+            const auto& peerVersion = edgeIt->second;
+            if (peerTarget == currentTarget) {
+                return std::unexpected(binding_error_(
+                    BindingErrorKind::SelfEdge,
+                    currentTarget, currentVersion,
+                    "legacy binding contains a self-edge"));
+            }
+
+            auto peerInfoIt = db.find(peerTarget);
+            if (peerInfoIt == db.end()) {
+                return std::unexpected(binding_error_(
+                    BindingErrorKind::TargetNotFound,
+                    peerTarget, peerVersion,
+                    "legacy binding destination target is missing"));
+            }
+            if (!peerInfoIt->second.versions.contains(peerVersion)) {
+                return std::unexpected(binding_error_(
+                    BindingErrorKind::VersionNotFound,
+                    peerTarget, peerVersion,
+                    "legacy binding destination version is missing"));
+            }
+            auto reverseIt = peerInfoIt->second.bindings.find(currentTarget);
+            if (reverseIt == peerInfoIt->second.bindings.end()) {
+                return std::unexpected(binding_error_(
+                    BindingErrorKind::AsymmetricEdge,
+                    peerTarget, peerVersion, "legacy binding is asymmetric"));
+            }
+            auto reverseVersionIt = reverseIt->second.find(peerVersion);
+            if (reverseVersionIt == reverseIt->second.end()
+                || reverseVersionIt->second != currentVersion) {
+                return std::unexpected(binding_error_(
+                    BindingErrorKind::AsymmetricEdge,
+                    peerTarget, peerVersion, "legacy binding is asymmetric"));
+            }
+            if (auto selectedIt = selection.members.find(peerTarget);
+                selectedIt != selection.members.end()
+                && selectedIt->second != peerVersion) {
+                return std::unexpected(binding_error_(
+                    BindingErrorKind::ConflictingTargetVersion,
+                    peerTarget, peerVersion,
+                    "legacy graph selects conflicting target versions"));
+            }
+            pending.emplace_back(peerTarget, peerVersion);
+        }
+    }
+
+    return selection;
+}
+
+}
+
+namespace xlings::xvm {
+
+std::expected<BindingSelection, BindingError>
+resolve_binding_selection(const VersionDB& db,
+                          const std::string& target,
+                          const std::string& version) {
+    BindingSelectionResolver resolver{db};
+    return resolver.resolve(target, version);
+}
+
+std::vector<HeaderAsset> group_header_assets(const VersionDB& db,
+                                             const std::string& target,
+                                             const std::string& version) {
+    auto targetIt = db.find(target);
+    if (targetIt == db.end()) return {};
+    auto versionIt = targetIt->second.versions.find(version);
+    if (versionIt == targetIt->second.versions.end()) return {};
+    const VData& entry = versionIt->second;
+
+    const VData* root = &entry;
+    if (entry.bindingGroup) {
+        const auto& ref = *entry.bindingGroup;
+        if (auto rootTargetIt = db.find(ref.rootTarget);
+            rootTargetIt != db.end()) {
+            if (auto rootVersionIt =
+                    rootTargetIt->second.versions.find(ref.rootVersion);
+                rootVersionIt != rootTargetIt->second.versions.end()) {
+                root = &rootVersionIt->second;
+            }
+        }
+        // A dangling root reference is not repaired here. The selection layer
+        // already refuses such a release, and this is only ever called for
+        // one that resolved -- so falling back to the member's own view is
+        // the conservative answer rather than a second opinion on validity.
+    }
+
+    if (!root->bindingHeaders.empty()) return root->bindingHeaders;
+    if (!entry.includedir.empty()) {
+        return {HeaderAsset{.sourceDir = entry.includedir}};
+    }
+    return {};
+}
+
+LibraryPlacement library_placement(const VersionDB& db,
+                                   const std::string& target,
+                                   const std::string& version) {
+    auto targetIt = db.find(target);
+    if (targetIt == db.end()) return {};
+    auto versionIt = targetIt->second.versions.find(version);
+    if (versionIt == targetIt->second.versions.end()) return {};
+
+    const VInfo& info = targetIt->second;
+    const VData& data = versionIt->second;
+    const auto kind = effective_kind(info, data);
+    if (kind != "lib" || data.path.empty()) return {};
+
+    const auto sourceName = effective_source_name(target, info, data, kind);
+    const auto destinationName =
+        effective_destination_name(target, data, kind, sourceName);
+    if (sourceName.empty() || destinationName.empty()) return {};
+
+    return {
+        .source = (std::filesystem::path(data.path) / sourceName).string(),
+        .name = destinationName,
+    };
+}
+
+bool is_permitted_file_destination(std::string_view destination) {
+    if (destination.empty()) return false;
+    const std::filesystem::path p{destination};
+    if (p.is_absolute()) return false;
+    std::string first;
+    for (const auto& part : p) {
+        if (part == "..") return false;
+        if (first.empty()) first = part.string();
+    }
+    // Windows drive-relative forms ("C:foo") are absolute in spirit.
+    if (destination.size() > 1 && destination[1] == ':') return false;
+    return first == "usr" || first == "etc" || first == "share";
+}
+
+FilePlacement file_placement(const VersionDB& db,
+                             const std::string& target,
+                             const std::string& version) {
+    auto targetIt = db.find(target);
+    if (targetIt == db.end()) return {};
+    auto versionIt = targetIt->second.versions.find(version);
+    if (versionIt == targetIt->second.versions.end()) return {};
+
+    const VData& data = versionIt->second;
+    if (effective_kind(targetIt->second, data) != "files") return {};
+    if (data.path.empty() || data.fileSrc.empty() || data.fileDst.empty()) {
+        return {};
+    }
+    if (!is_permitted_file_destination(data.fileDst)) return {};
+
+    return {
+        .source = (std::filesystem::path(data.path) / data.fileSrc).string(),
+        .destination = data.fileDst,
+    };
+}
+
+bool is_binding_root(const VersionDB& db,
+                     const std::string& target,
+                     const std::string& version) {
+    for (const auto& [peerTarget, peerInfo] : db) {
+        for (const auto& [peerVersion, peerData] : peerInfo.versions) {
+            if (peerTarget == target && peerVersion == version) continue;
+            if (peerData.bindingGroup
+                && peerData.bindingGroup->rootTarget == target
+                && peerData.bindingGroup->rootVersion == version) {
+                return true;
+            }
+        }
+        if (peerTarget == target) continue;
+        // Legacy pairwise edge: the member side records the root it belongs
+        // to, keyed by its own version.
+        const auto edge = peerInfo.bindings.find(target);
+        if (edge == peerInfo.bindings.end()) continue;
+        for (const auto& [_, rootVersion] : edge->second) {
+            if (rootVersion == version) return true;
+        }
+    }
+    return false;
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::xvm {
+
+BindingSelectionResolver::BindingSelectionResolver(const VersionDB& db) : db_(db) {}
+
+[[nodiscard]] std::size_t BindingSelectionResolver::legacy_incoming_index_builds() const {
+    return legacyIncomingIndexBuilds_;
+}
+
+[[nodiscard]] bool LibraryPlacement::empty() const { return source.empty(); }
+
+[[nodiscard]] bool FilePlacement::empty() const { return source.empty(); }
+
+} // namespace xlings::xvm
diff --git a/src/core/xvm/bindings.cppm b/src/core/xvm/bindings.cppm
index efa28982..78e6cb20 100644
--- a/src/core/xvm/bindings.cppm
+++ b/src/core/xvm/bindings.cppm
@@ -43,14 +43,12 @@ struct BindingError {
 
 class BindingSelectionResolver {
 public:
-    explicit BindingSelectionResolver(const VersionDB& db) : db_(db) {}
+    explicit BindingSelectionResolver(const VersionDB& db);
 
     std::expected<BindingSelection, BindingError>
     resolve(const std::string& target, const std::string& version);
 
-    [[nodiscard]] std::size_t legacy_incoming_index_builds() const {
-        return legacyIncomingIndexBuilds_;
-    }
+    [[nodiscard]] std::size_t legacy_incoming_index_builds() const;
 
 private:
     using TargetVersion = std::pair<std::string, std::string>;
@@ -105,7 +103,7 @@ struct LibraryPlacement {
     std::string source;
     std::string name;
 
-    [[nodiscard]] bool empty() const { return source.empty(); }
+    [[nodiscard]] bool empty() const;
 };
 
 // Resolve an entry to its library placement.
@@ -145,7 +143,7 @@ struct FilePlacement {
     std::string source;
     std::string destination;
 
-    [[nodiscard]] bool empty() const { return source.empty(); }
+    [[nodiscard]] bool empty() const;
 };
 
 // Whether a package may write this destination.
@@ -167,265 +165,31 @@ namespace xlings::xvm::detail_ {
 BindingError binding_error_(BindingErrorKind kind,
                             const std::string& target,
                             const std::string& version,
-                            std::string message) {
-    return {
-        .kind = kind,
-        .target = target,
-        .version = version,
-        .message = std::move(message),
-    };
-}
-
-bool same_group_identity_(const BindingGroupRef& lhs,
-                          const BindingGroupRef& rhs) {
-    return lhs.provider == rhs.provider
-        && lhs.providerVersion == rhs.providerVersion
-        && lhs.group == rhs.group;
-}
-
-bool same_group_(const BindingGroupRef& lhs, const BindingGroupRef& rhs) {
-    return same_group_identity_(lhs, rhs)
-        && lhs.rootTarget == rhs.rootTarget
-        && lhs.rootVersion == rhs.rootVersion;
-}
-
-bool supported_kind_(std::string_view kind) {
-    return kind == "program" || kind == "lib" || kind == "group"
-        || kind == "files";
-}
-
-std::optional<std::string_view>
-canonical_manifest_path_(const VData& data) {
-    if (data.bindingMembersDeclared || !data.bindingMembers.empty()) {
-        return "/bindingMembers";
-    }
-    if (data.bindingHeadersDeclared || !data.bindingHeaders.empty()) {
-        return "/bindingHeaders";
-    }
-    return std::nullopt;
-}
-
-bool has_canonical_manifest_(const VData& data) {
-    return canonical_manifest_path_(data).has_value();
-}
+                            std::string message);
 
-BindingError metadata_integrity_error_(
-    const std::string& target,
-    const std::string& version,
-    std::string_view code,
-    std::string_view path) {
-    return binding_error_(
-        BindingErrorKind::MetadataIntegrityIssue,
-        target, version,
-        std::format("binding metadata integrity issue '{}' at '{}'",
-                    code, path));
-}
+bool has_canonical_manifest_(const VData& data);
 
 std::optional<BindingError>
 binding_integrity_error_(const VData& data,
                          const std::string& target,
-                         const std::string& version) {
-    if (data.bindingIntegrityIssues.empty()) return std::nullopt;
-    const auto& issue = data.bindingIntegrityIssues.front();
-    return metadata_integrity_error_(
-        target, version, issue.code, issue.path);
-}
-
-std::string json_pointer_token_(std::string_view token) {
-    std::string escaped;
-    escaped.reserve(token.size());
-    for (const auto ch : token) {
-        if (ch == '~') {
-            escaped += "~0";
-        } else if (ch == '/') {
-            escaped += "~1";
-        } else {
-            escaped += ch;
-        }
-    }
-    return escaped;
-}
-
-std::optional<BindingError>
-root_content_integrity_error_(const VData& root,
-                              const std::string& target,
-                              const std::string& version) {
-    for (const auto& [memberTarget, memberVersion] : root.bindingMembers) {
-        if (memberTarget.empty()) {
-            return metadata_integrity_error_(
-                target, version,
-                "binding-member-target-empty", "/bindingMembers/");
-        }
-        if (memberVersion.empty()) {
-            return metadata_integrity_error_(
-                target, version,
-                "binding-member-version-empty",
-                "/bindingMembers/" + json_pointer_token_(memberTarget));
-        }
-    }
-    for (std::size_t index = 0;
-         index < root.bindingHeaders.size(); ++index) {
-        if (root.bindingHeaders[index].sourceDir.empty()) {
-            return metadata_integrity_error_(
-                target, version,
-                "binding-header-source-dir-empty",
-                std::format("/bindingHeaders/{}/sourceDir", index));
-        }
-    }
-    return std::nullopt;
-}
-
-std::optional<std::string_view>
-invalid_group_identity_path_(const BindingGroupRef& group) {
-    if (group.provider.empty()) return "/bindingGroup/provider";
-    if (group.providerVersion.empty()) return "/bindingGroup/version";
-    if (group.group.empty()) return "/bindingGroup/group";
-    if (group.rootTarget.empty()) return "/bindingGroup/rootTarget";
-    if (group.rootVersion.empty()) return "/bindingGroup/rootVersion";
-    return std::nullopt;
-}
+                         const std::string& version);
 
 std::optional<BindingError>
 group_identity_integrity_error_(const BindingGroupRef& group,
                                 const std::string& target,
-                                const std::string& version) {
-    const auto invalidPath = invalid_group_identity_path_(group);
-    if (!invalidPath) return std::nullopt;
-    return metadata_integrity_error_(
-        target, version, "binding-group-field-invalid", *invalidPath);
-}
+                                const std::string& version);
 
 std::optional<BindingError>
 non_root_metadata_error_(const VData& data,
                          const std::string& target,
                          const std::string& version,
-                         const BindingGroupRef& group) {
-    if (target == group.rootTarget && version == group.rootVersion) {
-        return std::nullopt;
-    }
-    const auto metadataPath = canonical_manifest_path_(data);
-    if (!metadataPath) return std::nullopt;
-    return metadata_integrity_error_(
-        target, version, "binding-metadata-on-non-root", *metadataPath);
-}
+                         const BindingGroupRef& group);
 
 std::expected<BindingSelection, BindingError>
 resolve_provider_group_(const VersionDB& db,
                         const std::string& target,
                         const std::string& version,
-                        const BindingGroupRef& group) {
-    auto rootInfoIt = db.find(group.rootTarget);
-    if (rootInfoIt == db.end()) {
-        return std::unexpected(binding_error_(
-            BindingErrorKind::TargetNotFound,
-            group.rootTarget, group.rootVersion,
-            "binding root target is missing"));
-    }
-    auto rootIt = rootInfoIt->second.versions.find(group.rootVersion);
-    if (rootIt == rootInfoIt->second.versions.end()) {
-        return std::unexpected(binding_error_(
-            BindingErrorKind::VersionNotFound,
-            group.rootTarget, group.rootVersion,
-            "binding root version is missing"));
-    }
-
-    const auto& root = rootIt->second;
-    if (auto error = binding_integrity_error_(
-            root, group.rootTarget, group.rootVersion)) {
-        return std::unexpected(std::move(*error));
-    }
-    if (root.bindingGroup) {
-        if (auto error = group_identity_integrity_error_(
-                *root.bindingGroup,
-                group.rootTarget, group.rootVersion)) {
-            return std::unexpected(std::move(*error));
-        }
-    }
-    if (!root.bindingGroup
-        || root.bindingGroup->rootTarget != group.rootTarget
-        || root.bindingGroup->rootVersion != group.rootVersion) {
-        return std::unexpected(binding_error_(
-            BindingErrorKind::RootReferenceMismatch,
-            group.rootTarget, group.rootVersion,
-            "binding root does not reference itself"));
-    }
-    if (!same_group_identity_(*root.bindingGroup, group)) {
-        return std::unexpected(binding_error_(
-            BindingErrorKind::GroupIdentityMismatch,
-            group.rootTarget, group.rootVersion,
-            "binding root group identity is inconsistent"));
-    }
-    if (auto error = root_content_integrity_error_(
-            root, group.rootTarget, group.rootVersion)) {
-        return std::unexpected(std::move(*error));
-    }
-
-    auto startIt = root.bindingMembers.find(target);
-    if (startIt == root.bindingMembers.end() || startIt->second != version) {
-        return std::unexpected(binding_error_(
-            BindingErrorKind::StartMemberMissing,
-            target, version, "starting member is absent from binding manifest"));
-    }
-    auto manifestRootIt = root.bindingMembers.find(group.rootTarget);
-    if (manifestRootIt == root.bindingMembers.end()
-        || manifestRootIt->second != group.rootVersion) {
-        return std::unexpected(binding_error_(
-            BindingErrorKind::RootMissingFromManifest,
-            group.rootTarget, group.rootVersion,
-            "binding root is absent from binding manifest"));
-    }
-
-    for (const auto& [memberTarget, memberVersion] : root.bindingMembers) {
-        auto memberInfoIt = db.find(memberTarget);
-        if (memberInfoIt == db.end()) {
-            return std::unexpected(binding_error_(
-                BindingErrorKind::TargetNotFound,
-                memberTarget, memberVersion,
-                "binding member target is missing"));
-        }
-        auto memberIt = memberInfoIt->second.versions.find(memberVersion);
-        if (memberIt == memberInfoIt->second.versions.end()) {
-            return std::unexpected(binding_error_(
-                BindingErrorKind::VersionNotFound,
-                memberTarget, memberVersion,
-                "binding member version is missing"));
-        }
-        if (auto error = binding_integrity_error_(
-                memberIt->second, memberTarget, memberVersion)) {
-            return std::unexpected(std::move(*error));
-        }
-        if (memberIt->second.bindingGroup) {
-            if (auto error = group_identity_integrity_error_(
-                    *memberIt->second.bindingGroup,
-                    memberTarget, memberVersion)) {
-                return std::unexpected(std::move(*error));
-            }
-        }
-        if (!memberIt->second.bindingGroup
-            || !same_group_(*memberIt->second.bindingGroup, group)) {
-            return std::unexpected(binding_error_(
-                BindingErrorKind::MemberReferenceMismatch,
-                memberTarget, memberVersion,
-                "binding member back-reference is inconsistent"));
-        }
-        if (auto error = non_root_metadata_error_(
-                memberIt->second, memberTarget, memberVersion, group)) {
-            return std::unexpected(std::move(*error));
-        }
-        if (!supported_kind_(memberIt->second.kind)) {
-            return std::unexpected(binding_error_(
-                BindingErrorKind::UnsupportedKind,
-                memberTarget, memberVersion,
-                std::format("unsupported provider-group member kind '{}'",
-                            memberIt->second.kind)));
-        }
-    }
-
-    return BindingSelection{
-        .members = root.bindingMembers,
-        .source = BindingSource::ProviderGroup,
-    };
-}
+                        const BindingGroupRef& group);
 
 std::expected<BindingSelection, BindingError>
 resolve_legacy_graph_(const VersionDB& db,
@@ -434,164 +198,7 @@ resolve_legacy_graph_(const VersionDB& db,
                       const std::map<
                           std::pair<std::string, std::string>,
                           std::vector<std::pair<
-                              std::string, std::string>>>& incomingEdges) {
-    BindingSelection selection{
-        .source = BindingSource::LegacyGraph,
-    };
-    std::vector<std::pair<std::string, std::string>> pending{
-        {target, version},
-    };
-    std::set<std::pair<std::string, std::string>> visited;
-    while (!pending.empty()) {
-        auto [currentTarget, currentVersion] = std::move(pending.back());
-        pending.pop_back();
-        if (!visited.emplace(currentTarget, currentVersion).second) continue;
-
-        auto infoIt = db.find(currentTarget);
-        if (infoIt == db.end()) {
-            return std::unexpected(binding_error_(
-                BindingErrorKind::TargetNotFound,
-                currentTarget, currentVersion,
-                "legacy target is missing"));
-        }
-        auto dataIt = infoIt->second.versions.find(currentVersion);
-        if (dataIt == infoIt->second.versions.end()) {
-            return std::unexpected(binding_error_(
-                BindingErrorKind::VersionNotFound,
-                currentTarget, currentVersion,
-                "legacy version is missing"));
-        }
-        if (auto error = binding_integrity_error_(
-                dataIt->second, currentTarget, currentVersion)) {
-            return std::unexpected(std::move(*error));
-        }
-        if (dataIt->second.bindingGroup) {
-            if (auto error = group_identity_integrity_error_(
-                    *dataIt->second.bindingGroup,
-                    currentTarget, currentVersion)) {
-                return std::unexpected(std::move(*error));
-            }
-            return std::unexpected(binding_error_(
-                BindingErrorKind::ProviderMetadataInLegacyGraph,
-                currentTarget, currentVersion,
-                "provider-aware version cannot participate in a legacy graph"));
-        }
-        if (has_canonical_manifest_(dataIt->second)) {
-            return std::unexpected(binding_error_(
-                BindingErrorKind::PartialProviderMetadata,
-                currentTarget, currentVersion,
-                "canonical binding manifest is missing its binding group"));
-        }
-        const auto kind = dataIt->second.kind.empty()
-            ? std::string_view{infoIt->second.type}
-            : std::string_view{dataIt->second.kind};
-        if (!supported_kind_(kind)) {
-            return std::unexpected(binding_error_(
-                BindingErrorKind::UnsupportedKind,
-                currentTarget, currentVersion,
-                std::format("unsupported legacy member kind '{}'", kind)));
-        }
-
-        const auto incomingIt =
-            incomingEdges.find({currentTarget, currentVersion});
-        if (incomingIt != incomingEdges.end()) {
-            for (const auto& [sourceTarget, sourceVersion] :
-                 incomingIt->second) {
-                if (sourceTarget == currentTarget) {
-                    return std::unexpected(binding_error_(
-                        BindingErrorKind::SelfEdge,
-                        currentTarget, currentVersion,
-                        "legacy binding contains a self-edge"));
-                }
-                const auto& sourceInfo = db.at(sourceTarget);
-                if (!sourceInfo.versions.contains(sourceVersion)) {
-                    return std::unexpected(binding_error_(
-                        BindingErrorKind::VersionNotFound,
-                        sourceTarget, sourceVersion,
-                        "legacy binding source version is missing"));
-                }
-
-                const auto reciprocalIt =
-                    infoIt->second.bindings.find(sourceTarget);
-                if (reciprocalIt == infoIt->second.bindings.end()) {
-                    return std::unexpected(binding_error_(
-                        BindingErrorKind::AsymmetricEdge,
-                        sourceTarget, sourceVersion,
-                        "legacy binding is asymmetric"));
-                }
-                const auto reciprocalVersionIt =
-                    reciprocalIt->second.find(currentVersion);
-                if (reciprocalVersionIt == reciprocalIt->second.end()
-                    || reciprocalVersionIt->second != sourceVersion) {
-                    return std::unexpected(binding_error_(
-                        BindingErrorKind::AsymmetricEdge,
-                        sourceTarget, sourceVersion,
-                        "legacy binding is asymmetric"));
-                }
-            }
-        }
-
-        if (auto selectedIt = selection.members.find(currentTarget);
-            selectedIt != selection.members.end()
-            && selectedIt->second != currentVersion) {
-            return std::unexpected(binding_error_(
-                BindingErrorKind::ConflictingTargetVersion,
-                currentTarget, currentVersion,
-                "legacy graph selects conflicting target versions"));
-        }
-        selection.members[currentTarget] = currentVersion;
-
-        for (const auto& [peerTarget, versions] : infoIt->second.bindings) {
-            auto edgeIt = versions.find(currentVersion);
-            if (edgeIt == versions.end()) continue;
-            const auto& peerVersion = edgeIt->second;
-            if (peerTarget == currentTarget) {
-                return std::unexpected(binding_error_(
-                    BindingErrorKind::SelfEdge,
-                    currentTarget, currentVersion,
-                    "legacy binding contains a self-edge"));
-            }
-
-            auto peerInfoIt = db.find(peerTarget);
-            if (peerInfoIt == db.end()) {
-                return std::unexpected(binding_error_(
-                    BindingErrorKind::TargetNotFound,
-                    peerTarget, peerVersion,
-                    "legacy binding destination target is missing"));
-            }
-            if (!peerInfoIt->second.versions.contains(peerVersion)) {
-                return std::unexpected(binding_error_(
-                    BindingErrorKind::VersionNotFound,
-                    peerTarget, peerVersion,
-                    "legacy binding destination version is missing"));
-            }
-            auto reverseIt = peerInfoIt->second.bindings.find(currentTarget);
-            if (reverseIt == peerInfoIt->second.bindings.end()) {
-                return std::unexpected(binding_error_(
-                    BindingErrorKind::AsymmetricEdge,
-                    peerTarget, peerVersion, "legacy binding is asymmetric"));
-            }
-            auto reverseVersionIt = reverseIt->second.find(peerVersion);
-            if (reverseVersionIt == reverseIt->second.end()
-                || reverseVersionIt->second != currentVersion) {
-                return std::unexpected(binding_error_(
-                    BindingErrorKind::AsymmetricEdge,
-                    peerTarget, peerVersion, "legacy binding is asymmetric"));
-            }
-            if (auto selectedIt = selection.members.find(peerTarget);
-                selectedIt != selection.members.end()
-                && selectedIt->second != peerVersion) {
-                return std::unexpected(binding_error_(
-                    BindingErrorKind::ConflictingTargetVersion,
-                    peerTarget, peerVersion,
-                    "legacy graph selects conflicting target versions"));
-            }
-            pending.emplace_back(peerTarget, peerVersion);
-        }
-    }
-
-    return selection;
-}
+                              std::string, std::string>>>& incomingEdges);
 
 }  // namespace xlings::xvm::detail_
 
@@ -663,125 +270,24 @@ BindingSelectionResolver::resolve(const std::string& target,
 std::expected<BindingSelection, BindingError>
 resolve_binding_selection(const VersionDB& db,
                           const std::string& target,
-                          const std::string& version) {
-    BindingSelectionResolver resolver{db};
-    return resolver.resolve(target, version);
-}
+                          const std::string& version);
 
 std::vector<HeaderAsset> group_header_assets(const VersionDB& db,
                                              const std::string& target,
-                                             const std::string& version) {
-    auto targetIt = db.find(target);
-    if (targetIt == db.end()) return {};
-    auto versionIt = targetIt->second.versions.find(version);
-    if (versionIt == targetIt->second.versions.end()) return {};
-    const VData& entry = versionIt->second;
-
-    const VData* root = &entry;
-    if (entry.bindingGroup) {
-        const auto& ref = *entry.bindingGroup;
-        if (auto rootTargetIt = db.find(ref.rootTarget);
-            rootTargetIt != db.end()) {
-            if (auto rootVersionIt =
-                    rootTargetIt->second.versions.find(ref.rootVersion);
-                rootVersionIt != rootTargetIt->second.versions.end()) {
-                root = &rootVersionIt->second;
-            }
-        }
-        // A dangling root reference is not repaired here. The selection layer
-        // already refuses such a release, and this is only ever called for
-        // one that resolved -- so falling back to the member's own view is
-        // the conservative answer rather than a second opinion on validity.
-    }
-
-    if (!root->bindingHeaders.empty()) return root->bindingHeaders;
-    if (!entry.includedir.empty()) {
-        return {HeaderAsset{.sourceDir = entry.includedir}};
-    }
-    return {};
-}
+                                             const std::string& version);
 
 LibraryPlacement library_placement(const VersionDB& db,
                                    const std::string& target,
-                                   const std::string& version) {
-    auto targetIt = db.find(target);
-    if (targetIt == db.end()) return {};
-    auto versionIt = targetIt->second.versions.find(version);
-    if (versionIt == targetIt->second.versions.end()) return {};
-
-    const VInfo& info = targetIt->second;
-    const VData& data = versionIt->second;
-    const auto kind = effective_kind(info, data);
-    if (kind != "lib" || data.path.empty()) return {};
-
-    const auto sourceName = effective_source_name(target, info, data, kind);
-    const auto destinationName =
-        effective_destination_name(target, data, kind, sourceName);
-    if (sourceName.empty() || destinationName.empty()) return {};
-
-    return {
-        .source = (std::filesystem::path(data.path) / sourceName).string(),
-        .name = destinationName,
-    };
-}
+                                   const std::string& version);
 
-bool is_permitted_file_destination(std::string_view destination) {
-    if (destination.empty()) return false;
-    const std::filesystem::path p{destination};
-    if (p.is_absolute()) return false;
-    std::string first;
-    for (const auto& part : p) {
-        if (part == "..") return false;
-        if (first.empty()) first = part.string();
-    }
-    // Windows drive-relative forms ("C:foo") are absolute in spirit.
-    if (destination.size() > 1 && destination[1] == ':') return false;
-    return first == "usr" || first == "etc" || first == "share";
-}
+bool is_permitted_file_destination(std::string_view destination);
 
 FilePlacement file_placement(const VersionDB& db,
                              const std::string& target,
-                             const std::string& version) {
-    auto targetIt = db.find(target);
-    if (targetIt == db.end()) return {};
-    auto versionIt = targetIt->second.versions.find(version);
-    if (versionIt == targetIt->second.versions.end()) return {};
-
-    const VData& data = versionIt->second;
-    if (effective_kind(targetIt->second, data) != "files") return {};
-    if (data.path.empty() || data.fileSrc.empty() || data.fileDst.empty()) {
-        return {};
-    }
-    if (!is_permitted_file_destination(data.fileDst)) return {};
-
-    return {
-        .source = (std::filesystem::path(data.path) / data.fileSrc).string(),
-        .destination = data.fileDst,
-    };
-}
+                             const std::string& version);
 
 bool is_binding_root(const VersionDB& db,
                      const std::string& target,
-                     const std::string& version) {
-    for (const auto& [peerTarget, peerInfo] : db) {
-        for (const auto& [peerVersion, peerData] : peerInfo.versions) {
-            if (peerTarget == target && peerVersion == version) continue;
-            if (peerData.bindingGroup
-                && peerData.bindingGroup->rootTarget == target
-                && peerData.bindingGroup->rootVersion == version) {
-                return true;
-            }
-        }
-        if (peerTarget == target) continue;
-        // Legacy pairwise edge: the member side records the root it belongs
-        // to, keyed by its own version.
-        const auto edge = peerInfo.bindings.find(target);
-        if (edge == peerInfo.bindings.end()) continue;
-        for (const auto& [_, rootVersion] : edge->second) {
-            if (rootVersion == version) return true;
-        }
-    }
-    return false;
-}
+                     const std::string& version);
 
 }  // namespace xlings::xvm
diff --git a/src/core/xvm/commands.cpp b/src/core/xvm/commands.cpp
new file mode 100644
index 00000000..8922a7bc
--- /dev/null
+++ b/src/core/xvm/commands.cpp
@@ -0,0 +1,759 @@
+module xlings.core.xvm.commands;
+
+import std;
+import xlings.core.common;
+import xlings.core.config;
+import xlings.core.log;
+import xlings.core.palette;
+import xlings.core.subos.manifest;
+import xlings.platform;
+import xlings.runtime;
+import xlings.libs.json;
+import xlings.core.semver;
+import xlings.core.entry_binary;
+import xlings.core.xself;
+import xlings.core.xself.repair;
+import xlings.core.xvm.types;
+import xlings.core.xvm.db;
+import xlings.core.xvm.lock;
+import xlings.core.xvm.bindings;
+import xlings.core.xvm.inspect;
+import xlings.core.xvm.errors;
+import xlings.core.xvm.switch_plan;
+import xlings.core.xvm.shim;
+
+namespace xlings::xvm {
+
+void create_link_(const fs::path& src, const fs::path& dst) {
+    std::error_code ec;
+#if defined(_WIN32)
+    if (fs::is_directory(src)) {
+        // Use directory junction on Windows (no admin required)
+        platform::create_directory_link(dst.string(), src.string());
+    } else {
+        fs::create_hard_link(src, dst, ec);
+        if (ec) {
+            ec.clear();
+            fs::copy_file(src, dst, fs::copy_options::overwrite_existing, ec);
+        }
+    }
+#else
+    fs::create_symlink(src, dst, ec);
+#endif
+    if (ec) log::warn("[xvm] link failed: {} -> {}",
+                      Config::display_path(dst), Config::display_path(src));
+}
+
+fs::path header_destination_(const HeaderAsset& asset,
+                             const fs::path& sysroot_include) {
+    return asset.destinationPrefix.empty()
+        ? sysroot_include
+        : sysroot_include / fs::path(asset.destinationPrefix);
+}
+
+bool sysroot_source_is_local_(const fs::path& src) {
+    std::error_code ec;
+    const auto canon = fs::weakly_canonical(src, ec);
+    const auto& probe = ec ? src : canon;
+    const auto under = [&](const fs::path& root) {
+        if (root.empty()) return false;
+        std::error_code rec;
+        auto canonRoot = fs::weakly_canonical(root, rec);
+        const auto& r = rec ? root : canonRoot;
+        auto a = probe.string(), b = r.string();
+        return a == b || a.starts_with(b + static_cast<char>(fs::path::preferred_separator))
+            || a.starts_with(b + "/");
+    };
+    const auto& p = Config::paths();
+    return under(p.dataDir) || under(p.homeDir);
+}
+
+void install_headers(const std::string& includedir, const fs::path& sysroot_include) {
+    fs::create_directories(sysroot_include);
+    std::error_code ec;
+    fs::path src(includedir);
+    if (!fs::exists(src, ec)) return;
+    if (!sysroot_source_is_local_(src)) {
+        // Warned, not refused. A recipe may legitimately expose headers from
+        // outside the store (a wrapper around system headers is the obvious
+        // one), and refusing would break packages that work today. What is
+        // NOT legitimate is the run that produced the measured damage, and
+        // this is the moment it becomes visible instead of surfacing weeks
+        // later as a missing header from a subos the user is not even in.
+        log::warn("[xvm] linking headers from outside this home: {}",
+                  Config::display_path(src));
+        log::warn("  into sysroot: {}", Config::display_path(sysroot_include));
+        log::warn("  these links outlive the run that made them; "
+                  "`xlings self doctor --fix` removes them once they dangle");
+    }
+    for (auto& entry : platform::dir_entries(src)) {
+        auto target = sysroot_include / entry.path().filename();
+        // Already pointing at this exact source: leave it alone.
+        // `xlings use` now re-materializes the active release on every
+        // invocation so it can repair a sysroot that drifted, and
+        // remove-then-relink would open a window on every one of those
+        // calls where the header is simply absent -- long enough for a
+        // concurrent build to fail on it. equivalent() covers symlinks,
+        // Windows junctions and hard links alike; a copy fallback compares
+        // unequal and is relinked, which is correct.
+        std::error_code sameEc;
+        if (std::filesystem::equivalent(target, entry.path(), sameEc)
+            && !sameEc) {
+            continue;
+        }
+        if (fs::exists(target, ec) || fs::is_symlink(target, ec)) {
+            log::debug("[xvm] overwriting header: {}", entry.path().filename().string());
+            fs::remove_all(target, ec);
+        }
+        create_link_(entry.path(), target);
+    }
+}
+
+void remove_headers(const std::string& includedir, const fs::path& sysroot_include) {
+    if (includedir.empty()) return;
+    fs::path src(includedir);
+    std::error_code ec;
+    if (!fs::exists(src, ec)) return;
+    for (auto& entry : platform::dir_entries(src)) {
+        auto target = sysroot_include / entry.path().filename();
+        if (fs::is_symlink(target, ec)) {
+            fs::remove(target, ec);
+#if defined(_WIN32)
+        } else if (fs::exists(target, ec)) {
+            // On Windows, directory junctions appear as dirs, not symlinks
+            fs::remove_all(target, ec);
+#endif
+        }
+    }
+}
+
+void install_headers(const HeaderAsset& asset, const fs::path& sysroot_include) {
+    install_headers(asset.sourceDir, header_destination_(asset, sysroot_include));
+}
+
+void remove_headers(const HeaderAsset& asset, const fs::path& sysroot_include) {
+    const auto destination = header_destination_(asset, sysroot_include);
+    remove_headers(asset.sourceDir, destination);
+    // A prefix directory that only ever held this release's links is litter
+    // once they are gone. remove() on a non-empty directory fails, so this
+    // cannot take anything else with it.
+    if (!asset.destinationPrefix.empty()) {
+        std::error_code ec;
+        fs::remove(destination, ec);
+    }
+}
+
+void place_asset(const std::string& source, const fs::path& destination) {
+    if (source.empty() || destination.empty()) return;
+    std::error_code ec;
+    fs::path src(source);
+    if (!fs::exists(src, ec)) {
+        log::debug("[xvm] asset source missing, not placed: {}",
+                   Config::display_path(source));
+        return;
+    }
+    fs::create_directories(destination.parent_path(), ec);
+
+    // Already pointing at this exact file: leave it alone. Keeps the repeated
+    // re-materialization that `use` performs down to a stat.
+    std::error_code sameEc;
+    if (fs::equivalent(destination, src, sameEc) && !sameEc) return;
+
+    const auto staging =
+        destination.parent_path()
+        / (destination.filename().string() + ".xlings-new");
+    fs::remove_all(staging, ec);
+    create_link_(src, staging);
+    if (!fs::exists(staging, ec) && !fs::is_symlink(staging, ec)) {
+        log::warn("[xvm] could not stage asset: {}",
+                  Config::display_path(destination));
+        return;
+    }
+    ec.clear();
+    fs::rename(staging, destination, ec);
+    if (ec) {
+        // Platforms without an atomic replace for this entry kind. Accept the
+        // window rather than leave the staging file behind.
+        std::error_code rmEc;
+        fs::remove_all(destination, rmEc);
+        ec.clear();
+        fs::rename(staging, destination, ec);
+        if (ec) {
+            fs::remove_all(staging, rmEc);
+            log::warn("[xvm] could not place asset {}: {}",
+                      Config::display_path(destination), ec.message());
+        }
+    }
+}
+
+void remove_asset(const fs::path& destination) {
+    if (destination.empty()) return;
+    std::error_code ec;
+    if (fs::is_symlink(destination, ec) || fs::exists(destination, ec)) {
+        fs::remove_all(destination, ec);
+    }
+}
+
+void place_library(const std::string& source,
+                   const std::string& name,
+                   const fs::path& sysroot_lib) {
+    if (name.empty()) return;
+    place_asset(source, sysroot_lib / name);
+}
+
+void remove_library(const std::string& name, const fs::path& sysroot_lib) {
+    if (name.empty()) return;
+    remove_asset(sysroot_lib / name);
+}
+
+bool runtime_activation_refused_(const VersionDB& db,
+                                 const std::string& target,
+                                 const std::string& requestedVersion) {
+    namespace mf = xlings::subos::manifest;
+
+    const auto doc = mf::read_document(Config::subos_scope().root);
+    if (!doc) return false;
+    const auto info = mf::parse(*doc);
+    if (!mf::is_binding(info.runtime)
+        || target != mf::binding_name(info.runtime)) {
+        return false;
+    }
+
+    const auto it = db.find(target);
+    if (it == db.end() || it->second.versions.empty()) return false;
+    const auto resolved = requestedVersion == "latest"
+        ? pick_highest_version(it->second.versions)
+        : match_version(db, target, requestedVersion);
+    if (resolved.empty()) return false;
+
+    bool payloadExists = false;
+    if (const auto* data = get_vdata(db, target, resolved);
+        data && !data->path.empty()) {
+        std::error_code ec;
+        const auto expanded = expand_path(
+            data->path, Config::paths().homeDir.string());
+        payloadExists = fs::exists(expanded, ec) && !ec;
+    }
+
+    const auto mismatch = mf::check_runtime_activation(
+        info, resolved, payloadExists);
+    if (!mismatch) return false;
+
+    const auto prospective = mismatch->active.empty()
+        ? std::format("{}@{}", target, resolved) : mismatch->active;
+    if (mismatch->payloadMissing
+        && prospective == mismatch->declared) {
+        log::error("[xlings:use] runtime activation refused: {} has no "
+                   "payload", mismatch->declared);
+        log::error("  nothing was changed");
+        log::error("  hint: reinstall it with `xlings install {} --force`",
+                   mismatch->declared);
+        return true;
+    }
+
+    log::error("[xlings:use] runtime activation refused: this SubOS "
+               "declares {}, but the requested runtime is {}",
+               mismatch->declared, prospective);
+    log::error("  nothing was changed");
+    // Two ways out, and both stay inside this SubOS. Sending the user to
+    // `subos new` implies neither exists, which was never true: activating the
+    // DECLARED version is exactly what this guard permits.
+    log::error("  hint: adopt what this SubOS runs -- `xlings self doctor --fix`");
+    log::error("        or migrate to it -- `xlings install {}` then "
+               "`xlings use {} {}`",
+               mismatch->declared, target, mf::binding_version(mismatch->declared));
+    return true;
+}
+
+int cmd_use(const std::string& target, const std::string& version, EventStream& stream, bool strict) {
+    // Serialize against any other xlings mutating this home, then re-read
+    // state under the lock: Config loaded it at process start, outside the
+    // lock, so acting on that snapshot is how two commands lose each other's
+    // work. See xvm/lock.cppm.
+    auto stateLock = xvm::acquire_state_lock(Config::paths().homeDir);
+    if (!stateLock) {
+        log::error("{}", stateLock.error());
+        return 1;
+    }
+    Config::reload_state();
+
+    if (runtime_activation_refused_(Config::versions(), target, version)) {
+        return 1;
+    }
+
+    // Self-heal a dangling legacy edge before planning anything.
+    //
+    // State written by <= 0.4.69 can carry a pairwise edge pointing at a
+    // version that is not registered. Such an edge describes no member
+    // anyone could switch to -- it can only make the release unresolvable --
+    // so dropping it needs no guessing, which is exactly why it does not
+    // need the user's permission either.
+    //
+    // Until now it was reported by doctor and only repaired by
+    // `doctor --fix`, which meant an upgraded user hit a refusal from `use`
+    // with no idea that a second command existed. Repairing it here makes
+    // the upgrade what it was supposed to be: silent. doctor keeps the
+    // report and the flag for anyone inspecting rather than switching.
+    if (auto pruning = plan_dangling_edge_pruning(Config::versions());
+        !pruning.empty()) {
+        auto& mutableDb = Config::versions_mut();
+        const auto dropped =
+            apply_dangling_edge_pruning(mutableDb, pruning);
+        if (dropped > 0) {
+            Config::save_versions();
+            log::debug("[xvm] pruned {} dangling binding edge(s) written by "
+                       "an older xlings", dropped);
+        }
+    }
+
+    auto db = Config::versions();
+    auto& p  = Config::paths();
+
+    if (!has_target(db, target)) {
+        log::error("[xlings:use] '{}' not found in version database", target);
+        log::error("  hint: install it first with `xlings install {}`", target);
+        return 1;
+    }
+
+    // "latest" means pick the highest available version.
+    std::string resolved;
+    if (version == "latest") {
+        // Scope-aware: pick_highest_version strips the "<scope>:" prefix (e.g.
+        // the bootstrap "local:0.4.47") before comparing by numeric semver, so
+        // a higher real release (e.g. 0.4.52) wins. semver::sort_desc alone
+        // cannot parse "local:..." and falls back to lexicographic order, where
+        // "local:0.4.47" wrongly beats "0.4.52" — the bug that made
+        // `xlings self update` install the new version yet stay on the old
+        // local one (xlings -> local:0.4.47).
+        auto it = db.find(target);
+        if (it == db.end() || it->second.versions.empty()) {
+            log::error("no versions installed for '{}'", target);
+            return 1;
+        }
+        resolved = pick_highest_version(it->second.versions);
+    } else {
+        // Fuzzy match version
+        resolved = match_version(db, target, version);
+    }
+
+    if (resolved.empty()) {
+        log::error("version '{}' not found for '{}'", version, target);
+        auto all = get_all_versions(db, target);
+        if (!all.empty()) {
+            std::string avail;
+            for (auto& v : all) {
+                if (!avail.empty()) avail += ", ";
+                avail += v;
+            }
+            log::error("  available: {}", avail);
+        }
+        return 1;
+    }
+
+    log::debug("fuzzy version match: {} -> {}", version, resolved);
+
+    // A version registered somewhere in this home is not a version this subos
+    // can use.
+    //
+    // `use` used to opt the current subos in silently whenever the payload
+    // existed anywhere (auto-add, 0.4.19+), on the reasoning that the payload
+    // is shared so activation is free. That is true of a self-contained
+    // package and false of everything with a dependency: gcc's glibc is not a
+    // member of gcc's release, and the versions DB records no dependency
+    // information at all, so activating gcc here activated exactly gcc. The
+    // result reported success, put a working `g++` on PATH, printed the right
+    // `-print-sysroot` -- and could not compile, because `usr/include` was
+    // empty. Nothing said so.
+    //
+    // `use` cannot fix that: it cannot even name what is missing. So it stops
+    // pretending to. Switching stays what it says it is -- moving between
+    // versions this subos has -- and getting a version into a subos belongs to
+    // `install`, which resolves dependencies and materialises them.
+    if (filter_to_subos_installed_(target, {resolved}).empty()) {
+        const auto scope = Config::subos_scope().name;
+        log::error("[xlings:use] '{}' is not installed in this subos ({})",
+                   target, scope.empty() ? "default" : scope);
+        log::error("  nothing was changed");
+        log::error("  hint: install it here first with `xlings install {}@{}`",
+                   target, resolved);
+        return 1;
+    }
+
+    // Resolve the whole release before touching anything.
+    //
+    // This used to walk the binding edges by hand, keyed by target rather
+    // than by (target, version), and without checking that what it reached
+    // actually existed. A stale edge would take it to a version with no
+    // VData, which it then wrote into the active workspace -- the shim
+    // failed later, far from the command that caused it. Header and library
+    // switching ran *before* that walk and only for the entry target, so a
+    // failure part-way through left the sysroot holding one release and the
+    // workspace claiming another.
+    //
+    // resolve_binding_selection validates the whole group and fails closed.
+    // Running it first means a bad group costs the user an error message
+    // instead of a half-switched toolchain.
+    auto workspace = Config::effective_workspace();
+    auto plan = plan_use_switch(db, workspace, target, resolved);
+    if (!plan) {
+        log::error("{}", render(plan.error(), true));
+        return 1;
+    }
+    const auto& to_switch = plan->members;
+
+    // A program the outgoing release had and this one does not keeps
+    // resolving to the release being left -- see StrandedMember. `--strict`
+    // is for callers that would rather not switch at all than end up holding
+    // two releases, and it has to refuse HERE, while nothing has moved yet.
+    //
+    // `stranded` only ever holds members of the SAME package (the planner
+    // sorts a package switch into retainedByOldPackage instead), so this can
+    // no longer refuse a move between two distributions of one tool -- a
+    // refusal the user could not have satisfied, since the two packages have
+    // no name in common to move first.
+    //
+    // Always lists every entry, verbose or not: this is the error path, and
+    // the reason for a refusal is not a detail.
+    if (strict && !plan->stranded.empty()) {
+        log::error("[xlings:use] --strict: not switching {} to {}",
+                   target, resolved);
+        log::error("  {} name(s) would stay on the old release:",
+                   plan->stranded.size());
+        for (const auto& member : plan->stranded) {
+            if (member.kind == "program") {
+                log::error("    {} (still {})", member.target, member.version);
+            } else {
+                log::error("    {} (still {}, {})", member.target,
+                           member.version, member.kind);
+            }
+        }
+        log::error("  hint: drop --strict, or move each one first");
+        return 1;
+    }
+
+    // Everything above this line is a decision; everything below changes the
+    // filesystem. Members that are already where they belong emit no change.
+    auto sysroot_include = p.subosDir / "usr" / "include";
+    // `<subos>/lib`, which is where the install path has always put
+    // libraries (`Config::paths().libDir`) and where they actually are: 94
+    // entries on a real installation, against one on `<subos>/usr/lib`.
+    // This line used to read `usr/lib`, and the disagreement was invisible
+    // because the switch side never emitted any library work at all --
+    // `VData::libdir` has no writer. Making libraries switch without fixing
+    // it would have started filling a second, unused directory.
+    auto sysroot_lib     = p.libDir;
+    // Headers first, and as two whole passes rather than per member: they are
+    // an asset of the release, not of any one member of it. Interleaving the
+    // passes -- remove one member's, install the next member's -- let the
+    // outgoing release's removal delete a link the incoming release had
+    // already put down, for every header name the two versions share. The
+    // plan has the two lists deduplicated and disjoint already.
+    for (const auto& asset : plan->removeHeaders) {
+        remove_headers(asset, sysroot_include);
+    }
+    for (const auto& asset : plan->installHeaders) {
+        install_headers(asset, sysroot_include);
+    }
+
+    for (const auto& change : plan->switches) {
+        if (!change.removeLibName.empty())
+            remove_library(change.removeLibName, sysroot_lib);
+        if (!change.installLibSource.empty())
+            place_library(change.installLibSource, change.installLibName,
+                          sysroot_lib);
+        // File assets carry their own destination, relative to the subos
+        // root, so they are joined here rather than assumed into a fixed dir.
+        if (!change.removeFileDest.empty())
+            remove_asset(p.subosDir / change.removeFileDest);
+        if (!change.installFileSource.empty())
+            place_asset(change.installFileSource,
+                        p.subosDir / change.installFileDest);
+        log::debug("switching {}: {} -> {}", change.target,
+                   change.previousVersion.empty() ? "(none)"
+                                                  : change.previousVersion,
+                   change.version);
+    }
+
+    // Update workspace for all nodes in the binding tree, and opt this
+    // subos into the version's installed[] set if it wasn't already.
+    //
+    // The entry target is guaranteed to be in installed[] already -- the gate
+    // above refused otherwise. What this still covers is the *members*: a
+    // release can gain a program between versions (gcc 16 adding a binary gcc
+    // 15 did not have), and a member the subos never saw is arriving as part
+    // of a release it did ask for, not instead of one. Its payload is the same
+    // already-materialised payload, so recording it is bookkeeping, not an
+    // install.
+    auto& wsi = Config::workspace_installed_mut();
+    for (auto& [name, ver] : to_switch) {
+        Config::workspace_mut()[name] = ver;
+        auto& list = wsi[name];
+        if (std::find(list.begin(), list.end(), ver) == list.end()) {
+            list.push_back(ver);
+            log::debug("auto-add to installed[]: {} += {}", name, ver);
+        }
+        log::debug("binding sync: {} -> {}", name, ver);
+    }
+    Config::save_workspace();
+
+    // Create/update shims for all switched targets
+#ifdef _WIN32
+    auto xlings_bin = p.homeDir / "bin" / "xlings.exe";
+    constexpr std::string_view shim_ext = ".exe";
+#else
+    auto xlings_bin = p.homeDir / "bin" / "xlings";
+    constexpr std::string_view shim_ext = "";
+#endif
+    if (!fs::exists(xlings_bin)) {
+        xlings_bin = p.homeDir / "xlings";
+    }
+
+    if (fs::exists(xlings_bin)) {
+        fs::create_directories(p.binDir);
+        for (auto& [name, ver] : to_switch) {
+            auto vinfo = get_vinfo(db, name);
+            // effective_kind_of, not vinfo->type: the per-version kind is the
+            // authority and the target-level type is only its fallback.
+            if (!vinfo || effective_kind_of(db, name, ver) != "program") continue;
+            std::string shim_name = (!vinfo->filename.empty()) ? vinfo->filename : name;
+            if (!shim_ext.empty() && !shim_name.ends_with(shim_ext))
+                shim_name += shim_ext;
+            xself::create_shim(xlings_bin, p.binDir / shim_name);
+            common::mirror_shim_to_global_bin(xlings_bin, shim_name);
+        }
+    }
+
+    // Self-replace: when the user switches to a different version of xlings
+    // (or its multicall aliases xim/xvm), physically replace the bootstrap
+    // binary with that version. Symmetric with the install-time replace in
+    // installer.cppm — they share the same condition: "we just made this
+    // version active for the running binary's identity".
+    //
+    // main.cpp's multiplexer short-circuits xlings/xim/xvm names to the
+    // local cli::run() without consulting the workspace at runtime, so
+    // updating workspace[xlings] alone has no observable effect; the
+    // bootstrap file itself must change for `xlings --version` etc. to
+    // reflect the switch.
+    if (is_xlings_binary(target) && fs::exists(xlings_bin)) {
+        auto* vd = get_vdata(db, target, resolved);
+        if (vd && !vd->path.empty()) {
+            auto active_bin = fs::path(vd->path)
+                            / ("xlings" + std::string(shim_ext));
+            if (fs::exists(active_bin)) {
+                entry_binary::replace_with(
+                    active_bin, xlings_bin,
+                    std::format("{}@{}", target, resolved), resolved);
+            }
+        }
+        // COMPAT(0.4.8 → drop in 0.6.0): opportunistically drop legacy
+        // alias symlinks (xim/xvm/...) left over from xlings ≤ 0.4.7.
+        // Lands on this path during `xlings self update`, which ends with
+        // `xlings use xlings latest` — so first-upgrade self-heals.
+        xself::compat::v0_4_8::cleanup_legacy_alias_shims(p.binDir, xlings_bin);
+    }
+
+    // Which release did this actually move?
+    //
+    // `xlings use java 25.0.4-zulu` names a MEMBER, not a package, so the
+    // bare line leaves the user unable to tell which package -- and which
+    // version of it -- they just selected, or that they changed packages at
+    // all. The clause carries the provider name (what they typed at install
+    // time) and the provider version, which is not the same string as the
+    // target's version: `xim:jdk-temurin 25.0.4+7` vs `java 25.0.4+7-temurin`.
+    //
+    // The `{target} -> {version}` half is unchanged, deliberately: it is what
+    // scripts and tests grep for.
+    if (plan->toProvider.empty()) {
+        log::info("{} -> {}", target, resolved);   // no group metadata
+    } else if (plan->fromProvider.empty()) {
+        log::info("{} -> {}  ({} {})", target, resolved,
+                  plan->toProvider, plan->toProviderVersion);
+    } else if (plan->fromProvider == plan->toProvider) {
+        log::info("{} -> {}  ({} {} -> {})", target, resolved,
+                  plan->toProvider, plan->fromProviderVersion,
+                  plan->toProviderVersion);
+    } else {
+        log::info("{} -> {}  ({} {} -> {} {})", target, resolved,
+                  plan->fromProvider, plan->fromProviderVersion,
+                  plan->toProvider, plan->toProviderVersion);
+    }
+
+    // `-v` is the global flag; nothing here needs an option of its own.
+    const bool verbose = log::get_level() <= log::Level::Debug;
+    // The release being left. `workspace` is the copy read before anything
+    // moved -- the writes above went through Config::workspace_mut() -- so it
+    // still answers for the state the user is coming from.
+    const auto leftIt = workspace.find(target);
+    const std::string leftRelease =
+        leftIt == workspace.end() ? std::string{} : leftIt->second;
+
+    // Say what the switch did NOT cover.
+    //
+    // The single `llvm -> 20.1.7` line above was the entire output of a
+    // command that left `clang` answering 22.1.8, and the user found out from
+    // their compiler, not from xlings. Naming each one and what it still
+    // resolves to is the difference between a mixed toolchain the user chose
+    // and one they were handed.
+    //
+    // Collapsed to one line unless asked: a real case runs to dozens of
+    // entries, and a report nobody finishes reading protects nobody. The line
+    // has to carry all three facts on its own -- how many, why they did not
+    // come along, and what they are now -- or it just puzzles the reader.
+    if (!plan->stranded.empty()) {
+        // Kept to short lines on purpose: core cannot wrap (it does not
+        // depend on ui, which owns the width contract), so the only way these
+        // stay inside a narrow terminal is to be written that way.
+        if (!verbose) {
+            log::warn("{} name(s) not in {}@{} still run from {} — -v to list",
+                      plan->stranded.size(), target, resolved, leftRelease);
+        } else {
+            log::warn("{} name(s) not in {}@{}, still on the old release:",
+                      plan->stranded.size(), target, resolved);
+            for (const auto& member : plan->stranded) {
+                if (member.kind == "program") {
+                    log::warn("    {} (still {})", member.target,
+                              member.version);
+                } else {
+                    log::warn("    {} (still {}, {})", member.target,
+                              member.version, member.kind);
+                }
+            }
+            log::warn("  move: xlings use {} <version>",
+                      plan->stranded.front().target);
+            log::warn("  drop: xlings remove {}@{}",
+                      plan->stranded.front().target,
+                      plan->stranded.front().version);
+        }
+    }
+
+    // Switching packages: what the old one still owns.
+    //
+    // Silent by default, and that is the point. These names did not fall
+    // behind -- the package they belong to is untouched and still active, and
+    // the incoming package has no version of them to offer. There is no
+    // action to recommend, so a warning would be pure noise on a command that
+    // did exactly what it was asked. The `(A -> B)` clause above already says
+    // the package changed; `-v` is where the list belongs.
+    if (verbose && !plan->retainedByOldPackage.empty()) {
+        log::warn("{} name(s) still come from {}:",
+                  plan->retainedByOldPackage.size(), plan->fromProvider);
+        for (const auto& member : plan->retainedByOldPackage) {
+            if (member.kind == "program") {
+                log::warn("    {} ({})", member.target, member.version);
+            } else {
+                log::warn("    {} ({}, {})", member.target, member.version,
+                          member.kind);
+            }
+        }
+        log::warn("  {} has no version of them to switch to.",
+                  plan->toProvider);
+    }
+
+    xself::print_migration_hint_once(Config::recorded_client_version(),
+                                     Info::VERSION);
+    return 0;
+}
+
+std::expected<VersionCandidates, int>
+collect_version_candidates_(const std::string& target, bool all) {
+    auto db = Config::versions();
+
+    if (!has_target(db, target)) {
+        log::error("'{}' not found in version database", target);
+        return std::unexpected(1);
+    }
+
+    auto workspace = Config::effective_workspace();
+    VersionCandidates out;
+    out.active = get_active_version(workspace, target);
+    auto global_all = get_all_versions(db, target);
+
+    if (all) {
+        out.versions = global_all;
+        out.title = target + " versions (all subos)";
+        return out;
+    }
+
+    out.versions = filter_to_subos_installed_(target, global_all);
+    if (out.versions.empty()) {
+        // Empty subos installed[] for this target — show a hint instead of an
+        // empty panel. The global list is informational so the user can pick
+        // a version to install.
+        log::error("'{}' is not installed in current subos", target);
+        if (!global_all.empty()) {
+            std::string avail;
+            for (auto& v : global_all) {
+                if (!avail.empty()) avail += " ";
+                avail += v;
+            }
+            log::error("  globally available: {}", avail);
+            log::error("  hint: xlings install {}@<version>"
+                       " (or `xlings use {} --all` to see global view)",
+                       target, target);
+        } else {
+            log::error("  hint: xlings install {}", target);
+        }
+        return std::unexpected(1);
+    }
+    out.title = target + " versions (current subos)";
+    return out;
+}
+
+void emit_version_panel_(const std::string& target,
+                         const VersionCandidates& candidates,
+                         EventStream& stream) {
+    auto db = Config::versions();
+    nlohmann::json fieldsJson = nlohmann::json::array();
+    for (auto& ver : candidates.versions) {
+        auto vdata = get_vdata(db, target, ver);
+        std::string path_info;
+        // `@xlings/...` rather than the absolute path. `self config` and
+        // `self doctor` already abbreviate; this panel did not, and it is the
+        // one whose rows are payload paths — the ~20 columns the prefix costs
+        // are exactly what pushed it past the terminal.
+        if (vdata && !vdata->path.empty()) path_info = Config::display_path(vdata->path);
+        bool highlight = (ver == candidates.active);
+        fieldsJson.push_back({{"label", ver}, {"value", path_info}, {"highlight", highlight}});
+    }
+    nlohmann::json payload;
+    payload["title"] = candidates.title;
+    payload["fields"] = std::move(fieldsJson);
+    stream.emit(DataEvent{"info_panel", payload.dump()});
+}
+
+int cmd_list_versions(const std::string& target, EventStream& stream, bool all) {
+    auto candidates = collect_version_candidates_(target, all);
+    if (!candidates) return candidates.error();
+    emit_version_panel_(target, *candidates, stream);
+    if (candidates->versions.size() > 1) {
+        nlohmann::json tip;
+        tip["message"] = std::format("xlings use {} <version>", target);
+        stream.emit(DataEvent{"tip", tip.dump()});
+    }
+    return 0;
+}
+
+int cmd_use_by_name(const std::string& target, EventStream& stream, bool all, bool strict) {
+    auto candidates = collect_version_candidates_(target, all);
+    if (!candidates) return candidates.error();
+
+    // Unambiguous: there is nothing to ask about. This also covers the
+    // documented sysroot-repair use of `use` -- switching to the version that
+    // is already active re-materializes headers and libraries.
+    if (candidates->versions.size() == 1) {
+        return cmd_use(target, candidates->versions.front(), stream, strict);
+    }
+
+    return cmd_list_versions(target, stream, all);
+}
+
+void register_version(const std::string& target,
+                      const std::string& version,
+                      const std::string& path,
+                      const std::string& type,
+                      const std::string& filename) {
+    add_version(Config::versions_mut(), target, version, path, type, filename);
+    Config::save_versions();
+}
+
+}
diff --git a/src/core/xvm/commands.cppm b/src/core/xvm/commands.cppm
index 76579a07..0935f0c4 100644
--- a/src/core/xvm/commands.cppm
+++ b/src/core/xvm/commands.cppm
@@ -2,14 +2,9 @@ export module xlings.core.xvm.commands;
 
 import std;
 
-import xlings.core.common;
 import xlings.core.config;
-import xlings.core.log;
-import xlings.core.palette;
 import xlings.core.subos.manifest;
-import xlings.platform;
 import xlings.runtime;
-import xlings.libs.json;
 import xlings.core.semver;
 import xlings.core.entry_binary;
 import xlings.core.xself;
@@ -28,25 +23,7 @@ export namespace xlings::xvm {
 namespace fs = std::filesystem;
 
 // Cross-platform link: symlink on Unix, directory junction or copy on Windows
-void create_link_(const fs::path& src, const fs::path& dst) {
-    std::error_code ec;
-#if defined(_WIN32)
-    if (fs::is_directory(src)) {
-        // Use directory junction on Windows (no admin required)
-        platform::create_directory_link(dst.string(), src.string());
-    } else {
-        fs::create_hard_link(src, dst, ec);
-        if (ec) {
-            ec.clear();
-            fs::copy_file(src, dst, fs::copy_options::overwrite_existing, ec);
-        }
-    }
-#else
-    fs::create_symlink(src, dst, ec);
-#endif
-    if (ec) log::warn("[xvm] link failed: {} -> {}",
-                      Config::display_path(dst), Config::display_path(src));
-}
+void create_link_(const fs::path& src, const fs::path& dst);
 
 // Where a header asset lands: `<sysroot>/include/<destinationPrefix>`, or
 // `<sysroot>/include` when the asset declares no prefix.
@@ -61,11 +38,7 @@ void create_link_(const fs::path& src, const fs::path& dst) {
 // serialized field that materialization ignores is exactly the kind of state
 // this release is removing, not adding.
 fs::path header_destination_(const HeaderAsset& asset,
-                             const fs::path& sysroot_include) {
-    return asset.destinationPrefix.empty()
-        ? sysroot_include
-        : sysroot_include / fs::path(asset.destinationPrefix);
-}
+                             const fs::path& sysroot_include);
 
 // Whether a payload directory may be linked into a sysroot.
 //
@@ -78,101 +51,19 @@ fs::path header_destination_(const HeaderAsset& asset,
 // `/tmp` path that no longer exists. Every later `remove` and `install` of the
 // package repaired the OTHER subos and reported success, because nothing was
 // ever wrong there.
-bool sysroot_source_is_local_(const fs::path& src) {
-    std::error_code ec;
-    const auto canon = fs::weakly_canonical(src, ec);
-    const auto& probe = ec ? src : canon;
-    const auto under = [&](const fs::path& root) {
-        if (root.empty()) return false;
-        std::error_code rec;
-        auto canonRoot = fs::weakly_canonical(root, rec);
-        const auto& r = rec ? root : canonRoot;
-        auto a = probe.string(), b = r.string();
-        return a == b || a.starts_with(b + static_cast<char>(fs::path::preferred_separator))
-            || a.starts_with(b + "/");
-    };
-    const auto& p = Config::paths();
-    return under(p.dataDir) || under(p.homeDir);
-}
+bool sysroot_source_is_local_(const fs::path& src);
 
 // Install header symlinks from source includedir into sysroot include/
-void install_headers(const std::string& includedir, const fs::path& sysroot_include) {
-    fs::create_directories(sysroot_include);
-    std::error_code ec;
-    fs::path src(includedir);
-    if (!fs::exists(src, ec)) return;
-    if (!sysroot_source_is_local_(src)) {
-        // Warned, not refused. A recipe may legitimately expose headers from
-        // outside the store (a wrapper around system headers is the obvious
-        // one), and refusing would break packages that work today. What is
-        // NOT legitimate is the run that produced the measured damage, and
-        // this is the moment it becomes visible instead of surfacing weeks
-        // later as a missing header from a subos the user is not even in.
-        log::warn("[xvm] linking headers from outside this home: {}",
-                  Config::display_path(src));
-        log::warn("  into sysroot: {}", Config::display_path(sysroot_include));
-        log::warn("  these links outlive the run that made them; "
-                  "`xlings self doctor --fix` removes them once they dangle");
-    }
-    for (auto& entry : platform::dir_entries(src)) {
-        auto target = sysroot_include / entry.path().filename();
-        // Already pointing at this exact source: leave it alone.
-        // `xlings use` now re-materializes the active release on every
-        // invocation so it can repair a sysroot that drifted, and
-        // remove-then-relink would open a window on every one of those
-        // calls where the header is simply absent -- long enough for a
-        // concurrent build to fail on it. equivalent() covers symlinks,
-        // Windows junctions and hard links alike; a copy fallback compares
-        // unequal and is relinked, which is correct.
-        std::error_code sameEc;
-        if (std::filesystem::equivalent(target, entry.path(), sameEc)
-            && !sameEc) {
-            continue;
-        }
-        if (fs::exists(target, ec) || fs::is_symlink(target, ec)) {
-            log::debug("[xvm] overwriting header: {}", entry.path().filename().string());
-            fs::remove_all(target, ec);
-        }
-        create_link_(entry.path(), target);
-    }
-}
+void install_headers(const std::string& includedir, const fs::path& sysroot_include);
 
 // Remove header symlinks that point into the given source includedir
-void remove_headers(const std::string& includedir, const fs::path& sysroot_include) {
-    if (includedir.empty()) return;
-    fs::path src(includedir);
-    std::error_code ec;
-    if (!fs::exists(src, ec)) return;
-    for (auto& entry : platform::dir_entries(src)) {
-        auto target = sysroot_include / entry.path().filename();
-        if (fs::is_symlink(target, ec)) {
-            fs::remove(target, ec);
-#if defined(_WIN32)
-        } else if (fs::exists(target, ec)) {
-            // On Windows, directory junctions appear as dirs, not symlinks
-            fs::remove_all(target, ec);
-#endif
-        }
-    }
-}
+void remove_headers(const std::string& includedir, const fs::path& sysroot_include);
 
 // Same two operations, addressed by header asset rather than by bare source
 // directory, so the destination prefix is honored.
-void install_headers(const HeaderAsset& asset, const fs::path& sysroot_include) {
-    install_headers(asset.sourceDir, header_destination_(asset, sysroot_include));
-}
+void install_headers(const HeaderAsset& asset, const fs::path& sysroot_include);
 
-void remove_headers(const HeaderAsset& asset, const fs::path& sysroot_include) {
-    const auto destination = header_destination_(asset, sysroot_include);
-    remove_headers(asset.sourceDir, destination);
-    // A prefix directory that only ever held this release's links is litter
-    // once they are gone. remove() on a non-empty directory fails, so this
-    // cannot take anything else with it.
-    if (!asset.destinationPrefix.empty()) {
-        std::error_code ec;
-        fs::remove(destination, ec);
-    }
-}
+void remove_headers(const HeaderAsset& asset, const fs::path& sysroot_include);
 
 // Place one file at an exact destination, replacing whatever is there.
 //
@@ -188,71 +79,18 @@ void remove_headers(const HeaderAsset& asset, const fs::path& sysroot_include) {
 // step to fail on it. rename(2) replaces atomically; Windows has no
 // equivalent for every entry kind, so the staging file is cleaned up and the
 // direct path is taken there.
-void place_asset(const std::string& source, const fs::path& destination) {
-    if (source.empty() || destination.empty()) return;
-    std::error_code ec;
-    fs::path src(source);
-    if (!fs::exists(src, ec)) {
-        log::debug("[xvm] asset source missing, not placed: {}",
-                   Config::display_path(source));
-        return;
-    }
-    fs::create_directories(destination.parent_path(), ec);
-
-    // Already pointing at this exact file: leave it alone. Keeps the repeated
-    // re-materialization that `use` performs down to a stat.
-    std::error_code sameEc;
-    if (fs::equivalent(destination, src, sameEc) && !sameEc) return;
-
-    const auto staging =
-        destination.parent_path()
-        / (destination.filename().string() + ".xlings-new");
-    fs::remove_all(staging, ec);
-    create_link_(src, staging);
-    if (!fs::exists(staging, ec) && !fs::is_symlink(staging, ec)) {
-        log::warn("[xvm] could not stage asset: {}",
-                  Config::display_path(destination));
-        return;
-    }
-    ec.clear();
-    fs::rename(staging, destination, ec);
-    if (ec) {
-        // Platforms without an atomic replace for this entry kind. Accept the
-        // window rather than leave the staging file behind.
-        std::error_code rmEc;
-        fs::remove_all(destination, rmEc);
-        ec.clear();
-        fs::rename(staging, destination, ec);
-        if (ec) {
-            fs::remove_all(staging, rmEc);
-            log::warn("[xvm] could not place asset {}: {}",
-                      Config::display_path(destination), ec.message());
-        }
-    }
-}
+void place_asset(const std::string& source, const fs::path& destination);
 
 // Take one placed file back out.
-void remove_asset(const fs::path& destination) {
-    if (destination.empty()) return;
-    std::error_code ec;
-    if (fs::is_symlink(destination, ec) || fs::exists(destination, ec)) {
-        fs::remove_all(destination, ec);
-    }
-}
+void remove_asset(const fs::path& destination);
 
 // Library-shaped wrappers, kept because the sysroot lib directory is implied
 // rather than declared for libraries.
 void place_library(const std::string& source,
                    const std::string& name,
-                   const fs::path& sysroot_lib) {
-    if (name.empty()) return;
-    place_asset(source, sysroot_lib / name);
-}
+                   const fs::path& sysroot_lib);
 
-void remove_library(const std::string& name, const fs::path& sysroot_lib) {
-    if (name.empty()) return;
-    remove_asset(sysroot_lib / name);
-}
+void remove_library(const std::string& name, const fs::path& sysroot_lib);
 
 // Helper: filter a list of version keys (`ns:ver` or bare) down to those
 // that appear in the current subos's installed[] for `target`. Tolerant
@@ -287,454 +125,12 @@ filter_to_subos_installed_(const std::string& target,
 // rewrite the versions DB as an incidental repair.
 bool runtime_activation_refused_(const VersionDB& db,
                                  const std::string& target,
-                                 const std::string& requestedVersion) {
-    namespace mf = xlings::subos::manifest;
-
-    const auto doc = mf::read_document(Config::subos_scope().root);
-    if (!doc) return false;
-    const auto info = mf::parse(*doc);
-    if (!mf::is_binding(info.runtime)
-        || target != mf::binding_name(info.runtime)) {
-        return false;
-    }
-
-    const auto it = db.find(target);
-    if (it == db.end() || it->second.versions.empty()) return false;
-    const auto resolved = requestedVersion == "latest"
-        ? pick_highest_version(it->second.versions)
-        : match_version(db, target, requestedVersion);
-    if (resolved.empty()) return false;
-
-    bool payloadExists = false;
-    if (const auto* data = get_vdata(db, target, resolved);
-        data && !data->path.empty()) {
-        std::error_code ec;
-        const auto expanded = expand_path(
-            data->path, Config::paths().homeDir.string());
-        payloadExists = fs::exists(expanded, ec) && !ec;
-    }
-
-    const auto mismatch = mf::check_runtime_activation(
-        info, resolved, payloadExists);
-    if (!mismatch) return false;
-
-    const auto prospective = mismatch->active.empty()
-        ? std::format("{}@{}", target, resolved) : mismatch->active;
-    if (mismatch->payloadMissing
-        && prospective == mismatch->declared) {
-        log::error("[xlings:use] runtime activation refused: {} has no "
-                   "payload", mismatch->declared);
-        log::error("  nothing was changed");
-        log::error("  hint: reinstall it with `xlings install {} --force`",
-                   mismatch->declared);
-        return true;
-    }
-
-    log::error("[xlings:use] runtime activation refused: this SubOS "
-               "declares {}, but the requested runtime is {}",
-               mismatch->declared, prospective);
-    log::error("  nothing was changed");
-    // Two ways out, and both stay inside this SubOS. Sending the user to
-    // `subos new` implies neither exists, which was never true: activating the
-    // DECLARED version is exactly what this guard permits.
-    log::error("  hint: adopt what this SubOS runs -- `xlings self doctor --fix`");
-    log::error("        or migrate to it -- `xlings install {}` then "
-               "`xlings use {} {}`",
-               mismatch->declared, target, mf::binding_version(mismatch->declared));
-    return true;
-}
+                                 const std::string& requestedVersion);
 
 // xlings use <target> <version>
 // Updates the active subos workspace and creates/updates bin/ hardlinks
 int cmd_use(const std::string& target, const std::string& version,
-            EventStream& stream, bool strict = false) {
-    // Serialize against any other xlings mutating this home, then re-read
-    // state under the lock: Config loaded it at process start, outside the
-    // lock, so acting on that snapshot is how two commands lose each other's
-    // work. See xvm/lock.cppm.
-    auto stateLock = xvm::acquire_state_lock(Config::paths().homeDir);
-    if (!stateLock) {
-        log::error("{}", stateLock.error());
-        return 1;
-    }
-    Config::reload_state();
-
-    if (runtime_activation_refused_(Config::versions(), target, version)) {
-        return 1;
-    }
-
-    // Self-heal a dangling legacy edge before planning anything.
-    //
-    // State written by <= 0.4.69 can carry a pairwise edge pointing at a
-    // version that is not registered. Such an edge describes no member
-    // anyone could switch to -- it can only make the release unresolvable --
-    // so dropping it needs no guessing, which is exactly why it does not
-    // need the user's permission either.
-    //
-    // Until now it was reported by doctor and only repaired by
-    // `doctor --fix`, which meant an upgraded user hit a refusal from `use`
-    // with no idea that a second command existed. Repairing it here makes
-    // the upgrade what it was supposed to be: silent. doctor keeps the
-    // report and the flag for anyone inspecting rather than switching.
-    if (auto pruning = plan_dangling_edge_pruning(Config::versions());
-        !pruning.empty()) {
-        auto& mutableDb = Config::versions_mut();
-        const auto dropped =
-            apply_dangling_edge_pruning(mutableDb, pruning);
-        if (dropped > 0) {
-            Config::save_versions();
-            log::debug("[xvm] pruned {} dangling binding edge(s) written by "
-                       "an older xlings", dropped);
-        }
-    }
-
-    auto db = Config::versions();
-    auto& p  = Config::paths();
-
-    if (!has_target(db, target)) {
-        log::error("[xlings:use] '{}' not found in version database", target);
-        log::error("  hint: install it first with `xlings install {}`", target);
-        return 1;
-    }
-
-    // "latest" means pick the highest available version.
-    std::string resolved;
-    if (version == "latest") {
-        // Scope-aware: pick_highest_version strips the "<scope>:" prefix (e.g.
-        // the bootstrap "local:0.4.47") before comparing by numeric semver, so
-        // a higher real release (e.g. 0.4.52) wins. semver::sort_desc alone
-        // cannot parse "local:..." and falls back to lexicographic order, where
-        // "local:0.4.47" wrongly beats "0.4.52" — the bug that made
-        // `xlings self update` install the new version yet stay on the old
-        // local one (xlings -> local:0.4.47).
-        auto it = db.find(target);
-        if (it == db.end() || it->second.versions.empty()) {
-            log::error("no versions installed for '{}'", target);
-            return 1;
-        }
-        resolved = pick_highest_version(it->second.versions);
-    } else {
-        // Fuzzy match version
-        resolved = match_version(db, target, version);
-    }
-
-    if (resolved.empty()) {
-        log::error("version '{}' not found for '{}'", version, target);
-        auto all = get_all_versions(db, target);
-        if (!all.empty()) {
-            std::string avail;
-            for (auto& v : all) {
-                if (!avail.empty()) avail += ", ";
-                avail += v;
-            }
-            log::error("  available: {}", avail);
-        }
-        return 1;
-    }
-
-    log::debug("fuzzy version match: {} -> {}", version, resolved);
-
-    // A version registered somewhere in this home is not a version this subos
-    // can use.
-    //
-    // `use` used to opt the current subos in silently whenever the payload
-    // existed anywhere (auto-add, 0.4.19+), on the reasoning that the payload
-    // is shared so activation is free. That is true of a self-contained
-    // package and false of everything with a dependency: gcc's glibc is not a
-    // member of gcc's release, and the versions DB records no dependency
-    // information at all, so activating gcc here activated exactly gcc. The
-    // result reported success, put a working `g++` on PATH, printed the right
-    // `-print-sysroot` -- and could not compile, because `usr/include` was
-    // empty. Nothing said so.
-    //
-    // `use` cannot fix that: it cannot even name what is missing. So it stops
-    // pretending to. Switching stays what it says it is -- moving between
-    // versions this subos has -- and getting a version into a subos belongs to
-    // `install`, which resolves dependencies and materialises them.
-    if (filter_to_subos_installed_(target, {resolved}).empty()) {
-        const auto scope = Config::subos_scope().name;
-        log::error("[xlings:use] '{}' is not installed in this subos ({})",
-                   target, scope.empty() ? "default" : scope);
-        log::error("  nothing was changed");
-        log::error("  hint: install it here first with `xlings install {}@{}`",
-                   target, resolved);
-        return 1;
-    }
-
-    // Resolve the whole release before touching anything.
-    //
-    // This used to walk the binding edges by hand, keyed by target rather
-    // than by (target, version), and without checking that what it reached
-    // actually existed. A stale edge would take it to a version with no
-    // VData, which it then wrote into the active workspace -- the shim
-    // failed later, far from the command that caused it. Header and library
-    // switching ran *before* that walk and only for the entry target, so a
-    // failure part-way through left the sysroot holding one release and the
-    // workspace claiming another.
-    //
-    // resolve_binding_selection validates the whole group and fails closed.
-    // Running it first means a bad group costs the user an error message
-    // instead of a half-switched toolchain.
-    auto workspace = Config::effective_workspace();
-    auto plan = plan_use_switch(db, workspace, target, resolved);
-    if (!plan) {
-        log::error("{}", render(plan.error(), true));
-        return 1;
-    }
-    const auto& to_switch = plan->members;
-
-    // A program the outgoing release had and this one does not keeps
-    // resolving to the release being left -- see StrandedMember. `--strict`
-    // is for callers that would rather not switch at all than end up holding
-    // two releases, and it has to refuse HERE, while nothing has moved yet.
-    //
-    // `stranded` only ever holds members of the SAME package (the planner
-    // sorts a package switch into retainedByOldPackage instead), so this can
-    // no longer refuse a move between two distributions of one tool -- a
-    // refusal the user could not have satisfied, since the two packages have
-    // no name in common to move first.
-    //
-    // Always lists every entry, verbose or not: this is the error path, and
-    // the reason for a refusal is not a detail.
-    if (strict && !plan->stranded.empty()) {
-        log::error("[xlings:use] --strict: not switching {} to {}",
-                   target, resolved);
-        log::error("  {} name(s) would stay on the old release:",
-                   plan->stranded.size());
-        for (const auto& member : plan->stranded) {
-            if (member.kind == "program") {
-                log::error("    {} (still {})", member.target, member.version);
-            } else {
-                log::error("    {} (still {}, {})", member.target,
-                           member.version, member.kind);
-            }
-        }
-        log::error("  hint: drop --strict, or move each one first");
-        return 1;
-    }
-
-    // Everything above this line is a decision; everything below changes the
-    // filesystem. Members that are already where they belong emit no change.
-    auto sysroot_include = p.subosDir / "usr" / "include";
-    // `<subos>/lib`, which is where the install path has always put
-    // libraries (`Config::paths().libDir`) and where they actually are: 94
-    // entries on a real installation, against one on `<subos>/usr/lib`.
-    // This line used to read `usr/lib`, and the disagreement was invisible
-    // because the switch side never emitted any library work at all --
-    // `VData::libdir` has no writer. Making libraries switch without fixing
-    // it would have started filling a second, unused directory.
-    auto sysroot_lib     = p.libDir;
-    // Headers first, and as two whole passes rather than per member: they are
-    // an asset of the release, not of any one member of it. Interleaving the
-    // passes -- remove one member's, install the next member's -- let the
-    // outgoing release's removal delete a link the incoming release had
-    // already put down, for every header name the two versions share. The
-    // plan has the two lists deduplicated and disjoint already.
-    for (const auto& asset : plan->removeHeaders) {
-        remove_headers(asset, sysroot_include);
-    }
-    for (const auto& asset : plan->installHeaders) {
-        install_headers(asset, sysroot_include);
-    }
-
-    for (const auto& change : plan->switches) {
-        if (!change.removeLibName.empty())
-            remove_library(change.removeLibName, sysroot_lib);
-        if (!change.installLibSource.empty())
-            place_library(change.installLibSource, change.installLibName,
-                          sysroot_lib);
-        // File assets carry their own destination, relative to the subos
-        // root, so they are joined here rather than assumed into a fixed dir.
-        if (!change.removeFileDest.empty())
-            remove_asset(p.subosDir / change.removeFileDest);
-        if (!change.installFileSource.empty())
-            place_asset(change.installFileSource,
-                        p.subosDir / change.installFileDest);
-        log::debug("switching {}: {} -> {}", change.target,
-                   change.previousVersion.empty() ? "(none)"
-                                                  : change.previousVersion,
-                   change.version);
-    }
-
-    // Update workspace for all nodes in the binding tree, and opt this
-    // subos into the version's installed[] set if it wasn't already.
-    //
-    // The entry target is guaranteed to be in installed[] already -- the gate
-    // above refused otherwise. What this still covers is the *members*: a
-    // release can gain a program between versions (gcc 16 adding a binary gcc
-    // 15 did not have), and a member the subos never saw is arriving as part
-    // of a release it did ask for, not instead of one. Its payload is the same
-    // already-materialised payload, so recording it is bookkeeping, not an
-    // install.
-    auto& wsi = Config::workspace_installed_mut();
-    for (auto& [name, ver] : to_switch) {
-        Config::workspace_mut()[name] = ver;
-        auto& list = wsi[name];
-        if (std::find(list.begin(), list.end(), ver) == list.end()) {
-            list.push_back(ver);
-            log::debug("auto-add to installed[]: {} += {}", name, ver);
-        }
-        log::debug("binding sync: {} -> {}", name, ver);
-    }
-    Config::save_workspace();
-
-    // Create/update shims for all switched targets
-#ifdef _WIN32
-    auto xlings_bin = p.homeDir / "bin" / "xlings.exe";
-    constexpr std::string_view shim_ext = ".exe";
-#else
-    auto xlings_bin = p.homeDir / "bin" / "xlings";
-    constexpr std::string_view shim_ext = "";
-#endif
-    if (!fs::exists(xlings_bin)) {
-        xlings_bin = p.homeDir / "xlings";
-    }
-
-    if (fs::exists(xlings_bin)) {
-        fs::create_directories(p.binDir);
-        for (auto& [name, ver] : to_switch) {
-            auto vinfo = get_vinfo(db, name);
-            // effective_kind_of, not vinfo->type: the per-version kind is the
-            // authority and the target-level type is only its fallback.
-            if (!vinfo || effective_kind_of(db, name, ver) != "program") continue;
-            std::string shim_name = (!vinfo->filename.empty()) ? vinfo->filename : name;
-            if (!shim_ext.empty() && !shim_name.ends_with(shim_ext))
-                shim_name += shim_ext;
-            xself::create_shim(xlings_bin, p.binDir / shim_name);
-            common::mirror_shim_to_global_bin(xlings_bin, shim_name);
-        }
-    }
-
-    // Self-replace: when the user switches to a different version of xlings
-    // (or its multicall aliases xim/xvm), physically replace the bootstrap
-    // binary with that version. Symmetric with the install-time replace in
-    // installer.cppm — they share the same condition: "we just made this
-    // version active for the running binary's identity".
-    //
-    // main.cpp's multiplexer short-circuits xlings/xim/xvm names to the
-    // local cli::run() without consulting the workspace at runtime, so
-    // updating workspace[xlings] alone has no observable effect; the
-    // bootstrap file itself must change for `xlings --version` etc. to
-    // reflect the switch.
-    if (is_xlings_binary(target) && fs::exists(xlings_bin)) {
-        auto* vd = get_vdata(db, target, resolved);
-        if (vd && !vd->path.empty()) {
-            auto active_bin = fs::path(vd->path)
-                            / ("xlings" + std::string(shim_ext));
-            if (fs::exists(active_bin)) {
-                entry_binary::replace_with(
-                    active_bin, xlings_bin,
-                    std::format("{}@{}", target, resolved), resolved);
-            }
-        }
-        // COMPAT(0.4.8 → drop in 0.6.0): opportunistically drop legacy
-        // alias symlinks (xim/xvm/...) left over from xlings ≤ 0.4.7.
-        // Lands on this path during `xlings self update`, which ends with
-        // `xlings use xlings latest` — so first-upgrade self-heals.
-        xself::compat::v0_4_8::cleanup_legacy_alias_shims(p.binDir, xlings_bin);
-    }
-
-    // Which release did this actually move?
-    //
-    // `xlings use java 25.0.4-zulu` names a MEMBER, not a package, so the
-    // bare line leaves the user unable to tell which package -- and which
-    // version of it -- they just selected, or that they changed packages at
-    // all. The clause carries the provider name (what they typed at install
-    // time) and the provider version, which is not the same string as the
-    // target's version: `xim:jdk-temurin 25.0.4+7` vs `java 25.0.4+7-temurin`.
-    //
-    // The `{target} -> {version}` half is unchanged, deliberately: it is what
-    // scripts and tests grep for.
-    if (plan->toProvider.empty()) {
-        log::info("{} -> {}", target, resolved);   // no group metadata
-    } else if (plan->fromProvider.empty()) {
-        log::info("{} -> {}  ({} {})", target, resolved,
-                  plan->toProvider, plan->toProviderVersion);
-    } else if (plan->fromProvider == plan->toProvider) {
-        log::info("{} -> {}  ({} {} -> {})", target, resolved,
-                  plan->toProvider, plan->fromProviderVersion,
-                  plan->toProviderVersion);
-    } else {
-        log::info("{} -> {}  ({} {} -> {} {})", target, resolved,
-                  plan->fromProvider, plan->fromProviderVersion,
-                  plan->toProvider, plan->toProviderVersion);
-    }
-
-    // `-v` is the global flag; nothing here needs an option of its own.
-    const bool verbose = log::get_level() <= log::Level::Debug;
-    // The release being left. `workspace` is the copy read before anything
-    // moved -- the writes above went through Config::workspace_mut() -- so it
-    // still answers for the state the user is coming from.
-    const auto leftIt = workspace.find(target);
-    const std::string leftRelease =
-        leftIt == workspace.end() ? std::string{} : leftIt->second;
-
-    // Say what the switch did NOT cover.
-    //
-    // The single `llvm -> 20.1.7` line above was the entire output of a
-    // command that left `clang` answering 22.1.8, and the user found out from
-    // their compiler, not from xlings. Naming each one and what it still
-    // resolves to is the difference between a mixed toolchain the user chose
-    // and one they were handed.
-    //
-    // Collapsed to one line unless asked: a real case runs to dozens of
-    // entries, and a report nobody finishes reading protects nobody. The line
-    // has to carry all three facts on its own -- how many, why they did not
-    // come along, and what they are now -- or it just puzzles the reader.
-    if (!plan->stranded.empty()) {
-        // Kept to short lines on purpose: core cannot wrap (it does not
-        // depend on ui, which owns the width contract), so the only way these
-        // stay inside a narrow terminal is to be written that way.
-        if (!verbose) {
-            log::warn("{} name(s) not in {}@{} still run from {} — -v to list",
-                      plan->stranded.size(), target, resolved, leftRelease);
-        } else {
-            log::warn("{} name(s) not in {}@{}, still on the old release:",
-                      plan->stranded.size(), target, resolved);
-            for (const auto& member : plan->stranded) {
-                if (member.kind == "program") {
-                    log::warn("    {} (still {})", member.target,
-                              member.version);
-                } else {
-                    log::warn("    {} (still {}, {})", member.target,
-                              member.version, member.kind);
-                }
-            }
-            log::warn("  move: xlings use {} <version>",
-                      plan->stranded.front().target);
-            log::warn("  drop: xlings remove {}@{}",
-                      plan->stranded.front().target,
-                      plan->stranded.front().version);
-        }
-    }
-
-    // Switching packages: what the old one still owns.
-    //
-    // Silent by default, and that is the point. These names did not fall
-    // behind -- the package they belong to is untouched and still active, and
-    // the incoming package has no version of them to offer. There is no
-    // action to recommend, so a warning would be pure noise on a command that
-    // did exactly what it was asked. The `(A -> B)` clause above already says
-    // the package changed; `-v` is where the list belongs.
-    if (verbose && !plan->retainedByOldPackage.empty()) {
-        log::warn("{} name(s) still come from {}:",
-                  plan->retainedByOldPackage.size(), plan->fromProvider);
-        for (const auto& member : plan->retainedByOldPackage) {
-            if (member.kind == "program") {
-                log::warn("    {} ({})", member.target, member.version);
-            } else {
-                log::warn("    {} ({}, {})", member.target, member.version,
-                          member.kind);
-            }
-        }
-        log::warn("  {} has no version of them to switch to.",
-                  plan->toProvider);
-    }
-
-    xself::print_migration_hint_once(Config::recorded_client_version(),
-                                     Info::VERSION);
-    return 0;
-}
+            EventStream& stream, bool strict = false);
 
 // The versions `xlings use <target>` / the listing panel may choose from.
 //
@@ -752,88 +148,18 @@ struct VersionCandidates {
 // as the exit code the caller should use, so both callers below fail the same
 // way.
 std::expected<VersionCandidates, int>
-collect_version_candidates_(const std::string& target, bool all) {
-    auto db = Config::versions();
-
-    if (!has_target(db, target)) {
-        log::error("'{}' not found in version database", target);
-        return std::unexpected(1);
-    }
-
-    auto workspace = Config::effective_workspace();
-    VersionCandidates out;
-    out.active = get_active_version(workspace, target);
-    auto global_all = get_all_versions(db, target);
-
-    if (all) {
-        out.versions = global_all;
-        out.title = target + " versions (all subos)";
-        return out;
-    }
-
-    out.versions = filter_to_subos_installed_(target, global_all);
-    if (out.versions.empty()) {
-        // Empty subos installed[] for this target — show a hint instead of an
-        // empty panel. The global list is informational so the user can pick
-        // a version to install.
-        log::error("'{}' is not installed in current subos", target);
-        if (!global_all.empty()) {
-            std::string avail;
-            for (auto& v : global_all) {
-                if (!avail.empty()) avail += " ";
-                avail += v;
-            }
-            log::error("  globally available: {}", avail);
-            log::error("  hint: xlings install {}@<version>"
-                       " (or `xlings use {} --all` to see global view)",
-                       target, target);
-        } else {
-            log::error("  hint: xlings install {}", target);
-        }
-        return std::unexpected(1);
-    }
-    out.title = target + " versions (current subos)";
-    return out;
-}
+collect_version_candidates_(const std::string& target, bool all);
 
 void emit_version_panel_(const std::string& target,
                          const VersionCandidates& candidates,
-                         EventStream& stream) {
-    auto db = Config::versions();
-    nlohmann::json fieldsJson = nlohmann::json::array();
-    for (auto& ver : candidates.versions) {
-        auto vdata = get_vdata(db, target, ver);
-        std::string path_info;
-        // `@xlings/...` rather than the absolute path. `self config` and
-        // `self doctor` already abbreviate; this panel did not, and it is the
-        // one whose rows are payload paths — the ~20 columns the prefix costs
-        // are exactly what pushed it past the terminal.
-        if (vdata && !vdata->path.empty()) path_info = Config::display_path(vdata->path);
-        bool highlight = (ver == candidates.active);
-        fieldsJson.push_back({{"label", ver}, {"value", path_info}, {"highlight", highlight}});
-    }
-    nlohmann::json payload;
-    payload["title"] = candidates.title;
-    payload["fields"] = std::move(fieldsJson);
-    stream.emit(DataEvent{"info_panel", payload.dump()});
-}
+                         EventStream& stream);
 
 // List versions for a target. Never switches anything.
 //
 // This is what the `list_installed_versions` capability runs, and the name is
 // the whole contract: a caller that asked to *see* the versions must not come
 // back to a different active toolchain. `use <target>` is below.
-int cmd_list_versions(const std::string& target, EventStream& stream, bool all = false) {
-    auto candidates = collect_version_candidates_(target, all);
-    if (!candidates) return candidates.error();
-    emit_version_panel_(target, *candidates, stream);
-    if (candidates->versions.size() > 1) {
-        nlohmann::json tip;
-        tip["message"] = std::format("xlings use {} <version>", target);
-        stream.emit(DataEvent{"tip", tip.dump()});
-    }
-    return 0;
-}
+int cmd_list_versions(const std::string& target, EventStream& stream, bool all = false);
 
 // `xlings use <target>` with no version — deterministic, or it lists.
 //
@@ -874,28 +200,13 @@ int cmd_list_versions(const std::string& target, EventStream& stream, bool all =
 // door; once the default path is deterministic, it is one more path to
 // maintain, test and document for a problem that no longer exists.
 int cmd_use_by_name(const std::string& target, EventStream& stream,
-                    bool all = false, bool strict = false) {
-    auto candidates = collect_version_candidates_(target, all);
-    if (!candidates) return candidates.error();
-
-    // Unambiguous: there is nothing to ask about. This also covers the
-    // documented sysroot-repair use of `use` -- switching to the version that
-    // is already active re-materializes headers and libraries.
-    if (candidates->versions.size() == 1) {
-        return cmd_use(target, candidates->versions.front(), stream, strict);
-    }
-
-    return cmd_list_versions(target, stream, all);
-}
+                    bool all = false, bool strict = false);
 
 // Register a version in the global database (called after xim install)
 void register_version(const std::string& target,
                       const std::string& version,
                       const std::string& path,
                       const std::string& type,
-                      const std::string& filename) {
-    add_version(Config::versions_mut(), target, version, path, type, filename);
-    Config::save_versions();
-}
+                      const std::string& filename);
 
 } // namespace xlings::xvm
diff --git a/src/core/xvm/db.cpp b/src/core/xvm/db.cpp
new file mode 100644
index 00000000..c5cb7f48
--- /dev/null
+++ b/src/core/xvm/db.cpp
@@ -0,0 +1,1045 @@
+module xlings.core.xvm.db;
+
+import std;
+import xlings.core.xvm.types;
+import xlings.libs.json;
+import xlings.platform;
+
+namespace xlings::xvm {
+
+std::pair<std::string, std::string> parse_ns_version(const std::string& s) {
+    auto pos = s.find(':');
+    if (pos == std::string::npos) return {"", s};
+    return {s.substr(0, pos), s.substr(pos + 1)};
+}
+
+std::string make_ns_version(const std::string& ns, const std::string& ver) {
+    if (ns.empty()) return ver;
+    return ns + ":" + ver;
+}
+
+std::string strip_namespace(const std::string& s) {
+    return parse_ns_version(s).second;
+}
+
+std::string get_namespace(const std::string& s) {
+    return parse_ns_version(s).first;
+}
+
+std::string display_coordinate(std::string_view target,
+                               std::string_view versionKey) {
+    if (versionKey.empty()) return std::string(target);
+    const auto [ns, version] = parse_ns_version(std::string(versionKey));
+    if (ns.empty()) return std::format("{}@{}", target, version);
+    return std::format("{}:{}@{}", ns, target, version);
+}
+
+void add_version(VersionDB& db, const std::string& target, const std::string& version, const std::string& path, const std::string& type, const std::string& filename, const std::string& alias, const std::string& ns, const std::string& binding) {
+    auto& info = db[target];
+    if (info.type.empty()) info.type = type;
+    if (info.filename.empty() && !filename.empty()) info.filename = filename;
+
+    auto ver_key = make_ns_version(ns, version);
+    VData vdata;
+    vdata.path = path;
+    vdata.kind = type;
+    if (type != "group") {
+        vdata.sourceName = filename.empty() ? target : filename;
+        vdata.destinationName =
+            type == "program" ? target : vdata.sourceName;
+    }
+    if (!alias.empty()) vdata.alias.push_back(alias);
+    info.versions[ver_key] = std::move(vdata);
+
+    // Establish bidirectional binding relationship
+    if (!binding.empty()) {
+        auto at = binding.find('@');
+        if (at != std::string::npos) {
+            auto peer = binding.substr(0, at);
+            auto peer_ver = make_ns_version(ns, binding.substr(at + 1));
+            // Bidirectional: peer records target, target records peer
+            db[peer].bindings[target][peer_ver] = ver_key;
+            db[target].bindings[peer][ver_key] = peer_ver;
+        }
+    }
+}
+
+std::expected<std::string, RemovalError>
+resolve_exact_version_key(const VersionDB& db,
+                          const std::string& target,
+                          const std::string& version) {
+    auto it = db.find(target);
+    if (it == db.end() || version.empty()) {
+        return std::unexpected(RemovalError{
+            .kind = RemovalErrorKind::VersionNotFound,
+            .target = target,
+            .version = version,
+            .message = "removal version is missing",
+        });
+    }
+
+    if (version.find(':') != std::string::npos) {
+        if (it->second.versions.contains(version)) return version;
+        return std::unexpected(RemovalError{
+            .kind = RemovalErrorKind::VersionNotFound,
+            .target = target,
+            .version = version,
+            .message = "exact removal version is not registered",
+        });
+    }
+
+    std::vector<std::string> matches;
+    for (const auto& [storedVersion, _] : it->second.versions) {
+        if (strip_namespace(storedVersion) == version) {
+            matches.push_back(storedVersion);
+        }
+    }
+    if (matches.size() == 1) return matches.front();
+    if (matches.empty()) {
+        return std::unexpected(RemovalError{
+            .kind = RemovalErrorKind::VersionNotFound,
+            .target = target,
+            .version = version,
+            .message = "removal version is not registered",
+        });
+    }
+    return std::unexpected(RemovalError{
+        .kind = RemovalErrorKind::AmbiguousVersion,
+        .target = target,
+        .version = version,
+        .message = std::format(
+            "bare removal version '{}' matches {} stored versions",
+            version, matches.size()),
+    });
+}
+
+std::expected<std::string, RemovalError>
+remove_version(VersionDB& db,
+               const std::string& target,
+               const std::string& version) {
+    auto exactVersionResult =
+        resolve_exact_version_key(db, target, version);
+    if (!exactVersionResult) {
+        return std::unexpected(std::move(exactVersionResult.error()));
+    }
+    const auto& exactVersion = *exactVersionResult;
+
+    auto it = db.find(target);
+    auto& vers = it->second.versions;
+
+    std::vector<std::pair<std::string, std::string>> edges;
+    for (const auto& [peerTarget, versions] : it->second.bindings) {
+        if (auto edgeIt = versions.find(exactVersion);
+            edgeIt != versions.end()) {
+            edges.emplace_back(peerTarget, edgeIt->second);
+        }
+    }
+
+    for (const auto& [peerTarget, peerVersion] : edges) {
+        auto peerIt = db.find(peerTarget);
+        const auto reciprocal =
+            peerIt != db.end()
+            && peerIt->second.versions.contains(peerVersion)
+            && peerIt->second.bindings.contains(target)
+            && peerIt->second.bindings.at(target).contains(peerVersion)
+            && peerIt->second.bindings.at(target).at(peerVersion)
+                == exactVersion;
+        if (!reciprocal) {
+            return std::unexpected(RemovalError{
+                .kind = RemovalErrorKind::AsymmetricEdge,
+                .target = target,
+                .version = exactVersion,
+                .peerTarget = peerTarget,
+                .peerVersion = peerVersion,
+                .message = "removal binding edge is not reciprocal",
+            });
+        }
+    }
+
+    for (const auto& [peerTarget, peerInfo] : db) {
+        auto incomingIt = peerInfo.bindings.find(target);
+        if (incomingIt == peerInfo.bindings.end()) continue;
+        for (const auto& [peerVersion, targetVersion] : incomingIt->second) {
+            if (targetVersion != exactVersion) continue;
+            const auto reciprocal =
+                peerInfo.versions.contains(peerVersion)
+                && it->second.bindings.contains(peerTarget)
+                && it->second.bindings.at(peerTarget).contains(exactVersion)
+                && it->second.bindings.at(peerTarget).at(exactVersion)
+                    == peerVersion;
+            if (!reciprocal) {
+                return std::unexpected(RemovalError{
+                    .kind = RemovalErrorKind::AsymmetricEdge,
+                    .target = target,
+                    .version = exactVersion,
+                    .peerTarget = peerTarget,
+                    .peerVersion = peerVersion,
+                    .message = "incoming removal binding edge is not reciprocal",
+                });
+            }
+        }
+    }
+
+    for (const auto& [peerTarget, peerVersion] : edges) {
+        auto bindingIt = it->second.bindings.find(peerTarget);
+        bindingIt->second.erase(exactVersion);
+        if (bindingIt->second.empty()) {
+            it->second.bindings.erase(bindingIt);
+        }
+
+        auto peerIt = db.find(peerTarget);
+        if (peerIt == db.end()) continue;
+        auto reverseIt = peerIt->second.bindings.find(target);
+        if (reverseIt == peerIt->second.bindings.end()) continue;
+        reverseIt->second.erase(peerVersion);
+        if (reverseIt->second.empty()) {
+            peerIt->second.bindings.erase(reverseIt);
+        }
+    }
+
+    vers.erase(exactVersion);
+    if (vers.empty() && it->second.bindings.empty()) db.erase(it);
+    return exactVersion;
+}
+
+bool version_key_greater(const std::string& lhs, const std::string& rhs) {
+    const auto split = [](const std::string& s) {
+        std::vector<std::string> parts;
+        std::istringstream iss(s);
+        std::string part;
+        while (std::getline(iss, part, '.')) parts.push_back(part);
+        return parts;
+    };
+    const auto pa = split(strip_namespace(lhs));
+    const auto pb = split(strip_namespace(rhs));
+    for (std::size_t i = 0; i < std::min(pa.size(), pb.size()); ++i) {
+        int na = 0, nb = 0;
+        std::from_chars(pa[i].data(), pa[i].data() + pa[i].size(), na);
+        std::from_chars(pb[i].data(), pb[i].data() + pb[i].size(), nb);
+        if (na != nb) return na > nb;
+    }
+    if (pa.size() != pb.size()) return pa.size() > pb.size();
+    return lhs < rhs;
+}
+
+std::string pick_highest_version(const std::map<std::string, VData>& versions) {
+    if (versions.empty()) return {};
+
+    std::vector<std::string> keys;
+    keys.reserve(versions.size());
+    for (auto& [k, _] : versions) keys.push_back(k);
+
+    std::ranges::sort(keys, version_key_greater);
+
+    return keys.front();
+}
+
+std::string match_version(const VersionDB& db,
+                          const std::string& target,
+                          const std::string& prefix) {
+    auto it = db.find(target);
+    if (it == db.end()) return {};
+
+    auto& versions = it->second.versions;
+
+    // Exact match first
+    if (versions.contains(prefix)) return prefix;
+
+    auto [input_ns, input_ver] = parse_ns_version(prefix);
+
+    auto split = [](const std::string& s) -> std::vector<std::string> {
+        std::vector<std::string> parts;
+        std::istringstream iss(s);
+        std::string part;
+        while (std::getline(iss, part, '.')) {
+            parts.push_back(part);
+        }
+        return parts;
+    };
+
+    auto sort_desc = [&](std::vector<std::string>& candidates) {
+        std::ranges::sort(candidates, [&](const std::string& a, const std::string& b) {
+            auto pa = split(strip_namespace(a));
+            auto pb = split(strip_namespace(b));
+            for (std::size_t i = 0; i < std::min(pa.size(), pb.size()); ++i) {
+                int na = 0, nb = 0;
+                std::from_chars(pa[i].data(), pa[i].data() + pa[i].size(), na);
+                std::from_chars(pb[i].data(), pb[i].data() + pb[i].size(), nb);
+                if (na != nb) return na > nb;
+            }
+            return pa.size() > pb.size();
+        });
+    };
+
+    auto input_parts = split(input_ver);
+
+    auto prefix_matches = [&](const std::string& bare_ver) -> bool {
+        auto ver_parts = split(bare_ver);
+        if (ver_parts.size() < input_parts.size()) return false;
+        for (std::size_t i = 0; i < input_parts.size(); ++i) {
+            if (input_parts[i] != ver_parts[i]) return false;
+        }
+        return true;
+    };
+
+    // If namespace specified, only match within that namespace
+    if (!input_ns.empty()) {
+        std::vector<std::string> candidates;
+        for (auto& [ver, _] : versions) {
+            auto [ver_ns, bare_ver] = parse_ns_version(ver);
+            if (ver_ns == input_ns && prefix_matches(bare_ver))
+                candidates.push_back(ver);
+        }
+        if (candidates.empty()) return {};
+        sort_desc(candidates);
+        return candidates[0];
+    }
+
+    // No namespace: prefer bare (unqualified) versions first
+    std::vector<std::string> bare_candidates;
+    std::vector<std::string> ns_candidates;
+    for (auto& [ver, _] : versions) {
+        auto [ver_ns, bare_ver] = parse_ns_version(ver);
+        if (prefix_matches(bare_ver)) {
+            if (ver_ns.empty())
+                bare_candidates.push_back(ver);
+            else
+                ns_candidates.push_back(ver);
+        }
+    }
+
+    if (!bare_candidates.empty()) {
+        sort_desc(bare_candidates);
+        return bare_candidates[0];
+    }
+    if (!ns_candidates.empty()) {
+        sort_desc(ns_candidates);
+        return ns_candidates[0];
+    }
+    return {};
+}
+
+std::string get_active_version(const Workspace& workspace,
+                               const std::string& target) {
+    auto it = workspace.find(target);
+    return it != workspace.end() ? it->second : std::string{};
+}
+
+bool has_target(const VersionDB& db, const std::string& target) {
+    return db.contains(target);
+}
+
+bool has_version(const VersionDB& db,
+                 const std::string& target,
+                 const std::string& version) {
+    auto it = db.find(target);
+    if (it == db.end()) return false;
+    return it->second.versions.contains(version);
+}
+
+std::vector<std::string> get_all_versions(const VersionDB& db,
+                                          const std::string& target) {
+    std::vector<std::string> result;
+    auto it = db.find(target);
+    if (it == db.end()) return result;
+    for (auto& [ver, _] : it->second.versions) {
+        result.push_back(ver);
+    }
+    return result;
+}
+
+const VData* get_vdata(const VersionDB& db,
+                       const std::string& target,
+                       const std::string& version) {
+    auto it = db.find(target);
+    if (it == db.end()) return nullptr;
+    auto vit = it->second.versions.find(version);
+    if (vit == it->second.versions.end()) return nullptr;
+    return &vit->second;
+}
+
+const VInfo* get_vinfo(const VersionDB& db, const std::string& target) {
+    auto it = db.find(target);
+    if (it == db.end()) return nullptr;
+    return &it->second;
+}
+
+std::string get_binding(const VersionDB& db,
+                        const std::string& target,
+                        const std::string& binding_name,
+                        const std::string& version) {
+    auto it = db.find(target);
+    if (it == db.end()) return {};
+    auto bit = it->second.bindings.find(binding_name);
+    if (bit == it->second.bindings.end()) return {};
+    auto vit = bit->second.find(version);
+    if (vit == bit->second.end()) return {};
+    return vit->second;
+}
+
+std::string normalize_subos_paths(const std::string& text,
+                                  const std::string& xlings_home,
+                                  const std::string& active_subos_dir) {
+    if (active_subos_dir.empty() || text.empty()) return text;
+
+    static constexpr std::string_view kPosix = "/subos/";
+    static constexpr std::string_view kWin   = "\\subos\\";
+
+    auto is_sep = [](char c) { return c == '/' || c == '\\'; };
+    // Where a path token can start: whitespace, plus the punctuation that
+    // glues a path onto a flag (`--sysroot=`, `PATH=a:b`, quotes).
+    auto is_boundary = [](char c) {
+        return c == ' ' || c == '\t' || c == '=' || c == ':' || c == ';'
+            || c == ',' || c == '"' || c == '\'';
+    };
+    auto is_alpha = [](char c) {
+        return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
+    };
+    auto path_equal = [](std::string_view a, std::string_view b) {
+#if defined(_WIN32)
+        // Windows compares paths case-insensitively and treats / and \ alike.
+        if (a.size() != b.size()) return false;
+        auto fold = [](char c) -> char {
+            if (c == '\\') return '/';
+            if (c >= 'A' && c <= 'Z') return static_cast<char>(c - 'A' + 'a');
+            return c;
+        };
+        for (std::size_t i = 0; i < a.size(); ++i) {
+            if (fold(a[i]) != fold(b[i])) return false;
+        }
+        return true;
+#else
+        return a == b;
+#endif
+    };
+
+    std::string out;
+    out.reserve(text.size());
+    std::size_t cursor = 0;
+
+    while (cursor < text.size()) {
+        auto p1 = text.find(kPosix, cursor);
+        auto p2 = text.find(kWin, cursor);
+        auto hit = std::min(p1, p2);   // npos is max, so min() picks the real one
+        if (hit == std::string::npos) break;
+
+        // Widen left to the start of the path token.
+        std::size_t start = hit;
+        while (start > cursor && !is_boundary(text[start - 1])) --start;
+        // ':' is a boundary (PATH=a:b), which would cut the drive letter off
+        // `--sysroot=C:\Users\...`: the prefix becomes `\Users\u\.xlings` and
+        // the replacement splices a second drive spec onto the surviving `C:`.
+        // Step back over a drive letter that is itself token-initial.
+        if (start >= cursor + 2 && text[start - 1] == ':'
+            && is_alpha(text[start - 2])
+            && (start < cursor + 3 || is_boundary(text[start - 3]))) {
+            start -= 2;
+        }
+        // A flag can sit flush against the path with no boundary between them
+        // (`-B/h/.xlings/subos/a`), and the walk above happily swallows it.
+        // Skip forward to where the path actually begins -- a separator, or a
+        // drive letter -- so the replacement never eats the flag.
+        const bool drive =
+            start + 1 < hit && is_alpha(text[start]) && text[start + 1] == ':';
+        if (!drive) {
+            while (start < hit && !is_sep(text[start])) {
+                if (start + 1 < hit && is_alpha(text[start])
+                    && text[start + 1] == ':') {
+                    break;   // `-BC:\...`
+                }
+                ++start;
+            }
+        }
+        std::string_view prefix(text.data() + start, hit - start);
+
+        // Right: the subos NAME segment only. Everything after it (`/usr/
+        // include`, …) is the caller's business and is preserved.
+        std::size_t nameStart = hit + kPosix.size();
+        std::size_t nameEnd = nameStart;
+        while (nameEnd < text.size()
+               && !is_sep(text[nameEnd]) && !is_boundary(text[nameEnd])) {
+            ++nameEnd;
+        }
+
+        const bool ours =
+            path_equal(prefix, xlings_home)
+            || (prefix.size() >= 7
+                && path_equal(prefix.substr(prefix.size() - 7), ".xlings"));
+
+        if (!ours || nameEnd == nameStart) {
+            out.append(text, cursor, nameEnd - cursor);   // passthrough
+        } else {
+            out.append(text, cursor, start - cursor);
+            out.append(active_subos_dir);
+        }
+        cursor = nameEnd;
+    }
+    out.append(text, cursor, std::string::npos);
+    return out;
+}
+
+std::string pin_subos_paths(const std::string& text,
+                            const std::string& xlings_home) {
+    return normalize_subos_paths(text, xlings_home,
+                                 std::string(kSubosPlaceholder));
+}
+
+std::optional<std::string> vanishing_xlings_reference(std::string_view text) {
+    constexpr std::string_view kPrefix = "${XLINGS_";
+    std::size_t pos = 0;
+    while ((pos = text.find(kPrefix, pos)) != std::string_view::npos) {
+        auto close = text.find('}', pos + kPrefix.size());
+        if (close == std::string_view::npos) break;  // unterminated; not ours to judge
+        auto name = std::string(
+            text.substr(pos + 2, close - (pos + 2)));   // strip "${" and "}"
+        const char* value = std::getenv(name.c_str());
+        if (value == nullptr || *value == '\0') return name;
+        pos = close + 1;
+    }
+    return std::nullopt;
+}
+
+std::string expand_subos_placeholder(const std::string& text,
+                                     const std::string& subos_dir) {
+    if (subos_dir.empty() || text.empty()) return text;
+    std::string result = text;
+    std::size_t pos = 0;
+    while ((pos = result.find(kSubosPlaceholder, pos)) != std::string::npos) {
+        result.replace(pos, kSubosPlaceholder.size(), subos_dir);
+        pos += subos_dir.size();
+    }
+    return result;
+}
+
+std::string expand_path(const std::string& path, const std::string& xlings_home) {
+    std::string result = path;
+    const std::string placeholder = "${XLINGS_HOME}";
+    std::size_t pos = 0;
+    while ((pos = result.find(placeholder, pos)) != std::string::npos) {
+        result.replace(pos, placeholder.size(), xlings_home);
+        pos += xlings_home.size();
+    }
+    return result;
+}
+
+nlohmann::json vdata_to_json(const VData& vdata) {
+    nlohmann::json j;
+    j["path"] = vdata.path;
+    if (!vdata.kind.empty()) j["kind"] = vdata.kind;
+    if (!vdata.sourceName.empty()) j["sourceName"] = vdata.sourceName;
+    if (!vdata.destinationName.empty())
+        j["destinationName"] = vdata.destinationName;
+    if (!vdata.fileSrc.empty()) j["fileSrc"] = vdata.fileSrc;
+    if (!vdata.fileDst.empty()) j["fileDst"] = vdata.fileDst;
+    if (!vdata.includedir.empty()) j["includedir"] = vdata.includedir;
+    if (!vdata.libdir.empty()) j["libdir"] = vdata.libdir;
+    if (!vdata.alias.empty()) {
+        j["alias"] = vdata.alias;
+    }
+    if (!vdata.envs.empty()) {
+        nlohmann::json envs_j = nlohmann::json::object();
+        for (auto it = vdata.envs.begin(); it != vdata.envs.end(); ++it) {
+            envs_j[it->first] = it->second;
+        }
+        j["envs"] = envs_j;
+    }
+    if (vdata.bindingGroup) {
+        j["bindingGroup"] = {
+            {"provider", vdata.bindingGroup->provider},
+            {"version", vdata.bindingGroup->providerVersion},
+            {"group", vdata.bindingGroup->group},
+            {"rootTarget", vdata.bindingGroup->rootTarget},
+            {"rootVersion", vdata.bindingGroup->rootVersion},
+        };
+    }
+    if (vdata.bindingMembersDeclared || !vdata.bindingMembers.empty()) {
+        nlohmann::json members = nlohmann::json::object();
+        for (const auto& [target, version] : vdata.bindingMembers) {
+            members[target] = version;
+        }
+        j["bindingMembers"] = std::move(members);
+    }
+    if (vdata.bindingHeadersDeclared || !vdata.bindingHeaders.empty()) {
+        nlohmann::json headers = nlohmann::json::array();
+        for (const auto& header : vdata.bindingHeaders) {
+            headers.push_back({
+                {"sourceDir", header.sourceDir},
+                {"destinationPrefix", header.destinationPrefix},
+            });
+        }
+        j["bindingHeaders"] = std::move(headers);
+    }
+    if (!vdata.bindingIntegrityIssues.empty()) {
+        nlohmann::json issues = nlohmann::json::array();
+        for (const auto& issue : vdata.bindingIntegrityIssues) {
+            issues.push_back({
+                {"code", issue.code},
+                {"path", issue.path},
+            });
+        }
+        j["bindingIntegrityIssues"] = std::move(issues);
+    }
+    // Preserved originals win over the reconstructed view.
+    //
+    // For a field we could not read, the parsed model holds at best a subset
+    // -- the members that happened to be well-formed, a group with the
+    // unreadable keys blanked. Writing that back is the silent rewrite this
+    // whole mechanism exists to stop, so the original text is restored last
+    // and overwrites whatever the blocks above produced for that key.
+    for (const auto& [field, text] : vdata.bindingUnreadable) {
+        try {
+            j[field] = nlohmann::json::parse(text);
+        } catch (const std::exception&) {
+            // Unreachable in practice: the text came from dump(). If it ever
+            // is, keeping the reconstructed value beats dropping the field.
+        }
+    }
+    return j;
+}
+
+VData vdata_from_json(const nlohmann::json& j) {
+    VData vdata;
+    const auto recordIssue =
+        [&vdata](std::string code, std::string path) {
+            const auto duplicate = std::ranges::any_of(
+                vdata.bindingIntegrityIssues,
+                [&](const BindingIntegrityIssue& issue) {
+                    return issue.code == code && issue.path == path;
+                });
+            if (duplicate) return;
+            vdata.bindingIntegrityIssues.push_back({
+                .code = std::move(code),
+                .path = std::move(path),
+            });
+        };
+    const auto pointerToken = [](std::string_view token) {
+        std::string escaped;
+        escaped.reserve(token.size());
+        for (char ch : token) {
+            if (ch == '~') {
+                escaped += "~0";
+            } else if (ch == '/') {
+                escaped += "~1";
+            } else {
+                escaped += ch;
+            }
+        }
+        return escaped;
+    };
+
+    if (j.contains("path") && j["path"].is_string())
+        vdata.path = j["path"].get<std::string>();
+    if (j.contains("kind") && j["kind"].is_string())
+        vdata.kind = j["kind"].get<std::string>();
+    if (j.contains("sourceName") && j["sourceName"].is_string())
+        vdata.sourceName = j["sourceName"].get<std::string>();
+    if (j.contains("destinationName") && j["destinationName"].is_string())
+        vdata.destinationName = j["destinationName"].get<std::string>();
+    if (j.contains("fileSrc") && j["fileSrc"].is_string())
+        vdata.fileSrc = j["fileSrc"].get<std::string>();
+    if (j.contains("fileDst") && j["fileDst"].is_string())
+        vdata.fileDst = j["fileDst"].get<std::string>();
+    if (j.contains("includedir") && j["includedir"].is_string())
+        vdata.includedir = j["includedir"].get<std::string>();
+    if (j.contains("libdir") && j["libdir"].is_string())
+        vdata.libdir = j["libdir"].get<std::string>();
+    if (j.contains("alias") && j["alias"].is_array()) {
+        for (auto& a : j["alias"]) {
+            if (a.is_string()) vdata.alias.push_back(a.get<std::string>());
+        }
+    }
+    if (j.contains("envs") && j["envs"].is_object()) {
+        auto& envs = j["envs"];
+        for (auto it = envs.begin(); it != envs.end(); ++it) {
+            if (it.value().is_string())
+                vdata.envs[it.key()] = it.value().get<std::string>();
+        }
+    }
+    if (j.contains("bindingIntegrityIssues")) {
+        if (!j["bindingIntegrityIssues"].is_array()) {
+            recordIssue(
+                "binding-integrity-issues-not-array",
+                "/bindingIntegrityIssues");
+        } else {
+            std::size_t index = 0;
+            for (const auto& issueJson : j["bindingIntegrityIssues"]) {
+                const auto issuePath =
+                    "/bindingIntegrityIssues/" + std::to_string(index++);
+                if (!issueJson.is_object()) {
+                    recordIssue(
+                        "binding-integrity-issue-not-object",
+                        issuePath);
+                    continue;
+                }
+
+                const auto validCode =
+                    issueJson.contains("code")
+                    && issueJson["code"].is_string()
+                    && !issueJson["code"].get_ref<
+                        const std::string&>().empty();
+                const auto validPath =
+                    issueJson.contains("path")
+                    && issueJson["path"].is_string()
+                    && !issueJson["path"].get_ref<
+                        const std::string&>().empty();
+                if (!validCode) {
+                    recordIssue(
+                        "binding-integrity-issue-field-invalid",
+                        issuePath + "/code");
+                }
+                if (!validPath) {
+                    recordIssue(
+                        "binding-integrity-issue-field-invalid",
+                        issuePath + "/path");
+                }
+                if (validCode && validPath) {
+                    recordIssue(
+                        issueJson["code"].get<std::string>(),
+                        issueJson["path"].get<std::string>());
+                }
+            }
+        }
+    }
+    if (j.contains("bindingGroup")) {
+        if (!j["bindingGroup"].is_object()) {
+            recordIssue(
+                "binding-group-not-object", "/bindingGroup");
+        } else {
+            const auto& group = j["bindingGroup"];
+            BindingGroupRef ref;
+            const auto parseGroupField =
+                [&](std::string_view name, std::string& destination) {
+                    const auto key = std::string(name);
+                    if (group.contains(key)
+                        && group[key].is_string()
+                        && !group[key].get_ref<
+                            const std::string&>().empty()) {
+                        destination = group[key].get<std::string>();
+                    } else {
+                        recordIssue(
+                            "binding-group-field-invalid",
+                            "/bindingGroup/" + key);
+                    }
+                };
+            parseGroupField("provider", ref.provider);
+            parseGroupField("version", ref.providerVersion);
+            parseGroupField("group", ref.group);
+            parseGroupField("rootTarget", ref.rootTarget);
+            parseGroupField("rootVersion", ref.rootVersion);
+            vdata.bindingGroup = std::move(ref);
+        }
+    }
+    if (j.contains("bindingMembers")) {
+        vdata.bindingMembersDeclared = true;
+        if (!j["bindingMembers"].is_object()) {
+            recordIssue(
+                "binding-members-not-object", "/bindingMembers");
+        } else {
+            const auto& members = j["bindingMembers"];
+            for (auto it = members.begin(); it != members.end(); ++it) {
+                const auto validTarget = !it.key().empty();
+                if (!validTarget) {
+                    recordIssue(
+                        "binding-member-target-empty",
+                        "/bindingMembers/");
+                }
+                if (!it.value().is_string()) {
+                    recordIssue(
+                        "binding-member-version-not-string",
+                        "/bindingMembers/" + pointerToken(it.key()));
+                } else if (it.value().get_ref<
+                               const std::string&>().empty()) {
+                    recordIssue(
+                        "binding-member-version-empty",
+                        "/bindingMembers/" + pointerToken(it.key()));
+                } else if (validTarget) {
+                    vdata.bindingMembers[it.key()] =
+                        it.value().get<std::string>();
+                }
+            }
+        }
+    }
+    if (j.contains("bindingHeaders")) {
+        vdata.bindingHeadersDeclared = true;
+        if (!j["bindingHeaders"].is_array()) {
+            recordIssue(
+                "binding-headers-not-array", "/bindingHeaders");
+        } else {
+            std::size_t index = 0;
+            for (const auto& headerJson : j["bindingHeaders"]) {
+                const auto headerPath =
+                    "/bindingHeaders/" + std::to_string(index++);
+                if (!headerJson.is_object()) {
+                    recordIssue("binding-header-not-object", headerPath);
+                    continue;
+                }
+                if (!headerJson.contains("sourceDir")
+                    || !headerJson["sourceDir"].is_string()) {
+                    recordIssue(
+                        "binding-header-source-dir-not-string",
+                        headerPath + "/sourceDir");
+                    continue;
+                }
+                if (headerJson["sourceDir"].get_ref<
+                        const std::string&>().empty()) {
+                    recordIssue(
+                        "binding-header-source-dir-empty",
+                        headerPath + "/sourceDir");
+                    continue;
+                }
+                if (headerJson.contains("destinationPrefix")
+                    && !headerJson["destinationPrefix"].is_string()) {
+                    recordIssue(
+                        "binding-header-destination-prefix-not-string",
+                        headerPath + "/destinationPrefix");
+                    continue;
+                }
+
+                HeaderAsset header{
+                    .sourceDir =
+                        headerJson["sourceDir"].get<std::string>(),
+                };
+                if (headerJson.contains("destinationPrefix")) {
+                    header.destinationPrefix =
+                        headerJson["destinationPrefix"].get<std::string>();
+                }
+                vdata.bindingHeaders.push_back(std::move(header));
+            }
+        }
+    }
+    if ((j.contains("bindingMembers") || j.contains("bindingHeaders"))
+        && !vdata.bindingGroup) {
+        recordIssue("binding-group-missing", "/bindingGroup");
+    }
+
+    // Keep the original text of every binding field we could not fully read.
+    //
+    // Without this the next save rewrites the entry from the parsed model and
+    // whatever did not fit is gone -- the marker survives, the data does not.
+    // That is why `--reset-metadata` could not be offered before: there was
+    // nothing left to reset from, and the destruction had already happened
+    // silently on the first save after the corruption.
+    //
+    // Whole-field granularity: a field with one bad member is re-emitted
+    // entire, because a partial re-emission is exactly the lossy rewrite this
+    // is here to prevent.
+    for (const auto& issue : vdata.bindingIntegrityIssues) {
+        static constexpr std::string_view fields[] = {
+            "bindingGroup", "bindingMembers",
+            "bindingHeaders", "bindingIntegrityIssues",
+        };
+        for (const auto field : fields) {
+            const auto prefix = "/" + std::string(field);
+            if (!issue.path.starts_with(prefix)) continue;
+            // `binding-group-missing` names a field that is not there; there
+            // is nothing to preserve and nothing was lost.
+            const auto key = std::string(field);
+            if (!j.contains(key)) break;
+            vdata.bindingUnreadable.emplace(key, j[key].dump());
+            break;
+        }
+    }
+    return vdata;
+}
+
+nlohmann::json vinfo_to_json(const VInfo& info) {
+    nlohmann::json j;
+    if (!info.type.empty()) j["type"] = info.type;
+    if (!info.filename.empty()) j["filename"] = info.filename;
+
+    nlohmann::json vers = nlohmann::json::object();
+    for (auto it = info.versions.begin(); it != info.versions.end(); ++it) {
+        vers[it->first] = vdata_to_json(it->second);
+    }
+    j["versions"] = vers;
+
+    if (!info.bindings.empty()) {
+        nlohmann::json binds = nlohmann::json::object();
+        for (auto it = info.bindings.begin(); it != info.bindings.end(); ++it) {
+            nlohmann::json vermap_j = nlohmann::json::object();
+            for (auto vit = it->second.begin(); vit != it->second.end(); ++vit) {
+                vermap_j[vit->first] = vit->second;
+            }
+            binds[it->first] = vermap_j;
+        }
+        j["bindings"] = binds;
+    }
+
+    return j;
+}
+
+VInfo vinfo_from_json(const nlohmann::json& j) {
+    VInfo info;
+    if (j.contains("type") && j["type"].is_string())
+        info.type = j["type"].get<std::string>();
+    if (j.contains("filename") && j["filename"].is_string())
+        info.filename = j["filename"].get<std::string>();
+    if (j.contains("versions") && j["versions"].is_object()) {
+        auto& vers = j["versions"];
+        for (auto it = vers.begin(); it != vers.end(); ++it) {
+            info.versions[it.key()] = vdata_from_json(it.value());
+        }
+    }
+    if (j.contains("bindings") && j["bindings"].is_object()) {
+        auto& binds = j["bindings"];
+        for (auto it = binds.begin(); it != binds.end(); ++it) {
+            if (it.value().is_object()) {
+                std::map<std::string, std::string> vermap;
+                for (auto vit = it.value().begin(); vit != it.value().end(); ++vit) {
+                    if (vit.value().is_string())
+                        vermap[vit.key()] = vit.value().get<std::string>();
+                }
+                info.bindings[it.key()] = std::move(vermap);
+            }
+        }
+    }
+    return info;
+}
+
+nlohmann::json versions_to_json(const VersionDB& db) {
+    nlohmann::json j = nlohmann::json::object();
+    for (auto it = db.begin(); it != db.end(); ++it) {
+        j[it->first] = vinfo_to_json(it->second);
+    }
+    return j;
+}
+
+VersionDB versions_from_json(const nlohmann::json& j) {
+    VersionDB db;
+    if (!j.is_object()) return db;
+    for (auto it = j.begin(); it != j.end(); ++it) {
+        db[it.key()] = vinfo_from_json(it.value());
+    }
+    return db;
+}
+
+Workspace workspace_from_json(const nlohmann::json& j) {
+    Workspace ws;
+    if (!j.is_object()) return ws;
+    for (auto it = j.begin(); it != j.end(); ++it) {
+        if (auto resolved = resolve_platform_workspace_value_(it.value())) {
+            ws[it.key()] = *resolved;
+        }
+    }
+    return ws;
+}
+
+nlohmann::json workspace_to_json(const Workspace& ws) {
+    nlohmann::json j = nlohmann::json::object();
+    for (auto it = ws.begin(); it != ws.end(); ++it) {
+        j[it->first] = it->second;
+    }
+    return j;
+}
+
+SubosWorkspace subos_workspace_from_json(const nlohmann::json& j) {
+    SubosWorkspace sws;
+    if (!j.is_object()) return sws;
+
+    // An active version is an installed version -- on read as well as on
+    // write.
+    //
+    // subos_workspace_to_json has always normalised `installed[]` to contain
+    // `active` ("write-time invariant: an active version is implicitly
+    // installed"), but the parser did not apply the same rule, so a record
+    // saying "this subos is on 1.0.0" parsed as "this subos has installed
+    // nothing". That was invisible while `use` opted a subos in silently;
+    // once `use` requires the version to be installed here (2026.7.31.3), it
+    // would refuse the very version the file says is active -- on every home
+    // written by a pre-0.4.19 client, and on every hand-written
+    // platform-conditional entry. Applying the invariant on both sides makes
+    // the round trip a fixed point.
+    //
+    // A lambda rather than a namespace-scope helper on purpose: GCC 16 ICEs
+    // when the first instantiation of a std container over a module-attached
+    // type is required from namespace scope, and the crash leaves a truncated
+    // BMI that reports itself as "Bad file data" in unrelated translation
+    // units.
+    auto set_active = [&sws](const std::string& key, std::string active) {
+        if (active.empty()) return;
+        auto& installed = sws.installed[key];
+        if (std::find(installed.begin(), installed.end(), active)
+                == installed.end()) {
+            installed.push_back(active);
+        }
+        sws.active[key] = std::move(active);
+    };
+
+    for (auto it = j.begin(); it != j.end(); ++it) {
+        const auto& key = it.key();
+        const auto& value = it.value();
+
+        if (value.is_string()) {
+            // Legacy form: bare version string.
+            set_active(key, value.get<std::string>());
+            continue;
+        }
+
+        if (!value.is_object()) continue;
+
+        // Form (2): C2 object form
+        bool hasActive = value.contains("active");
+        bool hasInstalled = value.contains("installed");
+        if (hasActive || hasInstalled) {
+            if (hasInstalled && value.at("installed").is_array()) {
+                std::vector<std::string> installed;
+                for (auto& v : value.at("installed")) {
+                    if (v.is_string()) installed.push_back(v.get<std::string>());
+                }
+                if (!installed.empty()) sws.installed[key] = std::move(installed);
+            }
+            if (hasActive && value.at("active").is_string()) {
+                set_active(key, value.at("active").get<std::string>());
+            }
+            continue;
+        }
+
+        // Form (3): platform-conditional fallback. Reuses the project-style
+        // resolver — subos files don't normally carry this shape, but
+        // honoring it here means a hand-edited subos file with platform
+        // branches behaves the same way the project manifest would.
+        if (auto resolved = resolve_platform_workspace_value_(value)) {
+            set_active(key, *resolved);
+        }
+    }
+
+    return sws;
+}
+
+nlohmann::json subos_workspace_to_json(const SubosWorkspace& sws) {
+    nlohmann::json j = nlohmann::json::object();
+
+    // Union of all target keys present in either map
+    std::set<std::string> keys;
+    for (auto& [k, _] : sws.active) keys.insert(k);
+    for (auto& [k, _] : sws.installed) keys.insert(k);
+
+    for (const auto& key : keys) {
+        std::string active;
+        if (auto it = sws.active.find(key); it != sws.active.end()) {
+            active = it->second;
+        }
+
+        std::vector<std::string> installed;
+        if (auto it = sws.installed.find(key); it != sws.installed.end()) {
+            installed = it->second;
+        }
+        if (!active.empty() &&
+            std::find(installed.begin(), installed.end(), active) == installed.end()) {
+            installed.push_back(active);
+        }
+        std::sort(installed.begin(), installed.end());
+
+        nlohmann::json entry = nlohmann::json::object();
+        if (!active.empty()) entry["active"] = active;
+        if (!installed.empty()) {
+            entry["installed"] = nlohmann::json::array();
+            for (auto& v : installed) entry["installed"].push_back(v);
+        }
+        j[key] = std::move(entry);
+    }
+
+    return j;
+}
+
+}
diff --git a/src/core/xvm/db.cppm b/src/core/xvm/db.cppm
index 19bb5e7a..59ef1946 100644
--- a/src/core/xvm/db.cppm
+++ b/src/core/xvm/db.cppm
@@ -9,27 +9,16 @@ import xlings.platform;
 export namespace xlings::xvm {
 
 // Parse "ns:ver" into (namespace, version). Plain "ver" → ("", "ver").
-std::pair<std::string, std::string> parse_ns_version(const std::string& s) {
-    auto pos = s.find(':');
-    if (pos == std::string::npos) return {"", s};
-    return {s.substr(0, pos), s.substr(pos + 1)};
-}
+std::pair<std::string, std::string> parse_ns_version(const std::string& s);
 
 // Build "ns:ver" from namespace and version. Empty namespace → plain "ver".
-std::string make_ns_version(const std::string& ns, const std::string& ver) {
-    if (ns.empty()) return ver;
-    return ns + ":" + ver;
-}
+std::string make_ns_version(const std::string& ns, const std::string& ver);
 
 // Strip namespace prefix, returning bare version.
-std::string strip_namespace(const std::string& s) {
-    return parse_ns_version(s).second;
-}
+std::string strip_namespace(const std::string& s);
 
 // Get namespace prefix (empty if none).
-std::string get_namespace(const std::string& s) {
-    return parse_ns_version(s).first;
-}
+std::string get_namespace(const std::string& s);
 
 // How a (target, version-key) pair is written for a human, and for a shell.
 //
@@ -45,12 +34,7 @@ std::string get_namespace(const std::string& s) {
 //   ("llvm", "20.1.7")        -> "llvm@20.1.7"
 //   ("gcc",  "")              -> "gcc"
 std::string display_coordinate(std::string_view target,
-                               std::string_view versionKey) {
-    if (versionKey.empty()) return std::string(target);
-    const auto [ns, version] = parse_ns_version(std::string(versionKey));
-    if (ns.empty()) return std::format("{}@{}", target, version);
-    return std::format("{}:{}@{}", ns, target, version);
-}
+                               std::string_view versionKey);
 
 // Add or update a version entry in the database.
 // If ns is non-empty, the version key becomes "ns:version".
@@ -62,35 +46,7 @@ void add_version(VersionDB& db,
                  const std::string& filename = "",
                  const std::string& alias = "",
                  const std::string& ns = "",
-                 const std::string& binding = "") {
-    auto& info = db[target];
-    if (info.type.empty()) info.type = type;
-    if (info.filename.empty() && !filename.empty()) info.filename = filename;
-
-    auto ver_key = make_ns_version(ns, version);
-    VData vdata;
-    vdata.path = path;
-    vdata.kind = type;
-    if (type != "group") {
-        vdata.sourceName = filename.empty() ? target : filename;
-        vdata.destinationName =
-            type == "program" ? target : vdata.sourceName;
-    }
-    if (!alias.empty()) vdata.alias.push_back(alias);
-    info.versions[ver_key] = std::move(vdata);
-
-    // Establish bidirectional binding relationship
-    if (!binding.empty()) {
-        auto at = binding.find('@');
-        if (at != std::string::npos) {
-            auto peer = binding.substr(0, at);
-            auto peer_ver = make_ns_version(ns, binding.substr(at + 1));
-            // Bidirectional: peer records target, target records peer
-            db[peer].bindings[target][peer_ver] = ver_key;
-            db[target].bindings[peer][ver_key] = peer_ver;
-        }
-    }
-}
+                 const std::string& binding = "");
 
 // Remove a version from the database.
 // Namespaced input must match exactly. Bare input resolves only when exactly
@@ -118,140 +74,12 @@ struct RemovalError {
 std::expected<std::string, RemovalError>
 resolve_exact_version_key(const VersionDB& db,
                           const std::string& target,
-                          const std::string& version) {
-    auto it = db.find(target);
-    if (it == db.end() || version.empty()) {
-        return std::unexpected(RemovalError{
-            .kind = RemovalErrorKind::VersionNotFound,
-            .target = target,
-            .version = version,
-            .message = "removal version is missing",
-        });
-    }
-
-    if (version.find(':') != std::string::npos) {
-        if (it->second.versions.contains(version)) return version;
-        return std::unexpected(RemovalError{
-            .kind = RemovalErrorKind::VersionNotFound,
-            .target = target,
-            .version = version,
-            .message = "exact removal version is not registered",
-        });
-    }
-
-    std::vector<std::string> matches;
-    for (const auto& [storedVersion, _] : it->second.versions) {
-        if (strip_namespace(storedVersion) == version) {
-            matches.push_back(storedVersion);
-        }
-    }
-    if (matches.size() == 1) return matches.front();
-    if (matches.empty()) {
-        return std::unexpected(RemovalError{
-            .kind = RemovalErrorKind::VersionNotFound,
-            .target = target,
-            .version = version,
-            .message = "removal version is not registered",
-        });
-    }
-    return std::unexpected(RemovalError{
-        .kind = RemovalErrorKind::AmbiguousVersion,
-        .target = target,
-        .version = version,
-        .message = std::format(
-            "bare removal version '{}' matches {} stored versions",
-            version, matches.size()),
-    });
-}
+                          const std::string& version);
 
 std::expected<std::string, RemovalError>
 remove_version(VersionDB& db,
                const std::string& target,
-               const std::string& version) {
-    auto exactVersionResult =
-        resolve_exact_version_key(db, target, version);
-    if (!exactVersionResult) {
-        return std::unexpected(std::move(exactVersionResult.error()));
-    }
-    const auto& exactVersion = *exactVersionResult;
-
-    auto it = db.find(target);
-    auto& vers = it->second.versions;
-
-    std::vector<std::pair<std::string, std::string>> edges;
-    for (const auto& [peerTarget, versions] : it->second.bindings) {
-        if (auto edgeIt = versions.find(exactVersion);
-            edgeIt != versions.end()) {
-            edges.emplace_back(peerTarget, edgeIt->second);
-        }
-    }
-
-    for (const auto& [peerTarget, peerVersion] : edges) {
-        auto peerIt = db.find(peerTarget);
-        const auto reciprocal =
-            peerIt != db.end()
-            && peerIt->second.versions.contains(peerVersion)
-            && peerIt->second.bindings.contains(target)
-            && peerIt->second.bindings.at(target).contains(peerVersion)
-            && peerIt->second.bindings.at(target).at(peerVersion)
-                == exactVersion;
-        if (!reciprocal) {
-            return std::unexpected(RemovalError{
-                .kind = RemovalErrorKind::AsymmetricEdge,
-                .target = target,
-                .version = exactVersion,
-                .peerTarget = peerTarget,
-                .peerVersion = peerVersion,
-                .message = "removal binding edge is not reciprocal",
-            });
-        }
-    }
-
-    for (const auto& [peerTarget, peerInfo] : db) {
-        auto incomingIt = peerInfo.bindings.find(target);
-        if (incomingIt == peerInfo.bindings.end()) continue;
-        for (const auto& [peerVersion, targetVersion] : incomingIt->second) {
-            if (targetVersion != exactVersion) continue;
-            const auto reciprocal =
-                peerInfo.versions.contains(peerVersion)
-                && it->second.bindings.contains(peerTarget)
-                && it->second.bindings.at(peerTarget).contains(exactVersion)
-                && it->second.bindings.at(peerTarget).at(exactVersion)
-                    == peerVersion;
-            if (!reciprocal) {
-                return std::unexpected(RemovalError{
-                    .kind = RemovalErrorKind::AsymmetricEdge,
-                    .target = target,
-                    .version = exactVersion,
-                    .peerTarget = peerTarget,
-                    .peerVersion = peerVersion,
-                    .message = "incoming removal binding edge is not reciprocal",
-                });
-            }
-        }
-    }
-
-    for (const auto& [peerTarget, peerVersion] : edges) {
-        auto bindingIt = it->second.bindings.find(peerTarget);
-        bindingIt->second.erase(exactVersion);
-        if (bindingIt->second.empty()) {
-            it->second.bindings.erase(bindingIt);
-        }
-
-        auto peerIt = db.find(peerTarget);
-        if (peerIt == db.end()) continue;
-        auto reverseIt = peerIt->second.bindings.find(target);
-        if (reverseIt == peerIt->second.bindings.end()) continue;
-        reverseIt->second.erase(peerVersion);
-        if (reverseIt->second.empty()) {
-            peerIt->second.bindings.erase(reverseIt);
-        }
-    }
-
-    vers.erase(exactVersion);
-    if (vers.empty() && it->second.bindings.empty()) db.erase(it);
-    return exactVersion;
-}
+               const std::string& version);
 
 // Pick the highest semver key from a version map (descending by dotted numeric components,
 // then by component count). Namespace prefix is stripped before comparison, but the
@@ -265,37 +93,9 @@ remove_version(VersionDB& db,
 // equal in both directions, so which one a sort leaves in front depends on the
 // input order. Callers that pick "the highest" would then return different
 // answers for the same set depending on how it happened to be built.
-bool version_key_greater(const std::string& lhs, const std::string& rhs) {
-    const auto split = [](const std::string& s) {
-        std::vector<std::string> parts;
-        std::istringstream iss(s);
-        std::string part;
-        while (std::getline(iss, part, '.')) parts.push_back(part);
-        return parts;
-    };
-    const auto pa = split(strip_namespace(lhs));
-    const auto pb = split(strip_namespace(rhs));
-    for (std::size_t i = 0; i < std::min(pa.size(), pb.size()); ++i) {
-        int na = 0, nb = 0;
-        std::from_chars(pa[i].data(), pa[i].data() + pa[i].size(), na);
-        std::from_chars(pb[i].data(), pb[i].data() + pb[i].size(), nb);
-        if (na != nb) return na > nb;
-    }
-    if (pa.size() != pb.size()) return pa.size() > pb.size();
-    return lhs < rhs;
-}
-
-std::string pick_highest_version(const std::map<std::string, VData>& versions) {
-    if (versions.empty()) return {};
-
-    std::vector<std::string> keys;
-    keys.reserve(versions.size());
-    for (auto& [k, _] : versions) keys.push_back(k);
+bool version_key_greater(const std::string& lhs, const std::string& rhs);
 
-    std::ranges::sort(keys, version_key_greater);
-
-    return keys.front();
-}
+std::string pick_highest_version(const std::map<std::string, VData>& versions);
 
 // Fuzzy version match: "15" -> "15.1.0", "ns:14.2" -> "ns:14.2.0"
 // Matching priority:
@@ -304,139 +104,31 @@ std::string pick_highest_version(const std::map<std::string, VData>& versions) {
 //   3. If no namespace: prefer bare (unqualified) versions, then fallback to any namespace
 std::string match_version(const VersionDB& db,
                           const std::string& target,
-                          const std::string& prefix) {
-    auto it = db.find(target);
-    if (it == db.end()) return {};
-
-    auto& versions = it->second.versions;
-
-    // Exact match first
-    if (versions.contains(prefix)) return prefix;
-
-    auto [input_ns, input_ver] = parse_ns_version(prefix);
-
-    auto split = [](const std::string& s) -> std::vector<std::string> {
-        std::vector<std::string> parts;
-        std::istringstream iss(s);
-        std::string part;
-        while (std::getline(iss, part, '.')) {
-            parts.push_back(part);
-        }
-        return parts;
-    };
-
-    auto sort_desc = [&](std::vector<std::string>& candidates) {
-        std::ranges::sort(candidates, [&](const std::string& a, const std::string& b) {
-            auto pa = split(strip_namespace(a));
-            auto pb = split(strip_namespace(b));
-            for (std::size_t i = 0; i < std::min(pa.size(), pb.size()); ++i) {
-                int na = 0, nb = 0;
-                std::from_chars(pa[i].data(), pa[i].data() + pa[i].size(), na);
-                std::from_chars(pb[i].data(), pb[i].data() + pb[i].size(), nb);
-                if (na != nb) return na > nb;
-            }
-            return pa.size() > pb.size();
-        });
-    };
-
-    auto input_parts = split(input_ver);
-
-    auto prefix_matches = [&](const std::string& bare_ver) -> bool {
-        auto ver_parts = split(bare_ver);
-        if (ver_parts.size() < input_parts.size()) return false;
-        for (std::size_t i = 0; i < input_parts.size(); ++i) {
-            if (input_parts[i] != ver_parts[i]) return false;
-        }
-        return true;
-    };
-
-    // If namespace specified, only match within that namespace
-    if (!input_ns.empty()) {
-        std::vector<std::string> candidates;
-        for (auto& [ver, _] : versions) {
-            auto [ver_ns, bare_ver] = parse_ns_version(ver);
-            if (ver_ns == input_ns && prefix_matches(bare_ver))
-                candidates.push_back(ver);
-        }
-        if (candidates.empty()) return {};
-        sort_desc(candidates);
-        return candidates[0];
-    }
-
-    // No namespace: prefer bare (unqualified) versions first
-    std::vector<std::string> bare_candidates;
-    std::vector<std::string> ns_candidates;
-    for (auto& [ver, _] : versions) {
-        auto [ver_ns, bare_ver] = parse_ns_version(ver);
-        if (prefix_matches(bare_ver)) {
-            if (ver_ns.empty())
-                bare_candidates.push_back(ver);
-            else
-                ns_candidates.push_back(ver);
-        }
-    }
-
-    if (!bare_candidates.empty()) {
-        sort_desc(bare_candidates);
-        return bare_candidates[0];
-    }
-    if (!ns_candidates.empty()) {
-        sort_desc(ns_candidates);
-        return ns_candidates[0];
-    }
-    return {};
-}
+                          const std::string& prefix);
 
 // Get the active version for a target from a workspace
 std::string get_active_version(const Workspace& workspace,
-                               const std::string& target) {
-    auto it = workspace.find(target);
-    return it != workspace.end() ? it->second : std::string{};
-}
+                               const std::string& target);
 
 // Check if a target has any versions registered
-bool has_target(const VersionDB& db, const std::string& target) {
-    return db.contains(target);
-}
+bool has_target(const VersionDB& db, const std::string& target);
 
 // Check if a specific version exists
 bool has_version(const VersionDB& db,
                  const std::string& target,
-                 const std::string& version) {
-    auto it = db.find(target);
-    if (it == db.end()) return false;
-    return it->second.versions.contains(version);
-}
+                 const std::string& version);
 
 // Get all version strings for a target
 std::vector<std::string> get_all_versions(const VersionDB& db,
-                                          const std::string& target) {
-    std::vector<std::string> result;
-    auto it = db.find(target);
-    if (it == db.end()) return result;
-    for (auto& [ver, _] : it->second.versions) {
-        result.push_back(ver);
-    }
-    return result;
-}
+                                          const std::string& target);
 
 // Get VData for a specific version
 const VData* get_vdata(const VersionDB& db,
                        const std::string& target,
-                       const std::string& version) {
-    auto it = db.find(target);
-    if (it == db.end()) return nullptr;
-    auto vit = it->second.versions.find(version);
-    if (vit == it->second.versions.end()) return nullptr;
-    return &vit->second;
-}
+                       const std::string& version);
 
 // Get VInfo for a target
-const VInfo* get_vinfo(const VersionDB& db, const std::string& target) {
-    auto it = db.find(target);
-    if (it == db.end()) return nullptr;
-    return &it->second;
-}
+const VInfo* get_vinfo(const VersionDB& db, const std::string& target);
 
 // Both accessors above hand back a pointer INTO the map, so passing a
 // temporary map is a use-after-free every time -- the map dies at the end of
@@ -468,15 +160,7 @@ const VInfo* get_vinfo(const VersionDB&&, const std::string&) = delete;
 std::string get_binding(const VersionDB& db,
                         const std::string& target,
                         const std::string& binding_name,
-                        const std::string& version) {
-    auto it = db.find(target);
-    if (it == db.end()) return {};
-    auto bit = it->second.bindings.find(binding_name);
-    if (bit == it->second.bindings.end()) return {};
-    auto vit = bit->second.find(version);
-    if (vit == bit->second.end()) return {};
-    return vit->second;
-}
+                        const std::string& version);
 
 // ── subos-relative alias/env normalization ───────────────────────────
 //
@@ -496,104 +180,7 @@ std::string get_binding(const VersionDB& db,
 // through byte-identical.
 std::string normalize_subos_paths(const std::string& text,
                                   const std::string& xlings_home,
-                                  const std::string& active_subos_dir) {
-    if (active_subos_dir.empty() || text.empty()) return text;
-
-    static constexpr std::string_view kPosix = "/subos/";
-    static constexpr std::string_view kWin   = "\\subos\\";
-
-    auto is_sep = [](char c) { return c == '/' || c == '\\'; };
-    // Where a path token can start: whitespace, plus the punctuation that
-    // glues a path onto a flag (`--sysroot=`, `PATH=a:b`, quotes).
-    auto is_boundary = [](char c) {
-        return c == ' ' || c == '\t' || c == '=' || c == ':' || c == ';'
-            || c == ',' || c == '"' || c == '\'';
-    };
-    auto is_alpha = [](char c) {
-        return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
-    };
-    auto path_equal = [](std::string_view a, std::string_view b) {
-#if defined(_WIN32)
-        // Windows compares paths case-insensitively and treats / and \ alike.
-        if (a.size() != b.size()) return false;
-        auto fold = [](char c) -> char {
-            if (c == '\\') return '/';
-            if (c >= 'A' && c <= 'Z') return static_cast<char>(c - 'A' + 'a');
-            return c;
-        };
-        for (std::size_t i = 0; i < a.size(); ++i) {
-            if (fold(a[i]) != fold(b[i])) return false;
-        }
-        return true;
-#else
-        return a == b;
-#endif
-    };
-
-    std::string out;
-    out.reserve(text.size());
-    std::size_t cursor = 0;
-
-    while (cursor < text.size()) {
-        auto p1 = text.find(kPosix, cursor);
-        auto p2 = text.find(kWin, cursor);
-        auto hit = std::min(p1, p2);   // npos is max, so min() picks the real one
-        if (hit == std::string::npos) break;
-
-        // Widen left to the start of the path token.
-        std::size_t start = hit;
-        while (start > cursor && !is_boundary(text[start - 1])) --start;
-        // ':' is a boundary (PATH=a:b), which would cut the drive letter off
-        // `--sysroot=C:\Users\...`: the prefix becomes `\Users\u\.xlings` and
-        // the replacement splices a second drive spec onto the surviving `C:`.
-        // Step back over a drive letter that is itself token-initial.
-        if (start >= cursor + 2 && text[start - 1] == ':'
-            && is_alpha(text[start - 2])
-            && (start < cursor + 3 || is_boundary(text[start - 3]))) {
-            start -= 2;
-        }
-        // A flag can sit flush against the path with no boundary between them
-        // (`-B/h/.xlings/subos/a`), and the walk above happily swallows it.
-        // Skip forward to where the path actually begins -- a separator, or a
-        // drive letter -- so the replacement never eats the flag.
-        const bool drive =
-            start + 1 < hit && is_alpha(text[start]) && text[start + 1] == ':';
-        if (!drive) {
-            while (start < hit && !is_sep(text[start])) {
-                if (start + 1 < hit && is_alpha(text[start])
-                    && text[start + 1] == ':') {
-                    break;   // `-BC:\...`
-                }
-                ++start;
-            }
-        }
-        std::string_view prefix(text.data() + start, hit - start);
-
-        // Right: the subos NAME segment only. Everything after it (`/usr/
-        // include`, …) is the caller's business and is preserved.
-        std::size_t nameStart = hit + kPosix.size();
-        std::size_t nameEnd = nameStart;
-        while (nameEnd < text.size()
-               && !is_sep(text[nameEnd]) && !is_boundary(text[nameEnd])) {
-            ++nameEnd;
-        }
-
-        const bool ours =
-            path_equal(prefix, xlings_home)
-            || (prefix.size() >= 7
-                && path_equal(prefix.substr(prefix.size() - 7), ".xlings"));
-
-        if (!ours || nameEnd == nameStart) {
-            out.append(text, cursor, nameEnd - cursor);   // passthrough
-        } else {
-            out.append(text, cursor, start - cursor);
-            out.append(active_subos_dir);
-        }
-        cursor = nameEnd;
-    }
-    out.append(text, cursor, std::string::npos);
-    return out;
-}
+                                  const std::string& active_subos_dir);
 
 // The marker a recipe writes when it needs the ACTIVE subos, and its
 // expansion at execution time.
@@ -634,10 +221,7 @@ inline constexpr std::string_view kSubosPlaceholder =
 // literally the same traversal, so the two can never disagree about which
 // paths are ours.
 std::string pin_subos_paths(const std::string& text,
-                            const std::string& xlings_home) {
-    return normalize_subos_paths(text, xlings_home,
-                                 std::string(kSubosPlaceholder));
-}
+                            const std::string& xlings_home);
 
 // A `${XLINGS_*}` reference in a command this client is about to hand to a
 // shell, which that shell would expand to NOTHING. Returns the name
@@ -674,437 +258,27 @@ std::string pin_subos_paths(const std::string& text,
 //
 // `${XLINGS_*}` only, never `${...}`: a recipe may reference any other shell
 // variable and mean it, and that is not xlings's business to police.
-std::optional<std::string> vanishing_xlings_reference(std::string_view text) {
-    constexpr std::string_view kPrefix = "${XLINGS_";
-    std::size_t pos = 0;
-    while ((pos = text.find(kPrefix, pos)) != std::string_view::npos) {
-        auto close = text.find('}', pos + kPrefix.size());
-        if (close == std::string_view::npos) break;  // unterminated; not ours to judge
-        auto name = std::string(
-            text.substr(pos + 2, close - (pos + 2)));   // strip "${" and "}"
-        const char* value = std::getenv(name.c_str());
-        if (value == nullptr || *value == '\0') return name;
-        pos = close + 1;
-    }
-    return std::nullopt;
-}
+std::optional<std::string> vanishing_xlings_reference(std::string_view text);
 
 std::string expand_subos_placeholder(const std::string& text,
-                                     const std::string& subos_dir) {
-    if (subos_dir.empty() || text.empty()) return text;
-    std::string result = text;
-    std::size_t pos = 0;
-    while ((pos = result.find(kSubosPlaceholder, pos)) != std::string::npos) {
-        result.replace(pos, kSubosPlaceholder.size(), subos_dir);
-        pos += subos_dir.size();
-    }
-    return result;
-}
+                                     const std::string& subos_dir);
 
 // Expand ${XLINGS_HOME} in a path string
-std::string expand_path(const std::string& path, const std::string& xlings_home) {
-    std::string result = path;
-    const std::string placeholder = "${XLINGS_HOME}";
-    std::size_t pos = 0;
-    while ((pos = result.find(placeholder, pos)) != std::string::npos) {
-        result.replace(pos, placeholder.size(), xlings_home);
-        pos += xlings_home.size();
-    }
-    return result;
-}
+std::string expand_path(const std::string& path, const std::string& xlings_home);
 
 // --- JSON serialization ---
 
-nlohmann::json vdata_to_json(const VData& vdata) {
-    nlohmann::json j;
-    j["path"] = vdata.path;
-    if (!vdata.kind.empty()) j["kind"] = vdata.kind;
-    if (!vdata.sourceName.empty()) j["sourceName"] = vdata.sourceName;
-    if (!vdata.destinationName.empty())
-        j["destinationName"] = vdata.destinationName;
-    if (!vdata.fileSrc.empty()) j["fileSrc"] = vdata.fileSrc;
-    if (!vdata.fileDst.empty()) j["fileDst"] = vdata.fileDst;
-    if (!vdata.includedir.empty()) j["includedir"] = vdata.includedir;
-    if (!vdata.libdir.empty()) j["libdir"] = vdata.libdir;
-    if (!vdata.alias.empty()) {
-        j["alias"] = vdata.alias;
-    }
-    if (!vdata.envs.empty()) {
-        nlohmann::json envs_j = nlohmann::json::object();
-        for (auto it = vdata.envs.begin(); it != vdata.envs.end(); ++it) {
-            envs_j[it->first] = it->second;
-        }
-        j["envs"] = envs_j;
-    }
-    if (vdata.bindingGroup) {
-        j["bindingGroup"] = {
-            {"provider", vdata.bindingGroup->provider},
-            {"version", vdata.bindingGroup->providerVersion},
-            {"group", vdata.bindingGroup->group},
-            {"rootTarget", vdata.bindingGroup->rootTarget},
-            {"rootVersion", vdata.bindingGroup->rootVersion},
-        };
-    }
-    if (vdata.bindingMembersDeclared || !vdata.bindingMembers.empty()) {
-        nlohmann::json members = nlohmann::json::object();
-        for (const auto& [target, version] : vdata.bindingMembers) {
-            members[target] = version;
-        }
-        j["bindingMembers"] = std::move(members);
-    }
-    if (vdata.bindingHeadersDeclared || !vdata.bindingHeaders.empty()) {
-        nlohmann::json headers = nlohmann::json::array();
-        for (const auto& header : vdata.bindingHeaders) {
-            headers.push_back({
-                {"sourceDir", header.sourceDir},
-                {"destinationPrefix", header.destinationPrefix},
-            });
-        }
-        j["bindingHeaders"] = std::move(headers);
-    }
-    if (!vdata.bindingIntegrityIssues.empty()) {
-        nlohmann::json issues = nlohmann::json::array();
-        for (const auto& issue : vdata.bindingIntegrityIssues) {
-            issues.push_back({
-                {"code", issue.code},
-                {"path", issue.path},
-            });
-        }
-        j["bindingIntegrityIssues"] = std::move(issues);
-    }
-    // Preserved originals win over the reconstructed view.
-    //
-    // For a field we could not read, the parsed model holds at best a subset
-    // -- the members that happened to be well-formed, a group with the
-    // unreadable keys blanked. Writing that back is the silent rewrite this
-    // whole mechanism exists to stop, so the original text is restored last
-    // and overwrites whatever the blocks above produced for that key.
-    for (const auto& [field, text] : vdata.bindingUnreadable) {
-        try {
-            j[field] = nlohmann::json::parse(text);
-        } catch (const std::exception&) {
-            // Unreachable in practice: the text came from dump(). If it ever
-            // is, keeping the reconstructed value beats dropping the field.
-        }
-    }
-    return j;
-}
-
-VData vdata_from_json(const nlohmann::json& j) {
-    VData vdata;
-    const auto recordIssue =
-        [&vdata](std::string code, std::string path) {
-            const auto duplicate = std::ranges::any_of(
-                vdata.bindingIntegrityIssues,
-                [&](const BindingIntegrityIssue& issue) {
-                    return issue.code == code && issue.path == path;
-                });
-            if (duplicate) return;
-            vdata.bindingIntegrityIssues.push_back({
-                .code = std::move(code),
-                .path = std::move(path),
-            });
-        };
-    const auto pointerToken = [](std::string_view token) {
-        std::string escaped;
-        escaped.reserve(token.size());
-        for (char ch : token) {
-            if (ch == '~') {
-                escaped += "~0";
-            } else if (ch == '/') {
-                escaped += "~1";
-            } else {
-                escaped += ch;
-            }
-        }
-        return escaped;
-    };
-
-    if (j.contains("path") && j["path"].is_string())
-        vdata.path = j["path"].get<std::string>();
-    if (j.contains("kind") && j["kind"].is_string())
-        vdata.kind = j["kind"].get<std::string>();
-    if (j.contains("sourceName") && j["sourceName"].is_string())
-        vdata.sourceName = j["sourceName"].get<std::string>();
-    if (j.contains("destinationName") && j["destinationName"].is_string())
-        vdata.destinationName = j["destinationName"].get<std::string>();
-    if (j.contains("fileSrc") && j["fileSrc"].is_string())
-        vdata.fileSrc = j["fileSrc"].get<std::string>();
-    if (j.contains("fileDst") && j["fileDst"].is_string())
-        vdata.fileDst = j["fileDst"].get<std::string>();
-    if (j.contains("includedir") && j["includedir"].is_string())
-        vdata.includedir = j["includedir"].get<std::string>();
-    if (j.contains("libdir") && j["libdir"].is_string())
-        vdata.libdir = j["libdir"].get<std::string>();
-    if (j.contains("alias") && j["alias"].is_array()) {
-        for (auto& a : j["alias"]) {
-            if (a.is_string()) vdata.alias.push_back(a.get<std::string>());
-        }
-    }
-    if (j.contains("envs") && j["envs"].is_object()) {
-        auto& envs = j["envs"];
-        for (auto it = envs.begin(); it != envs.end(); ++it) {
-            if (it.value().is_string())
-                vdata.envs[it.key()] = it.value().get<std::string>();
-        }
-    }
-    if (j.contains("bindingIntegrityIssues")) {
-        if (!j["bindingIntegrityIssues"].is_array()) {
-            recordIssue(
-                "binding-integrity-issues-not-array",
-                "/bindingIntegrityIssues");
-        } else {
-            std::size_t index = 0;
-            for (const auto& issueJson : j["bindingIntegrityIssues"]) {
-                const auto issuePath =
-                    "/bindingIntegrityIssues/" + std::to_string(index++);
-                if (!issueJson.is_object()) {
-                    recordIssue(
-                        "binding-integrity-issue-not-object",
-                        issuePath);
-                    continue;
-                }
-
-                const auto validCode =
-                    issueJson.contains("code")
-                    && issueJson["code"].is_string()
-                    && !issueJson["code"].get_ref<
-                        const std::string&>().empty();
-                const auto validPath =
-                    issueJson.contains("path")
-                    && issueJson["path"].is_string()
-                    && !issueJson["path"].get_ref<
-                        const std::string&>().empty();
-                if (!validCode) {
-                    recordIssue(
-                        "binding-integrity-issue-field-invalid",
-                        issuePath + "/code");
-                }
-                if (!validPath) {
-                    recordIssue(
-                        "binding-integrity-issue-field-invalid",
-                        issuePath + "/path");
-                }
-                if (validCode && validPath) {
-                    recordIssue(
-                        issueJson["code"].get<std::string>(),
-                        issueJson["path"].get<std::string>());
-                }
-            }
-        }
-    }
-    if (j.contains("bindingGroup")) {
-        if (!j["bindingGroup"].is_object()) {
-            recordIssue(
-                "binding-group-not-object", "/bindingGroup");
-        } else {
-            const auto& group = j["bindingGroup"];
-            BindingGroupRef ref;
-            const auto parseGroupField =
-                [&](std::string_view name, std::string& destination) {
-                    const auto key = std::string(name);
-                    if (group.contains(key)
-                        && group[key].is_string()
-                        && !group[key].get_ref<
-                            const std::string&>().empty()) {
-                        destination = group[key].get<std::string>();
-                    } else {
-                        recordIssue(
-                            "binding-group-field-invalid",
-                            "/bindingGroup/" + key);
-                    }
-                };
-            parseGroupField("provider", ref.provider);
-            parseGroupField("version", ref.providerVersion);
-            parseGroupField("group", ref.group);
-            parseGroupField("rootTarget", ref.rootTarget);
-            parseGroupField("rootVersion", ref.rootVersion);
-            vdata.bindingGroup = std::move(ref);
-        }
-    }
-    if (j.contains("bindingMembers")) {
-        vdata.bindingMembersDeclared = true;
-        if (!j["bindingMembers"].is_object()) {
-            recordIssue(
-                "binding-members-not-object", "/bindingMembers");
-        } else {
-            const auto& members = j["bindingMembers"];
-            for (auto it = members.begin(); it != members.end(); ++it) {
-                const auto validTarget = !it.key().empty();
-                if (!validTarget) {
-                    recordIssue(
-                        "binding-member-target-empty",
-                        "/bindingMembers/");
-                }
-                if (!it.value().is_string()) {
-                    recordIssue(
-                        "binding-member-version-not-string",
-                        "/bindingMembers/" + pointerToken(it.key()));
-                } else if (it.value().get_ref<
-                               const std::string&>().empty()) {
-                    recordIssue(
-                        "binding-member-version-empty",
-                        "/bindingMembers/" + pointerToken(it.key()));
-                } else if (validTarget) {
-                    vdata.bindingMembers[it.key()] =
-                        it.value().get<std::string>();
-                }
-            }
-        }
-    }
-    if (j.contains("bindingHeaders")) {
-        vdata.bindingHeadersDeclared = true;
-        if (!j["bindingHeaders"].is_array()) {
-            recordIssue(
-                "binding-headers-not-array", "/bindingHeaders");
-        } else {
-            std::size_t index = 0;
-            for (const auto& headerJson : j["bindingHeaders"]) {
-                const auto headerPath =
-                    "/bindingHeaders/" + std::to_string(index++);
-                if (!headerJson.is_object()) {
-                    recordIssue("binding-header-not-object", headerPath);
-                    continue;
-                }
-                if (!headerJson.contains("sourceDir")
-                    || !headerJson["sourceDir"].is_string()) {
-                    recordIssue(
-                        "binding-header-source-dir-not-string",
-                        headerPath + "/sourceDir");
-                    continue;
-                }
-                if (headerJson["sourceDir"].get_ref<
-                        const std::string&>().empty()) {
-                    recordIssue(
-                        "binding-header-source-dir-empty",
-                        headerPath + "/sourceDir");
-                    continue;
-                }
-                if (headerJson.contains("destinationPrefix")
-                    && !headerJson["destinationPrefix"].is_string()) {
-                    recordIssue(
-                        "binding-header-destination-prefix-not-string",
-                        headerPath + "/destinationPrefix");
-                    continue;
-                }
-
-                HeaderAsset header{
-                    .sourceDir =
-                        headerJson["sourceDir"].get<std::string>(),
-                };
-                if (headerJson.contains("destinationPrefix")) {
-                    header.destinationPrefix =
-                        headerJson["destinationPrefix"].get<std::string>();
-                }
-                vdata.bindingHeaders.push_back(std::move(header));
-            }
-        }
-    }
-    if ((j.contains("bindingMembers") || j.contains("bindingHeaders"))
-        && !vdata.bindingGroup) {
-        recordIssue("binding-group-missing", "/bindingGroup");
-    }
-
-    // Keep the original text of every binding field we could not fully read.
-    //
-    // Without this the next save rewrites the entry from the parsed model and
-    // whatever did not fit is gone -- the marker survives, the data does not.
-    // That is why `--reset-metadata` could not be offered before: there was
-    // nothing left to reset from, and the destruction had already happened
-    // silently on the first save after the corruption.
-    //
-    // Whole-field granularity: a field with one bad member is re-emitted
-    // entire, because a partial re-emission is exactly the lossy rewrite this
-    // is here to prevent.
-    for (const auto& issue : vdata.bindingIntegrityIssues) {
-        static constexpr std::string_view fields[] = {
-            "bindingGroup", "bindingMembers",
-            "bindingHeaders", "bindingIntegrityIssues",
-        };
-        for (const auto field : fields) {
-            const auto prefix = "/" + std::string(field);
-            if (!issue.path.starts_with(prefix)) continue;
-            // `binding-group-missing` names a field that is not there; there
-            // is nothing to preserve and nothing was lost.
-            const auto key = std::string(field);
-            if (!j.contains(key)) break;
-            vdata.bindingUnreadable.emplace(key, j[key].dump());
-            break;
-        }
-    }
-    return vdata;
-}
-
-nlohmann::json vinfo_to_json(const VInfo& info) {
-    nlohmann::json j;
-    if (!info.type.empty()) j["type"] = info.type;
-    if (!info.filename.empty()) j["filename"] = info.filename;
+nlohmann::json vdata_to_json(const VData& vdata);
 
-    nlohmann::json vers = nlohmann::json::object();
-    for (auto it = info.versions.begin(); it != info.versions.end(); ++it) {
-        vers[it->first] = vdata_to_json(it->second);
-    }
-    j["versions"] = vers;
+VData vdata_from_json(const nlohmann::json& j);
 
-    if (!info.bindings.empty()) {
-        nlohmann::json binds = nlohmann::json::object();
-        for (auto it = info.bindings.begin(); it != info.bindings.end(); ++it) {
-            nlohmann::json vermap_j = nlohmann::json::object();
-            for (auto vit = it->second.begin(); vit != it->second.end(); ++vit) {
-                vermap_j[vit->first] = vit->second;
-            }
-            binds[it->first] = vermap_j;
-        }
-        j["bindings"] = binds;
-    }
+nlohmann::json vinfo_to_json(const VInfo& info);
 
-    return j;
-}
+VInfo vinfo_from_json(const nlohmann::json& j);
 
-VInfo vinfo_from_json(const nlohmann::json& j) {
-    VInfo info;
-    if (j.contains("type") && j["type"].is_string())
-        info.type = j["type"].get<std::string>();
-    if (j.contains("filename") && j["filename"].is_string())
-        info.filename = j["filename"].get<std::string>();
-    if (j.contains("versions") && j["versions"].is_object()) {
-        auto& vers = j["versions"];
-        for (auto it = vers.begin(); it != vers.end(); ++it) {
-            info.versions[it.key()] = vdata_from_json(it.value());
-        }
-    }
-    if (j.contains("bindings") && j["bindings"].is_object()) {
-        auto& binds = j["bindings"];
-        for (auto it = binds.begin(); it != binds.end(); ++it) {
-            if (it.value().is_object()) {
-                std::map<std::string, std::string> vermap;
-                for (auto vit = it.value().begin(); vit != it.value().end(); ++vit) {
-                    if (vit.value().is_string())
-                        vermap[vit.key()] = vit.value().get<std::string>();
-                }
-                info.bindings[it.key()] = std::move(vermap);
-            }
-        }
-    }
-    return info;
-}
-
-nlohmann::json versions_to_json(const VersionDB& db) {
-    nlohmann::json j = nlohmann::json::object();
-    for (auto it = db.begin(); it != db.end(); ++it) {
-        j[it->first] = vinfo_to_json(it->second);
-    }
-    return j;
-}
+nlohmann::json versions_to_json(const VersionDB& db);
 
-VersionDB versions_from_json(const nlohmann::json& j) {
-    VersionDB db;
-    if (!j.is_object()) return db;
-    for (auto it = j.begin(); it != j.end(); ++it) {
-        db[it.key()] = vinfo_from_json(it.value());
-    }
-    return db;
-}
+VersionDB versions_from_json(const nlohmann::json& j);
 
 // Resolve a project-style workspace value (string | platform-conditional
 // object) to a single version string. Lifted out of workspace_from_json
@@ -1133,24 +307,9 @@ resolve_platform_workspace_value_(const nlohmann::json& value) {
     return std::nullopt;
 }
 
-Workspace workspace_from_json(const nlohmann::json& j) {
-    Workspace ws;
-    if (!j.is_object()) return ws;
-    for (auto it = j.begin(); it != j.end(); ++it) {
-        if (auto resolved = resolve_platform_workspace_value_(it.value())) {
-            ws[it.key()] = *resolved;
-        }
-    }
-    return ws;
-}
+Workspace workspace_from_json(const nlohmann::json& j);
 
-nlohmann::json workspace_to_json(const Workspace& ws) {
-    nlohmann::json j = nlohmann::json::object();
-    for (auto it = ws.begin(); it != ws.end(); ++it) {
-        j[it->first] = it->second;
-    }
-    return j;
-}
+nlohmann::json workspace_to_json(const Workspace& ws);
 
 // Subos-flavored workspace parser. Accepts three value shapes per target:
 //
@@ -1169,79 +328,7 @@ nlohmann::json workspace_to_json(const Workspace& ws) {
 // "Plan 1" disambiguation strategy from the C2 design discussion — `active`
 // and `installed` cannot meaningfully be platform names, so the two object
 // shapes can never collide.
-SubosWorkspace subos_workspace_from_json(const nlohmann::json& j) {
-    SubosWorkspace sws;
-    if (!j.is_object()) return sws;
-
-    // An active version is an installed version -- on read as well as on
-    // write.
-    //
-    // subos_workspace_to_json has always normalised `installed[]` to contain
-    // `active` ("write-time invariant: an active version is implicitly
-    // installed"), but the parser did not apply the same rule, so a record
-    // saying "this subos is on 1.0.0" parsed as "this subos has installed
-    // nothing". That was invisible while `use` opted a subos in silently;
-    // once `use` requires the version to be installed here (2026.7.31.3), it
-    // would refuse the very version the file says is active -- on every home
-    // written by a pre-0.4.19 client, and on every hand-written
-    // platform-conditional entry. Applying the invariant on both sides makes
-    // the round trip a fixed point.
-    //
-    // A lambda rather than a namespace-scope helper on purpose: GCC 16 ICEs
-    // when the first instantiation of a std container over a module-attached
-    // type is required from namespace scope, and the crash leaves a truncated
-    // BMI that reports itself as "Bad file data" in unrelated translation
-    // units.
-    auto set_active = [&sws](const std::string& key, std::string active) {
-        if (active.empty()) return;
-        auto& installed = sws.installed[key];
-        if (std::find(installed.begin(), installed.end(), active)
-                == installed.end()) {
-            installed.push_back(active);
-        }
-        sws.active[key] = std::move(active);
-    };
-
-    for (auto it = j.begin(); it != j.end(); ++it) {
-        const auto& key = it.key();
-        const auto& value = it.value();
-
-        if (value.is_string()) {
-            // Legacy form: bare version string.
-            set_active(key, value.get<std::string>());
-            continue;
-        }
-
-        if (!value.is_object()) continue;
-
-        // Form (2): C2 object form
-        bool hasActive = value.contains("active");
-        bool hasInstalled = value.contains("installed");
-        if (hasActive || hasInstalled) {
-            if (hasInstalled && value.at("installed").is_array()) {
-                std::vector<std::string> installed;
-                for (auto& v : value.at("installed")) {
-                    if (v.is_string()) installed.push_back(v.get<std::string>());
-                }
-                if (!installed.empty()) sws.installed[key] = std::move(installed);
-            }
-            if (hasActive && value.at("active").is_string()) {
-                set_active(key, value.at("active").get<std::string>());
-            }
-            continue;
-        }
-
-        // Form (3): platform-conditional fallback. Reuses the project-style
-        // resolver — subos files don't normally carry this shape, but
-        // honoring it here means a hand-edited subos file with platform
-        // branches behaves the same way the project manifest would.
-        if (auto resolved = resolve_platform_workspace_value_(value)) {
-            set_active(key, *resolved);
-        }
-    }
-
-    return sws;
-}
+SubosWorkspace subos_workspace_from_json(const nlohmann::json& j);
 
 // Subos workspace serializer. Always emits the C2 object form with
 // `active` and `installed` keys. The `installed` set is normalized to
@@ -1251,40 +338,6 @@ SubosWorkspace subos_workspace_from_json(const nlohmann::json& j) {
 // and never had an install/remove since — visually compact.
 //
 // Stable sort on installed[] so json diffs remain reviewable across runs.
-nlohmann::json subos_workspace_to_json(const SubosWorkspace& sws) {
-    nlohmann::json j = nlohmann::json::object();
-
-    // Union of all target keys present in either map
-    std::set<std::string> keys;
-    for (auto& [k, _] : sws.active) keys.insert(k);
-    for (auto& [k, _] : sws.installed) keys.insert(k);
-
-    for (const auto& key : keys) {
-        std::string active;
-        if (auto it = sws.active.find(key); it != sws.active.end()) {
-            active = it->second;
-        }
-
-        std::vector<std::string> installed;
-        if (auto it = sws.installed.find(key); it != sws.installed.end()) {
-            installed = it->second;
-        }
-        if (!active.empty() &&
-            std::find(installed.begin(), installed.end(), active) == installed.end()) {
-            installed.push_back(active);
-        }
-        std::sort(installed.begin(), installed.end());
-
-        nlohmann::json entry = nlohmann::json::object();
-        if (!active.empty()) entry["active"] = active;
-        if (!installed.empty()) {
-            entry["installed"] = nlohmann::json::array();
-            for (auto& v : installed) entry["installed"].push_back(v);
-        }
-        j[key] = std::move(entry);
-    }
-
-    return j;
-}
+nlohmann::json subos_workspace_to_json(const SubosWorkspace& sws);
 
 } // namespace xlings::xvm
diff --git a/src/core/xvm/errors.cpp b/src/core/xvm/errors.cpp
new file mode 100644
index 00000000..a64e7b74
--- /dev/null
+++ b/src/core/xvm/errors.cpp
@@ -0,0 +1,260 @@
+module xlings.core.xvm.errors;
+
+import std;
+import xlings.core.xvm.bindings;
+import xlings.core.xvm.db;
+import xlings.core.xvm.registration;
+
+namespace xlings::xvm {
+
+CodeAndHint describe_kind(RegistrationErrorKind kind) {
+    switch (kind) {
+    case RegistrationErrorKind::InvalidBatchIdentity:
+        return {"xvm-batch-identity-invalid",
+                "the package did not declare who owns these registrations; "
+                "this is a recipe defect -- please report it upstream"};
+    case RegistrationErrorKind::InvalidNodeIdentity:
+        return {"xvm-node-identity-invalid",
+                "a recipe registered something with no name or no version; "
+                "check the xvm.add calls in the package recipe"};
+    case RegistrationErrorKind::InvalidNodePayload:
+        return {"xvm-node-payload-invalid",
+                "a recipe registered an entry with an unusable kind or "
+                "filename; check the type/filename of that xvm.add call"};
+    case RegistrationErrorKind::InvalidBindingIdentity:
+        return {"xvm-binding-identity-invalid",
+                "a recipe declared a binding with no target; check the "
+                "binding argument of that xvm.add call"};
+    case RegistrationErrorKind::DuplicateNode:
+        return {"xvm-duplicate-registration",
+                "the recipe registers the same name and version twice; "
+                "remove the duplicate xvm.add"};
+    case RegistrationErrorKind::RootNotInBatch:
+        return {"xvm-binding-root-missing",
+                "a binding points at something the recipe never registers; "
+                "register the binding target in the same recipe"};
+    case RegistrationErrorKind::SelfBinding:
+        return {"xvm-self-binding",
+                "an entry binds to itself; drop the binding argument"};
+    case RegistrationErrorKind::GroupConflict:
+        return {"xvm-group-conflict",
+                "the recipe puts one release under two different roots; "
+                "give the members a single common binding target"};
+    case RegistrationErrorKind::TargetVersionConflict:
+        return {"xvm-group-version-conflict",
+                "one release selects two versions of the same program; "
+                "a toolchain release must pin exactly one version per name"};
+    case RegistrationErrorKind::OwnershipConflict:
+        return {"xvm-ownership-conflict",
+                "another package already owns this exact name and version; "
+                "uninstall that package first, or install this one at a "
+                "different version"};
+    // The three hints below all say "uninstall it first", and all three used
+    // to say it without naming a version. `xlings remove <name>` resolves
+    // through the ACTIVE binding, which in every situation these errors are
+    // raised in is a DIFFERENT version from the one that needs clearing -- so
+    // the official way out reported "not installed" and left the user with the
+    // tool's own `--force` warning as the only remaining move (#541 ②).
+    //
+    // A remedy that names no version is a remedy for whichever package happens
+    // to be active. Say `@<version>`.
+    case RegistrationErrorKind::LegacyPayloadMismatch:
+        return {"xvm-legacy-payload-mismatch",
+                "this name and version is already installed with different "
+                "contents; uninstall it with its version "
+                "(`xlings remove <name>@<version>`) before reinstalling"};
+    case RegistrationErrorKind::IncompleteLegacyComponent:
+        return {"xvm-legacy-component-incomplete",
+                "the install would rewrite part of an existing bound group; "
+                "uninstall the whole package first, naming its version "
+                "(`xlings remove <name>@<version>`)"};
+    case RegistrationErrorKind::IncompleteOwnedGroup:
+        return {"xvm-owned-group-incomplete",
+                "reinstalling this release would drop a member it already "
+                "owns; uninstall it with its version "
+                "(`xlings remove <name>@<version>`), then install again"};
+    case RegistrationErrorKind::InvalidHeader:
+        return {"xvm-header-invalid",
+                "a recipe declared headers with no source directory; check "
+                "the xvm.headers call"};
+    case RegistrationErrorKind::HeaderGroupNotFound:
+        return {"xvm-header-group-unknown",
+                "the headers name a group the recipe does not create; fix "
+                "the group name on the xvm.headers call"};
+    case RegistrationErrorKind::HeaderAmbiguous:
+        return {"xvm-header-owner-ambiguous",
+                "the recipe registers several groups and nothing says which "
+                "one ships these headers; name the group on xvm.headers"};
+    case RegistrationErrorKind::BindingValidationFailed:
+        return {"xvm-binding-validation-failed",
+                "the resulting version database would not be self-consistent; "
+                "run `xlings self doctor` to see the offending entries"};
+    }
+    return {kUnclassifiedCode, kUnclassifiedHint};
+}
+
+CodeAndHint describe_kind(RemovalErrorKind kind) {
+    switch (kind) {
+    case RemovalErrorKind::VersionNotFound:
+        return {"xvm-remove-version-unknown",
+                "that version is not registered; run `xlings list` to see "
+                "what is installed"};
+    case RemovalErrorKind::AmbiguousVersion:
+        return {"xvm-remove-version-ambiguous",
+                "several installed versions match; pass the fully qualified "
+                "version, including its namespace prefix"};
+    case RemovalErrorKind::AsymmetricEdge:
+        return {"xvm-remove-edge-asymmetric",
+                "the stored binding is one-sided, so removal cannot tell what "
+                "else to detach; run `xlings self doctor`"};
+    case RemovalErrorKind::SelectionInvalid:
+        return {"xvm-remove-selection-invalid",
+                "the release to remove does not resolve to a coherent set; "
+                "run `xlings self doctor`"};
+    case RemovalErrorKind::ProviderRequired:
+        return {"xvm-remove-provider-required",
+                "removing every version of a name requires knowing which "
+                "package owns them; remove the package instead of the name"};
+    case RemovalErrorKind::ProviderMismatch:
+        return {"xvm-remove-provider-mismatch",
+                "that version belongs to a different package; uninstall the "
+                "package that owns it"};
+    case RemovalErrorKind::ProviderVersionNotFound:
+        return {"xvm-remove-provider-version-unknown",
+                "this package owns no such version of that name; run "
+                "`xlings list` to see what it installed"};
+    case RemovalErrorKind::VersionMismatch:
+        return {"xvm-remove-version-mismatch",
+                "the recipe asks to remove a version other than the one it "
+                "owns; this is a recipe defect -- please report it upstream"};
+    }
+    return {kUnclassifiedCode, kUnclassifiedHint};
+}
+
+CodeAndHint describe_kind(BindingErrorKind kind) {
+    switch (kind) {
+    case BindingErrorKind::InvalidGraph:
+        return {"xvm-binding-graph-invalid",
+                "the stored bindings do not form a usable group; run "
+                "`xlings self doctor`"};
+    case BindingErrorKind::TargetNotFound:
+        return {"xvm-binding-target-missing",
+                "a member of this release is not registered; reinstall the "
+                "package to restore it"};
+    case BindingErrorKind::VersionNotFound:
+        return {"xvm-binding-version-missing",
+                "a member of this release is registered at no such version; "
+                "reinstall the package to restore it"};
+    case BindingErrorKind::RootReferenceMismatch:
+        return {"xvm-binding-root-mismatch",
+                "the release root does not point at itself; reinstall the "
+                "package, or run `xlings self doctor`"};
+    case BindingErrorKind::GroupIdentityMismatch:
+        return {"xvm-binding-identity-mismatch",
+                "members of this release disagree about which release they "
+                "belong to; reinstall the package"};
+    case BindingErrorKind::RootMissingFromManifest:
+        return {"xvm-binding-root-unlisted",
+                "the release root is absent from its own member list; "
+                "reinstall the package"};
+    case BindingErrorKind::StartMemberMissing:
+        return {"xvm-binding-member-unlisted",
+                "this name is not listed as a member of the release it "
+                "claims; reinstall the package"};
+    case BindingErrorKind::MemberReferenceMismatch:
+        return {"xvm-binding-member-mismatch",
+                "a member points back at a different release; reinstall the "
+                "package"};
+    case BindingErrorKind::UnsupportedKind:
+        return {"xvm-binding-kind-unsupported",
+                "a member is registered as something xvm cannot switch; this "
+                "is a recipe defect -- please report it upstream"};
+    case BindingErrorKind::SelfEdge:
+        return {"xvm-binding-self-edge",
+                "a stored binding points at itself; run `xlings self doctor`"};
+    case BindingErrorKind::AsymmetricEdge:
+        return {"xvm-binding-edge-asymmetric",
+                "a stored binding is one-sided; run `xlings self doctor`"};
+    case BindingErrorKind::ConflictingTargetVersion:
+        return {"xvm-binding-version-conflict",
+                "following the bindings reaches two versions of one name; "
+                "run `xlings self doctor`"};
+    case BindingErrorKind::PartialProviderMetadata:
+        return {"xvm-binding-metadata-partial",
+                "this entry carries a member list but no release identity; "
+                "reinstall the package"};
+    case BindingErrorKind::ProviderMetadataInLegacyGraph:
+        return {"xvm-binding-metadata-mixed",
+                "an entry mixes the current and the pre-0.4.70 binding "
+                "formats; reinstall the package"};
+    case BindingErrorKind::MetadataIntegrityIssue:
+        return {"xvm-binding-metadata-corrupt",
+                "the stored binding metadata could not be parsed; run "
+                "`xlings self doctor` to see the offending field"};
+    }
+    return {kUnclassifiedCode, kUnclassifiedHint};
+}
+
+XvmUserError describe(const RegistrationError& error, std::string provider) {
+    const auto [code, hint] = describe_kind(error.kind);
+    return {
+        .code = std::string(code),
+        .what = error.message,
+        .provider = std::move(provider),
+        .target = error.target,
+        .version = error.version,
+        .path = error.path,
+        .hint = std::string(hint),
+    };
+}
+
+XvmUserError describe(const RemovalError& error, std::string provider) {
+    const auto [code, hint] = describe_kind(error.kind);
+    auto what = error.message;
+    if (!error.peerTarget.empty()) {
+        what += std::format(" (peer {}@{})", error.peerTarget, error.peerVersion);
+    }
+    return {
+        .code = std::string(code),
+        .what = std::move(what),
+        .provider = std::move(provider),
+        .target = error.target,
+        .version = error.version,
+        .hint = std::string(hint),
+    };
+}
+
+XvmUserError describe(const BindingError& error, std::string provider) {
+    const auto [code, hint] = describe_kind(error.kind);
+    return {
+        .code = std::string(code),
+        .what = error.message,
+        .provider = std::move(provider),
+        .target = error.target,
+        .version = error.version,
+        .hint = std::string(hint),
+    };
+}
+
+std::string render(const XvmUserError& error, bool nothingChanged) {
+    std::string out = error.what;
+    out += std::format("\n          code:     {}", error.code);
+    if (!error.provider.empty()) {
+        out += std::format("\n          provider: {}", error.provider);
+    }
+    if (!error.target.empty()) {
+        out += std::format("\n          at:       {}{}{}", error.target,
+                           error.version.empty() ? "" : "@",
+                           error.version);
+    }
+    if (!error.path.empty()) {
+        out += std::format("\n          field:    {}", error.path);
+    }
+    out += std::format("\n          hint:     {}", error.hint);
+    if (nothingChanged) {
+        out += "\n          nothing was changed";
+    }
+    return out;
+}
+
+}
diff --git a/src/core/xvm/errors.cppm b/src/core/xvm/errors.cppm
index 340546c0..e20e04b5 100644
--- a/src/core/xvm/errors.cppm
+++ b/src/core/xvm/errors.cppm
@@ -41,235 +41,18 @@ struct CodeAndHint {
     std::string_view hint;
 };
 
-CodeAndHint describe_kind(RegistrationErrorKind kind) {
-    switch (kind) {
-    case RegistrationErrorKind::InvalidBatchIdentity:
-        return {"xvm-batch-identity-invalid",
-                "the package did not declare who owns these registrations; "
-                "this is a recipe defect -- please report it upstream"};
-    case RegistrationErrorKind::InvalidNodeIdentity:
-        return {"xvm-node-identity-invalid",
-                "a recipe registered something with no name or no version; "
-                "check the xvm.add calls in the package recipe"};
-    case RegistrationErrorKind::InvalidNodePayload:
-        return {"xvm-node-payload-invalid",
-                "a recipe registered an entry with an unusable kind or "
-                "filename; check the type/filename of that xvm.add call"};
-    case RegistrationErrorKind::InvalidBindingIdentity:
-        return {"xvm-binding-identity-invalid",
-                "a recipe declared a binding with no target; check the "
-                "binding argument of that xvm.add call"};
-    case RegistrationErrorKind::DuplicateNode:
-        return {"xvm-duplicate-registration",
-                "the recipe registers the same name and version twice; "
-                "remove the duplicate xvm.add"};
-    case RegistrationErrorKind::RootNotInBatch:
-        return {"xvm-binding-root-missing",
-                "a binding points at something the recipe never registers; "
-                "register the binding target in the same recipe"};
-    case RegistrationErrorKind::SelfBinding:
-        return {"xvm-self-binding",
-                "an entry binds to itself; drop the binding argument"};
-    case RegistrationErrorKind::GroupConflict:
-        return {"xvm-group-conflict",
-                "the recipe puts one release under two different roots; "
-                "give the members a single common binding target"};
-    case RegistrationErrorKind::TargetVersionConflict:
-        return {"xvm-group-version-conflict",
-                "one release selects two versions of the same program; "
-                "a toolchain release must pin exactly one version per name"};
-    case RegistrationErrorKind::OwnershipConflict:
-        return {"xvm-ownership-conflict",
-                "another package already owns this exact name and version; "
-                "uninstall that package first, or install this one at a "
-                "different version"};
-    // The three hints below all say "uninstall it first", and all three used
-    // to say it without naming a version. `xlings remove <name>` resolves
-    // through the ACTIVE binding, which in every situation these errors are
-    // raised in is a DIFFERENT version from the one that needs clearing -- so
-    // the official way out reported "not installed" and left the user with the
-    // tool's own `--force` warning as the only remaining move (#541 ②).
-    //
-    // A remedy that names no version is a remedy for whichever package happens
-    // to be active. Say `@<version>`.
-    case RegistrationErrorKind::LegacyPayloadMismatch:
-        return {"xvm-legacy-payload-mismatch",
-                "this name and version is already installed with different "
-                "contents; uninstall it with its version "
-                "(`xlings remove <name>@<version>`) before reinstalling"};
-    case RegistrationErrorKind::IncompleteLegacyComponent:
-        return {"xvm-legacy-component-incomplete",
-                "the install would rewrite part of an existing bound group; "
-                "uninstall the whole package first, naming its version "
-                "(`xlings remove <name>@<version>`)"};
-    case RegistrationErrorKind::IncompleteOwnedGroup:
-        return {"xvm-owned-group-incomplete",
-                "reinstalling this release would drop a member it already "
-                "owns; uninstall it with its version "
-                "(`xlings remove <name>@<version>`), then install again"};
-    case RegistrationErrorKind::InvalidHeader:
-        return {"xvm-header-invalid",
-                "a recipe declared headers with no source directory; check "
-                "the xvm.headers call"};
-    case RegistrationErrorKind::HeaderGroupNotFound:
-        return {"xvm-header-group-unknown",
-                "the headers name a group the recipe does not create; fix "
-                "the group name on the xvm.headers call"};
-    case RegistrationErrorKind::HeaderAmbiguous:
-        return {"xvm-header-owner-ambiguous",
-                "the recipe registers several groups and nothing says which "
-                "one ships these headers; name the group on xvm.headers"};
-    case RegistrationErrorKind::BindingValidationFailed:
-        return {"xvm-binding-validation-failed",
-                "the resulting version database would not be self-consistent; "
-                "run `xlings self doctor` to see the offending entries"};
-    }
-    return {kUnclassifiedCode, kUnclassifiedHint};
-}
+CodeAndHint describe_kind(RegistrationErrorKind kind);
 
-CodeAndHint describe_kind(RemovalErrorKind kind) {
-    switch (kind) {
-    case RemovalErrorKind::VersionNotFound:
-        return {"xvm-remove-version-unknown",
-                "that version is not registered; run `xlings list` to see "
-                "what is installed"};
-    case RemovalErrorKind::AmbiguousVersion:
-        return {"xvm-remove-version-ambiguous",
-                "several installed versions match; pass the fully qualified "
-                "version, including its namespace prefix"};
-    case RemovalErrorKind::AsymmetricEdge:
-        return {"xvm-remove-edge-asymmetric",
-                "the stored binding is one-sided, so removal cannot tell what "
-                "else to detach; run `xlings self doctor`"};
-    case RemovalErrorKind::SelectionInvalid:
-        return {"xvm-remove-selection-invalid",
-                "the release to remove does not resolve to a coherent set; "
-                "run `xlings self doctor`"};
-    case RemovalErrorKind::ProviderRequired:
-        return {"xvm-remove-provider-required",
-                "removing every version of a name requires knowing which "
-                "package owns them; remove the package instead of the name"};
-    case RemovalErrorKind::ProviderMismatch:
-        return {"xvm-remove-provider-mismatch",
-                "that version belongs to a different package; uninstall the "
-                "package that owns it"};
-    case RemovalErrorKind::ProviderVersionNotFound:
-        return {"xvm-remove-provider-version-unknown",
-                "this package owns no such version of that name; run "
-                "`xlings list` to see what it installed"};
-    case RemovalErrorKind::VersionMismatch:
-        return {"xvm-remove-version-mismatch",
-                "the recipe asks to remove a version other than the one it "
-                "owns; this is a recipe defect -- please report it upstream"};
-    }
-    return {kUnclassifiedCode, kUnclassifiedHint};
-}
+CodeAndHint describe_kind(RemovalErrorKind kind);
 
-CodeAndHint describe_kind(BindingErrorKind kind) {
-    switch (kind) {
-    case BindingErrorKind::InvalidGraph:
-        return {"xvm-binding-graph-invalid",
-                "the stored bindings do not form a usable group; run "
-                "`xlings self doctor`"};
-    case BindingErrorKind::TargetNotFound:
-        return {"xvm-binding-target-missing",
-                "a member of this release is not registered; reinstall the "
-                "package to restore it"};
-    case BindingErrorKind::VersionNotFound:
-        return {"xvm-binding-version-missing",
-                "a member of this release is registered at no such version; "
-                "reinstall the package to restore it"};
-    case BindingErrorKind::RootReferenceMismatch:
-        return {"xvm-binding-root-mismatch",
-                "the release root does not point at itself; reinstall the "
-                "package, or run `xlings self doctor`"};
-    case BindingErrorKind::GroupIdentityMismatch:
-        return {"xvm-binding-identity-mismatch",
-                "members of this release disagree about which release they "
-                "belong to; reinstall the package"};
-    case BindingErrorKind::RootMissingFromManifest:
-        return {"xvm-binding-root-unlisted",
-                "the release root is absent from its own member list; "
-                "reinstall the package"};
-    case BindingErrorKind::StartMemberMissing:
-        return {"xvm-binding-member-unlisted",
-                "this name is not listed as a member of the release it "
-                "claims; reinstall the package"};
-    case BindingErrorKind::MemberReferenceMismatch:
-        return {"xvm-binding-member-mismatch",
-                "a member points back at a different release; reinstall the "
-                "package"};
-    case BindingErrorKind::UnsupportedKind:
-        return {"xvm-binding-kind-unsupported",
-                "a member is registered as something xvm cannot switch; this "
-                "is a recipe defect -- please report it upstream"};
-    case BindingErrorKind::SelfEdge:
-        return {"xvm-binding-self-edge",
-                "a stored binding points at itself; run `xlings self doctor`"};
-    case BindingErrorKind::AsymmetricEdge:
-        return {"xvm-binding-edge-asymmetric",
-                "a stored binding is one-sided; run `xlings self doctor`"};
-    case BindingErrorKind::ConflictingTargetVersion:
-        return {"xvm-binding-version-conflict",
-                "following the bindings reaches two versions of one name; "
-                "run `xlings self doctor`"};
-    case BindingErrorKind::PartialProviderMetadata:
-        return {"xvm-binding-metadata-partial",
-                "this entry carries a member list but no release identity; "
-                "reinstall the package"};
-    case BindingErrorKind::ProviderMetadataInLegacyGraph:
-        return {"xvm-binding-metadata-mixed",
-                "an entry mixes the current and the pre-0.4.70 binding "
-                "formats; reinstall the package"};
-    case BindingErrorKind::MetadataIntegrityIssue:
-        return {"xvm-binding-metadata-corrupt",
-                "the stored binding metadata could not be parsed; run "
-                "`xlings self doctor` to see the offending field"};
-    }
-    return {kUnclassifiedCode, kUnclassifiedHint};
-}
+CodeAndHint describe_kind(BindingErrorKind kind);
 
 XvmUserError describe(const RegistrationError& error,
-                      std::string provider = {}) {
-    const auto [code, hint] = describe_kind(error.kind);
-    return {
-        .code = std::string(code),
-        .what = error.message,
-        .provider = std::move(provider),
-        .target = error.target,
-        .version = error.version,
-        .path = error.path,
-        .hint = std::string(hint),
-    };
-}
+                      std::string provider = {});
 
-XvmUserError describe(const RemovalError& error, std::string provider = {}) {
-    const auto [code, hint] = describe_kind(error.kind);
-    auto what = error.message;
-    if (!error.peerTarget.empty()) {
-        what += std::format(" (peer {}@{})", error.peerTarget, error.peerVersion);
-    }
-    return {
-        .code = std::string(code),
-        .what = std::move(what),
-        .provider = std::move(provider),
-        .target = error.target,
-        .version = error.version,
-        .hint = std::string(hint),
-    };
-}
+XvmUserError describe(const RemovalError& error, std::string provider = {});
 
-XvmUserError describe(const BindingError& error, std::string provider = {}) {
-    const auto [code, hint] = describe_kind(error.kind);
-    return {
-        .code = std::string(code),
-        .what = error.message,
-        .provider = std::move(provider),
-        .target = error.target,
-        .version = error.version,
-        .hint = std::string(hint),
-    };
-}
+XvmUserError describe(const BindingError& error, std::string provider = {});
 
 // One block suitable for a single log::error call: the summary first, then
 // indented detail. The logger supplies the "[error]" marker, so this does not
@@ -277,25 +60,6 @@ XvmUserError describe(const BindingError& error, std::string provider = {}) {
 //
 // `nothingChanged` is a promise, not decoration: pass true only where the
 // caller has actually left the stored state alone.
-std::string render(const XvmUserError& error, bool nothingChanged) {
-    std::string out = error.what;
-    out += std::format("\n          code:     {}", error.code);
-    if (!error.provider.empty()) {
-        out += std::format("\n          provider: {}", error.provider);
-    }
-    if (!error.target.empty()) {
-        out += std::format("\n          at:       {}{}{}", error.target,
-                           error.version.empty() ? "" : "@",
-                           error.version);
-    }
-    if (!error.path.empty()) {
-        out += std::format("\n          field:    {}", error.path);
-    }
-    out += std::format("\n          hint:     {}", error.hint);
-    if (nothingChanged) {
-        out += "\n          nothing was changed";
-    }
-    return out;
-}
+std::string render(const XvmUserError& error, bool nothingChanged);
 
 }  // namespace xlings::xvm
diff --git a/src/core/xvm/groups.cpp b/src/core/xvm/groups.cpp
new file mode 100644
index 00000000..287574ec
--- /dev/null
+++ b/src/core/xvm/groups.cpp
@@ -0,0 +1,175 @@
+module xlings.core.xvm.groups;
+
+import std;
+import xlings.core.xvm.types;
+
+namespace xlings::xvm {
+
+std::string binding_group_id(const BindingGroupRef& ref) {
+    return ref.provider + "@" + ref.providerVersion + "/" + ref.group;
+}
+
+std::string legacy_group_id(const std::map<std::string, std::string>& members) {
+    if (members.empty()) return {};
+    const auto& [target, version] = *members.begin();
+    return "legacy:" + target + "@" + version;
+}
+
+namespace detail_ {
+
+std::map<std::string, std::string>
+legacy_component(const VersionDB& db,
+                 const std::string& startTarget,
+                 const std::string& startVersion) {
+    std::map<std::string, std::string> members;
+    std::vector<std::pair<std::string, std::string>> queue;
+    queue.emplace_back(startTarget, startVersion);
+
+    while (!queue.empty()) {
+        auto [target, version] = queue.back();
+        queue.pop_back();
+        if (!members.emplace(target, version).second) continue;
+
+        auto infoIt = db.find(target);
+        if (infoIt == db.end()) continue;
+        for (const auto& [peerTarget, ownVersions] : infoIt->second.bindings) {
+            auto it = ownVersions.find(version);
+            if (it == ownVersions.end()) continue;
+            if (members.contains(peerTarget)) continue;
+
+            // A peer whose version is not registered is not a member. The
+            // edge names something nobody can switch to, so admitting it
+            // would build a group with a hole in it -- and a `use` that
+            // "succeeds" onto a version that does not exist is worse than the
+            // refusal it replaced.
+            //
+            // This is the difference between the two shapes that both look
+            // like a broken edge. `gcc@15.1.0 -> xim-gnu-gcc@15.1.0` where
+            // xim-gnu-gcc exists only at 16.1.0 is a dangling edge, and
+            // dropping it is repair (see XvmDanglingEdge). A pair where both
+            // versions exist but only one direction of the edge was written
+            // is a partial write, and reading it as a group is repair too.
+            // Membership, not reverse-reachability, is what tells them apart.
+            auto peerIt = db.find(peerTarget);
+            if (peerIt == db.end()) continue;
+            if (!peerIt->second.versions.contains(it->second)) continue;
+
+            queue.emplace_back(peerTarget, it->second);
+        }
+    }
+    return members;
+}
+
+}
+
+BindingGroupTable normalize_binding_groups(const VersionDB& db) {
+    BindingGroupTable table;
+
+    // Pass 1 -- root manifests. The manifest lives on one member; find it and
+    // lift it into a group of its own.
+    for (const auto& [target, info] : db) {
+        for (const auto& [version, data] : info.versions) {
+            if (!data.bindingGroup) continue;
+            if (data.bindingMembers.empty()
+                && !data.bindingMembersDeclared) continue;
+
+            auto id = binding_group_id(*data.bindingGroup);
+            if (id == "@/") continue;  // identity entirely blank: not a group
+
+            auto& g = table[id];
+            if (!g.id.empty()) {
+                // Two entries claim the same identity. Union the members
+                // rather than letting iteration order pick a winner -- a
+                // disagreement here is exactly the drift the top-level table
+                // exists to make visible, and dropping half of it would hide
+                // the evidence.
+                for (const auto& [t, v] : data.bindingMembers) g.members.emplace(t, v);
+                continue;
+            }
+            g.id              = id;
+            g.provider        = data.bindingGroup->provider;
+            g.providerVersion = data.bindingGroup->providerVersion;
+            g.group           = data.bindingGroup->group;
+            g.members         = data.bindingMembers;
+            g.headers         = data.bindingHeaders;
+            g.origin          = "root-manifest";
+            // The holder is a member even when the manifest forgot to say so.
+            // Under the old model that omission was an error
+            // (RootMissingFromManifest); here the fact that the entry carries
+            // the manifest already establishes membership.
+            g.members.emplace(target, version);
+        }
+    }
+
+    // Which (target, version) pairs pass 1 already accounts for. A legacy
+    // component overlapping any of them describes a group that has since been
+    // rewritten in the newer form, so it is not a second group.
+    std::set<std::pair<std::string, std::string>> claimed;
+    for (const auto& [_, g] : table) {
+        for (const auto& [t, v] : g.members) claimed.emplace(t, v);
+    }
+
+    // Pass 2 -- legacy pairwise edges (<= 0.4.69).
+    std::set<std::pair<std::string, std::string>> seen;
+    for (const auto& [target, info] : db) {
+        // Seeds are (target, ownVersion). The own version is the SECOND key --
+        // `bindings[peerTarget][ownVersion]` -- so it has to be collected from
+        // the inner maps. Reading it off the first key instead names a peer,
+        // and every component then starts from a pair that does not exist.
+        std::set<std::string> ownVersions;
+        for (const auto& [peerTarget, versionMap] : info.bindings) {
+            for (const auto& [ownVersion, peerVersion] : versionMap) {
+                ownVersions.insert(ownVersion);
+            }
+        }
+        for (const auto& version : ownVersions) {
+            if (claimed.contains({target, version})) continue;
+            if (seen.contains({target, version})) continue;
+
+            auto members = detail_::legacy_component(db, target, version);
+            for (const auto& [t, v] : members) seen.emplace(t, v);
+            if (members.size() < 2) continue;  // an edge to nowhere is not a group
+
+            // Overlap with a newer-form group anywhere in the component means
+            // the component is a stale remnant of it, not a group of its own.
+            bool overlaps = false;
+            for (const auto& [t, v] : members) {
+                if (claimed.contains({t, v})) { overlaps = true; break; }
+            }
+            if (overlaps) continue;
+
+            auto id = legacy_group_id(members);
+
+            // Components are disjoint, so their smallest members are distinct
+            // and a collision here cannot happen. It is still handled by
+            // merging rather than by `continue`: an earlier draft of the walk
+            // transposed the edge nesting, which made components overlap, and
+            // the `continue` then discarded 351 of 398 of them without a word.
+            // Dropping on a should-be-impossible condition is how that stayed
+            // invisible; unioning keeps the evidence if the invariant breaks.
+            auto [it, inserted] = table.try_emplace(id);
+            if (!inserted) {
+                for (auto& [t, v] : members) it->second.members.emplace(t, v);
+                continue;
+            }
+            it->second.id      = id;
+            it->second.group   = id;
+            it->second.members = std::move(members);
+            it->second.origin  = "legacy-edges";
+        }
+    }
+
+    return table;
+}
+
+const BindingGroup* find_binding_group(const BindingGroupTable& table,
+                                       const std::string& target,
+                                       const std::string& version) {
+    for (const auto& [_, g] : table) {
+        auto it = g.members.find(target);
+        if (it != g.members.end() && it->second == version) return &g;
+    }
+    return nullptr;
+}
+
+}
diff --git a/src/core/xvm/groups.cppm b/src/core/xvm/groups.cppm
index 07d8d2cf..eda5e45c 100644
--- a/src/core/xvm/groups.cppm
+++ b/src/core/xvm/groups.cppm
@@ -44,20 +44,14 @@ using BindingGroupTable = std::map<std::string, BindingGroup>;
 // `same_group_identity_` in bindings.cppm compares. rootTarget/rootVersion are
 // deliberately NOT part of it: which member happens to hold the manifest is
 // exactly the accident this normalization removes.
-std::string binding_group_id(const BindingGroupRef& ref) {
-    return ref.provider + "@" + ref.providerVersion + "/" + ref.group;
-}
+std::string binding_group_id(const BindingGroupRef& ref);
 
 // A legacy edge component has no recorded provider, so it gets one derived
 // from its own content. Deterministic and independent of iteration order: the
 // lexicographically smallest member names the group, so the same component
 // yields the same id on every load, which is what makes the normalized table
 // comparable across runs.
-std::string legacy_group_id(const std::map<std::string, std::string>& members) {
-    if (members.empty()) return {};
-    const auto& [target, version] = *members.begin();
-    return "legacy:" + target + "@" + version;
-}
+std::string legacy_group_id(const std::map<std::string, std::string>& members);
 
 namespace detail_ {
 
@@ -81,45 +75,7 @@ namespace detail_ {
 std::map<std::string, std::string>
 legacy_component(const VersionDB& db,
                  const std::string& startTarget,
-                 const std::string& startVersion) {
-    std::map<std::string, std::string> members;
-    std::vector<std::pair<std::string, std::string>> queue;
-    queue.emplace_back(startTarget, startVersion);
-
-    while (!queue.empty()) {
-        auto [target, version] = queue.back();
-        queue.pop_back();
-        if (!members.emplace(target, version).second) continue;
-
-        auto infoIt = db.find(target);
-        if (infoIt == db.end()) continue;
-        for (const auto& [peerTarget, ownVersions] : infoIt->second.bindings) {
-            auto it = ownVersions.find(version);
-            if (it == ownVersions.end()) continue;
-            if (members.contains(peerTarget)) continue;
-
-            // A peer whose version is not registered is not a member. The
-            // edge names something nobody can switch to, so admitting it
-            // would build a group with a hole in it -- and a `use` that
-            // "succeeds" onto a version that does not exist is worse than the
-            // refusal it replaced.
-            //
-            // This is the difference between the two shapes that both look
-            // like a broken edge. `gcc@15.1.0 -> xim-gnu-gcc@15.1.0` where
-            // xim-gnu-gcc exists only at 16.1.0 is a dangling edge, and
-            // dropping it is repair (see XvmDanglingEdge). A pair where both
-            // versions exist but only one direction of the edge was written
-            // is a partial write, and reading it as a group is repair too.
-            // Membership, not reverse-reachability, is what tells them apart.
-            auto peerIt = db.find(peerTarget);
-            if (peerIt == db.end()) continue;
-            if (!peerIt->second.versions.contains(it->second)) continue;
-
-            queue.emplace_back(peerTarget, it->second);
-        }
-    }
-    return members;
-}
+                 const std::string& startVersion);
 
 } // namespace detail_
 
@@ -139,105 +95,7 @@ legacy_component(const VersionDB& db,
 //
 // Pure over `db`, like inspect.cppm: no reads of the filesystem or the clock,
 // so every branch is reachable from a unit test.
-BindingGroupTable normalize_binding_groups(const VersionDB& db) {
-    BindingGroupTable table;
-
-    // Pass 1 -- root manifests. The manifest lives on one member; find it and
-    // lift it into a group of its own.
-    for (const auto& [target, info] : db) {
-        for (const auto& [version, data] : info.versions) {
-            if (!data.bindingGroup) continue;
-            if (data.bindingMembers.empty()
-                && !data.bindingMembersDeclared) continue;
-
-            auto id = binding_group_id(*data.bindingGroup);
-            if (id == "@/") continue;  // identity entirely blank: not a group
-
-            auto& g = table[id];
-            if (!g.id.empty()) {
-                // Two entries claim the same identity. Union the members
-                // rather than letting iteration order pick a winner -- a
-                // disagreement here is exactly the drift the top-level table
-                // exists to make visible, and dropping half of it would hide
-                // the evidence.
-                for (const auto& [t, v] : data.bindingMembers) g.members.emplace(t, v);
-                continue;
-            }
-            g.id              = id;
-            g.provider        = data.bindingGroup->provider;
-            g.providerVersion = data.bindingGroup->providerVersion;
-            g.group           = data.bindingGroup->group;
-            g.members         = data.bindingMembers;
-            g.headers         = data.bindingHeaders;
-            g.origin          = "root-manifest";
-            // The holder is a member even when the manifest forgot to say so.
-            // Under the old model that omission was an error
-            // (RootMissingFromManifest); here the fact that the entry carries
-            // the manifest already establishes membership.
-            g.members.emplace(target, version);
-        }
-    }
-
-    // Which (target, version) pairs pass 1 already accounts for. A legacy
-    // component overlapping any of them describes a group that has since been
-    // rewritten in the newer form, so it is not a second group.
-    std::set<std::pair<std::string, std::string>> claimed;
-    for (const auto& [_, g] : table) {
-        for (const auto& [t, v] : g.members) claimed.emplace(t, v);
-    }
-
-    // Pass 2 -- legacy pairwise edges (<= 0.4.69).
-    std::set<std::pair<std::string, std::string>> seen;
-    for (const auto& [target, info] : db) {
-        // Seeds are (target, ownVersion). The own version is the SECOND key --
-        // `bindings[peerTarget][ownVersion]` -- so it has to be collected from
-        // the inner maps. Reading it off the first key instead names a peer,
-        // and every component then starts from a pair that does not exist.
-        std::set<std::string> ownVersions;
-        for (const auto& [peerTarget, versionMap] : info.bindings) {
-            for (const auto& [ownVersion, peerVersion] : versionMap) {
-                ownVersions.insert(ownVersion);
-            }
-        }
-        for (const auto& version : ownVersions) {
-            if (claimed.contains({target, version})) continue;
-            if (seen.contains({target, version})) continue;
-
-            auto members = detail_::legacy_component(db, target, version);
-            for (const auto& [t, v] : members) seen.emplace(t, v);
-            if (members.size() < 2) continue;  // an edge to nowhere is not a group
-
-            // Overlap with a newer-form group anywhere in the component means
-            // the component is a stale remnant of it, not a group of its own.
-            bool overlaps = false;
-            for (const auto& [t, v] : members) {
-                if (claimed.contains({t, v})) { overlaps = true; break; }
-            }
-            if (overlaps) continue;
-
-            auto id = legacy_group_id(members);
-
-            // Components are disjoint, so their smallest members are distinct
-            // and a collision here cannot happen. It is still handled by
-            // merging rather than by `continue`: an earlier draft of the walk
-            // transposed the edge nesting, which made components overlap, and
-            // the `continue` then discarded 351 of 398 of them without a word.
-            // Dropping on a should-be-impossible condition is how that stayed
-            // invisible; unioning keeps the evidence if the invariant breaks.
-            auto [it, inserted] = table.try_emplace(id);
-            if (!inserted) {
-                for (auto& [t, v] : members) it->second.members.emplace(t, v);
-                continue;
-            }
-            it->second.id      = id;
-            it->second.group   = id;
-            it->second.members = std::move(members);
-            it->second.origin  = "legacy-edges";
-        }
-    }
-
-    return table;
-}
+BindingGroupTable normalize_binding_groups(const VersionDB& db);
 
 // The group a given entry belongs to, or nullptr.
 //
@@ -245,12 +103,6 @@ BindingGroupTable normalize_binding_groups(const VersionDB& db) {
 // the group owns its members: one lookup and one membership test.
 const BindingGroup* find_binding_group(const BindingGroupTable& table,
                                        const std::string& target,
-                                       const std::string& version) {
-    for (const auto& [_, g] : table) {
-        auto it = g.members.find(target);
-        if (it != g.members.end() && it->second == version) return &g;
-    }
-    return nullptr;
-}
+                                       const std::string& version);
 
 } // namespace xlings::xvm
diff --git a/src/core/xvm/inspect.cpp b/src/core/xvm/inspect.cpp
new file mode 100644
index 00000000..8ee9908e
--- /dev/null
+++ b/src/core/xvm/inspect.cpp
@@ -0,0 +1,657 @@
+module xlings.core.xvm.inspect;
+
+import std;
+import xlings.core.xvm.types;
+import xlings.core.xvm.bindings;
+import xlings.core.xvm.errors;
+import xlings.core.xvm.db;
+
+namespace xlings::xvm::detail_ {
+
+// Does the release this version belongs to declare any file asset?
+//
+// Asked of the release rather than the entry itself because a file asset is
+// registered as its own target (`<pkg>.files.<n>`) bound to the release, not
+// as a field on the package's own entry.
+bool release_declares_file_assets_(const VersionDB& db,
+                                   const std::string& target,
+                                   const std::string& version) {
+    auto selection = resolve_binding_selection(db, target, version);
+    if (!selection) return false;
+    for (const auto& [memberTarget, memberVersion] : selection->members) {
+        auto infoIt = db.find(memberTarget);
+        if (infoIt == db.end()) continue;
+        auto dataIt = infoIt->second.versions.find(memberVersion);
+        if (dataIt == infoIt->second.versions.end()) continue;
+        if (effective_kind(infoIt->second, dataIt->second) == "files") {
+            return true;
+        }
+    }
+    return false;
+}
+
+// Is this member's name currently held by a DIFFERENT provider?
+//
+// Two packages can register the same program name: node's release registers
+// `npm`, and a standalone npm package registers it too. Whichever is active,
+// the other release's member is "wrong" by version alone -- and treating that
+// as a broken release is wrong twice over. As a report it tells the user to
+// run a `use` that would take the name away from the package they chose; as a
+// REPAIR it tears down a release that is working. A contest with the SAME
+// provider is a genuinely split release and is neither.
+//
+// Extracted because the reporter and the repairer disagreed about it and that
+// disagreement shipped. `analyze_bindings` (INV-2) learned this rule in
+// 2026.8.1.1; `plan_incoherent_deactivation` -- which is what `self doctor
+// --fix` actually executes -- did not. So doctor said "this home is fine" and
+// `--fix`, on the same home, took `gcc` and `ld` down. One predicate, both
+// callers: the two cannot drift again.
+bool held_by_another_provider_(const VersionDB& db,
+                               const Workspace& workspace,
+                               const std::string& memberTarget,
+                               const std::string& releaseProvider) {
+    const auto activeIt = workspace.find(memberTarget);
+    if (activeIt == workspace.end()) return false;
+    const auto holderIt = db.find(memberTarget);
+    if (holderIt == db.end()) return false;
+    const auto heldIt = holderIt->second.versions.find(activeIt->second);
+    if (heldIt == holderIt->second.versions.end()) return false;
+    // No group metadata means an entry written before providers were
+    // recorded. Treated as the same provider, so old homes keep the older,
+    // stricter behaviour rather than silently losing a coherence check.
+    if (!heldIt->second.bindingGroup) return false;
+    return heldIt->second.bindingGroup->provider != releaseProvider;
+}
+
+}
+
+namespace xlings::xvm {
+
+std::vector<BindingFinding> inspect_binding_state(
+        const VersionDB& db,
+        const Workspace& workspace) {
+    std::vector<BindingFinding> findings;
+
+    // ── Metadata integrity ───────────────────────────────────────────
+    for (const auto& [target, info] : db) {
+        for (const auto& [version, data] : info.versions) {
+            for (const auto& issue : data.bindingIntegrityIssues) {
+                findings.push_back({
+                    .code = "xvm-binding-metadata-corrupt",
+                    .summary = std::format(
+                        "stored binding metadata is unreadable ({})",
+                        issue.code),
+                    .target = target,
+                    .version = version,
+                    .field = issue.path,
+                    // Reinstall first: it restores the release. The reset
+                    // only discards it, and is the answer when the package
+                    // is no longer installable.
+                    .hint = "reinstall the package that owns this entry, or "
+                            "run `xlings self doctor --reset-metadata` to "
+                            "discard the unreadable release metadata",
+                });
+            }
+        }
+    }
+
+    // ── INV-1: the workspace points at something that exists ─────────
+    for (const auto& [target, version] : workspace) {
+        auto infoIt = db.find(target);
+        if (infoIt != db.end() && infoIt->second.versions.contains(version)) {
+            continue;
+        }
+        findings.push_back({
+            .code = "xvm-active-version-missing",
+            .summary = "the active version is not registered",
+            .target = target,
+            .version = version,
+            .hint = std::format(
+                "run `xlings install {}` to restore it, or `xlings use {} "
+                "<other-version>`", target, target),
+        });
+    }
+
+    // ── INV-4: every group resolves ──────────────────────────────────
+    //
+    // One report per group rather than per member: a five-member toolchain
+    // with one missing member is one problem, and printing it five times
+    // buries the rest of the output.
+    std::set<std::tuple<std::string, std::string, std::string>> seenGroups;
+    for (const auto& [target, info] : db) {
+        for (const auto& [version, data] : info.versions) {
+            if (!data.bindingGroup) continue;
+            if (!data.bindingIntegrityIssues.empty()) continue;  // already reported
+            const auto& ref = *data.bindingGroup;
+            if (!seenGroups.emplace(ref.provider, ref.providerVersion,
+                                    ref.group).second) {
+                continue;
+            }
+            auto selection = resolve_binding_selection(db, target, version);
+            if (selection) continue;
+            const auto described = describe(selection.error());
+            findings.push_back({
+                .code = described.code,
+                .summary = std::format("release {}@{} does not resolve: {}",
+                                       ref.provider, ref.providerVersion,
+                                       described.what),
+                .target = described.target,
+                .version = described.version,
+                .hint = described.hint,
+            });
+        }
+    }
+
+    // ── Dangling legacy edges ────────────────────────────────────────
+    //
+    // The INV-4 pass above only looks at entries that carry a
+    // `bindingGroup`. Everything written before 0.4.70 does not, so its
+    // pairwise edges were never checked -- and a pairwise edge pointing at a
+    // version that no longer exists makes the whole release unresolvable.
+    //
+    // This is not hypothetical. On a real installation `gcc@15.1.0` carries
+    // an edge to `xim-gnu-gcc@15.1.0`, an anchor that only exists at 16.1.0,
+    // so `xlings use gcc 15.1.0` -- which worked on 0.4.68 -- is refused with
+    // "a member of this release is registered at no such version". Nothing
+    // reported it and `--fix` could not repair it, leaving reinstall as the
+    // only way out. That is the upgrade being anything but seamless.
+    //
+    // An edge whose destination does not exist carries no information: it
+    // cannot name a member to switch, it can only cause a refusal. Reporting
+    // it separately from INV-4 keeps the remedy separate too -- this one is
+    // repairable without guessing, and INV-4's is not.
+    for (const auto& [target, info] : db) {
+        for (const auto& [peerTarget, edges] : info.bindings) {
+            auto peerIt = db.find(peerTarget);
+            for (const auto& [ownVersion, peerVersion] : edges) {
+                // Two ways an edge can name nothing, and both were treated
+                // very differently for no reason.
+                //
+                // The peer side was reported and repaired. The SOURCE side --
+                // an edge keyed by a version of the owner that is not itself
+                // registered -- was skipped by this loop and by the pruning
+                // plan, so it was invisible AND permanent. It is not
+                // harmless: resolve_binding_selection walks it and fails with
+                // "legacy binding source version is missing", which makes
+                // every future registration of that target refuse. Measured
+                // on a real home, `xim-musl-gnu-gcc` carries five such edges
+                // keyed at `15.1.0-musl` while only `15.1.0` is registered,
+                // and `xlings install musl-gcc@15.1.0` had been failing on it
+                // with no finding anywhere that named the cause.
+                const bool sourceMissing =
+                    !info.versions.contains(ownVersion);
+                const bool peerMissing =
+                    peerIt == db.end()
+                    || !peerIt->second.versions.contains(peerVersion);
+                if (!sourceMissing && !peerMissing) continue;
+                findings.push_back({
+                    .code = "xvm-legacy-edge-dangling",
+                    .summary = sourceMissing
+                        ? std::format(
+                            "a binding edge is keyed at '{}', which is not "
+                            "registered",
+                            display_coordinate(target, ownVersion))
+                        : std::format(
+                            "a binding edge points at '{}', which is not "
+                            "registered",
+                            display_coordinate(peerTarget, peerVersion)),
+                    .target = target,
+                    .version = ownVersion,
+                    .field = std::format("/bindings/{}", peerTarget),
+                    .hint = "run `xlings self doctor --fix` to drop the edge; "
+                            "it names nothing and only blocks switching",
+                });
+            }
+        }
+    }
+
+    // ── Sysroot assets placed before this client tracked them ────────
+    //
+    // Before 2026.7.27.0 a recipe put headers into the sysroot with plain
+    // Lua inside `config()` -- `os.cp`, or `sysroot.install_headers`.
+    // Nothing recorded it, so those files are invisible to the version
+    // database and `xlings use` cannot move them.
+    //
+    // On its own that is not new: such a version could never switch its
+    // headers. What upgrading changes is that it becomes *inconsistent* --
+    // one version of a package now switches its headers and another
+    // silently does not, and the failure surfaces as a build picking up the
+    // wrong header, long after the `use` that reported success.
+    //
+    // Hence the pairing requirement: reported only when another version of
+    // the same target does declare file assets. Without it, every package
+    // that simply ships no headers would be flagged.
+    for (const auto& [target, info] : db) {
+        if (info.versions.size() < 2) continue;
+        std::vector<std::string> untracked;
+        bool anyTracked = false;
+        for (const auto& [version, data] : info.versions) {
+            // Only the entry point users actually switch. Members of a
+            // release resolve to the same set, so checking them too would
+            // report one problem once per library in the toolchain.
+            if (effective_kind(info, data) != "program") continue;
+            if (detail_::release_declares_file_assets_(db, target, version)) {
+                anyTracked = true;
+            } else {
+                untracked.push_back(version);
+            }
+        }
+        if (!anyTracked || untracked.empty()) continue;
+        for (const auto& version : untracked) {
+            findings.push_back({
+                .code = "xvm-sysroot-untracked",
+                .summary = std::format(
+                    "installed before file tracking: sysroot files for {}@{} "
+                    "will not follow a version switch", target, version),
+                .target = target,
+                .version = version,
+                .hint = std::format(
+                    "run `xlings install {}` to re-register them",
+                    display_coordinate(target, version)),
+                .severity = BindingSeverity::Notice,
+            });
+        }
+    }
+
+    // ── INV-2: an active release is active as a whole ────────────────
+    std::set<std::string> reportedIncoherent;
+    for (const auto& [target, version] : workspace) {
+        auto infoIt = db.find(target);
+        if (infoIt == db.end()) continue;
+        auto dataIt = infoIt->second.versions.find(version);
+        if (dataIt == infoIt->second.versions.end()) continue;
+        if (!dataIt->second.bindingGroup) continue;
+        auto selection = resolve_binding_selection(db, target, version);
+        if (!selection) continue;  // reported by INV-4 already
+
+        for (const auto& [memberTarget, memberVersion] : selection->members) {
+            auto activeIt = workspace.find(memberTarget);
+            const bool coherent = activeIt != workspace.end()
+                && activeIt->second == memberVersion;
+            if (coherent) continue;
+
+            if (detail_::held_by_another_provider_(
+                    db, workspace, memberTarget,
+                    dataIt->second.bindingGroup->provider)) {
+                continue;
+            }
+            const auto key = dataIt->second.bindingGroup->provider + "@"
+                + dataIt->second.bindingGroup->providerVersion + "/"
+                + memberTarget;
+            if (!reportedIncoherent.insert(key).second) continue;
+            findings.push_back({
+                .code = "xvm-active-group-incoherent",
+                .summary = std::format(
+                    "'{}' is active at {} but '{}' of the same release is {}",
+                    target, version, memberTarget,
+                    activeIt == workspace.end()
+                        ? std::string("not active")
+                        : std::format("active at {}", activeIt->second)),
+                .target = memberTarget,
+                .version = memberVersion,
+                .hint = std::format(
+                    "run `xlings use {} {}` to bring the whole release back "
+                    "in step", target, version),
+            });
+        }
+    }
+
+    return findings;
+}
+
+bool subos_claims(const Workspace& active,
+                  const WorkspaceInstalled& installed,
+                  const std::string& target,
+                  const std::string& version) {
+    if (auto it = active.find(target);
+        it != active.end() && it->second == version) {
+        return true;
+    }
+    if (auto it = installed.find(target); it != installed.end()) {
+        return std::ranges::find(it->second, version) != it->second.end();
+    }
+    return false;
+}
+
+OwnershipVerdict subos_ownership(const Workspace& active,
+                                 const WorkspaceInstalled& installed,
+                                 const std::vector<SubosRef>& others,
+                                 const std::string& target,
+                                 const std::string& version) {
+    OwnershipVerdict verdict;
+    verdict.ownedHere = subos_claims(active, installed, target, version);
+    for (const auto& other : others) {
+        if (subos_claims(other.active, other.installed, target, version)) {
+            verdict.otherSubos.push_back(other.subos);
+        }
+    }
+    std::ranges::sort(verdict.otherSubos);
+    auto dup = std::ranges::unique(verdict.otherSubos);
+    verdict.otherSubos.erase(dup.begin(), dup.end());
+    return verdict;
+}
+
+std::vector<BindingFinding> inspect_subos_references(
+        const VersionDB& db,
+        const std::vector<SubosRef>& others) {
+    std::vector<BindingFinding> findings;
+
+    const auto registered = [&](const std::string& target,
+                                const std::string& version) {
+        auto it = db.find(target);
+        return it != db.end() && it->second.versions.contains(version);
+    };
+
+    for (const auto& other : others) {
+        for (const auto& [target, version] : other.active) {
+            if (version.empty() || registered(target, version)) continue;
+            findings.push_back({
+                .code = "xvm-subos-active-missing",
+                .summary = std::format(
+                    "subos '{}' has '{}' active at {}, which is not registered",
+                    other.subos, target, version),
+                .target = target,
+                .version = version,
+                .hint = std::format(
+                    "run `xlings subos use {}` then `xlings install {}` to "
+                    "restore it, or `xlings use {} <other-version>` there",
+                    other.subos, display_coordinate(target, version), target),
+            });
+        }
+        for (const auto& [target, versions] : other.installed) {
+            for (const auto& version : versions) {
+                if (version.empty() || registered(target, version)) continue;
+                // Notice, not Broken: nothing dispatches through installed[],
+                // so this subos still works. It matters because removal counts
+                // references through this set -- a dangling entry keeps a
+                // payload pinned against a version that no longer exists.
+                findings.push_back({
+                    .code = "xvm-subos-installed-dangling",
+                    .summary = std::format(
+                        "subos '{}' lists '{}' as installed, but it is not "
+                        "registered", other.subos,
+                        display_coordinate(target, version)),
+                    .target = target,
+                    .version = version,
+                    .hint = std::format(
+                        "run `xlings subos use {}` then `xlings remove {}` "
+                        "to drop the stale entry", other.subos,
+                        display_coordinate(target, version)),
+                    .severity = BindingSeverity::Notice,
+                });
+            }
+        }
+    }
+    return findings;
+}
+
+std::vector<BindingFinding> inspect_sysroot_ownership(
+        const VersionDB& db,
+        const Workspace& workspace,
+        const std::vector<SysrootEntry>& entries,
+        std::string_view payloadRoot) {
+    std::vector<BindingFinding> findings;
+    if (payloadRoot.empty()) return findings;
+
+    // Destinations the active selection says should be ours.
+    std::map<std::string, std::pair<std::string, std::string>> claimed;
+    for (const auto& [target, version] : workspace) {
+        auto infoIt = db.find(target);
+        if (infoIt == db.end()) continue;
+        auto dataIt = infoIt->second.versions.find(version);
+        if (dataIt == infoIt->second.versions.end()) continue;
+        if (!dataIt->second.fileDst.empty()) {
+            claimed.emplace(dataIt->second.fileDst,
+                            std::pair{target, version});
+        }
+    }
+
+    for (const auto& entry : entries) {
+        const bool ours = !entry.linkTarget.empty()
+            && std::string_view{entry.linkTarget}.starts_with(payloadRoot);
+        if (ours) continue;
+
+        if (auto it = claimed.find(entry.path); it != claimed.end()) {
+            // Declared, but what is on disk is not the link we would have
+            // made. Something replaced it after the fact.
+            findings.push_back({
+                .code = "xvm-sysroot-drift",
+                .summary = std::format(
+                    "'{}' is declared by {}@{} but is not the link xlings "
+                    "placed", entry.path, it->second.first,
+                    it->second.second),
+                .target = it->second.first,
+                .version = it->second.second,
+                .hint = std::format(
+                    "run `xlings use {} {}` to put it back",
+                    it->second.first, it->second.second),
+            });
+            continue;
+        }
+
+        // Nothing claims it. Could be the host image, could be a package
+        // that placed it by hand and is now gone -- either way xlings will
+        // not move it on a version switch, and cannot remove it.
+        findings.push_back({
+            .code = "xvm-sysroot-unmanaged",
+            .summary = std::format(
+                "'{}' is in the subos but no package declares it", entry.path),
+            .hint = "left as-is; xlings only moves what a package declares",
+            .severity = BindingSeverity::Notice,
+        });
+    }
+    return findings;
+}
+
+SubosMetadataRepair plan_subos_metadata_repair(
+        const VersionDB& db,
+        const std::vector<SubosRef>& others) {
+    const auto registered = [&](const std::string& target,
+                                const std::string& version) {
+        auto it = db.find(target);
+        return it != db.end() && it->second.versions.contains(version);
+    };
+
+    SubosMetadataRepair plan;
+    for (const auto& other : others) {
+        SubosMetadataRepair::Entry entry{.subos = other.subos};
+        for (const auto& [target, version] : other.active) {
+            if (version.empty() || registered(target, version)) continue;
+            entry.deactivate.push_back(target);
+        }
+        for (const auto& [target, versions] : other.installed) {
+            for (const auto& version : versions) {
+                if (version.empty() || registered(target, version)) continue;
+                entry.dropInstalled.emplace_back(target, version);
+            }
+        }
+        if (entry.deactivate.empty() && entry.dropInstalled.empty()) continue;
+        plan.entries.push_back(std::move(entry));
+    }
+    return plan;
+}
+
+std::size_t apply_subos_metadata_repair(
+        SubosWorkspace& workspace,
+        const SubosMetadataRepair::Entry& entry) {
+    std::size_t dropped = 0;
+    for (const auto& target : entry.deactivate) {
+        dropped += workspace.active.erase(target);
+    }
+    for (const auto& [target, version] : entry.dropInstalled) {
+        auto it = workspace.installed.find(target);
+        if (it == workspace.installed.end()) continue;
+        const auto before = it->second.size();
+        std::erase(it->second, version);
+        dropped += before - it->second.size();
+        if (it->second.empty()) workspace.installed.erase(it);
+    }
+    return dropped;
+}
+
+std::vector<std::string> plan_unregistered_active_deactivation(
+        const VersionDB& db,
+        const Workspace& workspace) {
+    std::vector<std::string> targets;
+    for (const auto& [target, version] : workspace) {
+        if (version.empty()) continue;
+        auto it = db.find(target);
+        if (it != db.end() && it->second.versions.contains(version)) continue;
+        targets.push_back(target);
+    }
+    return targets;
+}
+
+DeactivationPlan plan_incoherent_deactivation(const VersionDB& db,
+                                              const Workspace& workspace) {
+    DeactivationPlan plan;
+    for (const auto& [target, version] : workspace) {
+        auto infoIt = db.find(target);
+        if (infoIt == db.end()) continue;
+        auto dataIt = infoIt->second.versions.find(version);
+        if (dataIt == infoIt->second.versions.end()) continue;
+        if (!dataIt->second.bindingGroup) continue;
+        auto selection = resolve_binding_selection(db, target, version);
+        if (!selection) continue;  // unresolvable is a different problem
+
+        const auto& ref = *dataIt->second.bindingGroup;
+
+        // Exactly the predicate INV-2 reports with. A member whose name is
+        // held by another provider is not this release breaking step, so it
+        // must not put this release on the teardown list either -- which it
+        // did until 2026.8.1.2, making `--fix` demolish releases `self doctor`
+        // had just called healthy.
+        const bool coherent = std::ranges::all_of(
+            selection->members, [&](const auto& member) {
+                auto activeIt = workspace.find(member.first);
+                if (activeIt != workspace.end()
+                    && activeIt->second == member.second) {
+                    return true;
+                }
+                return detail_::held_by_another_provider_(
+                    db, workspace, member.first, ref.provider);
+            });
+        if (coherent) continue;
+
+        const auto label =
+            std::format("{}@{}", ref.provider, ref.providerVersion);
+        // Take down every member of this release that is active, not just
+        // the entry point: leaving the rest behind would swap one
+        // incoherent state for another.
+        for (const auto& [memberTarget, memberVersion] : selection->members) {
+            auto activeIt = workspace.find(memberTarget);
+            if (activeIt == workspace.end()) continue;
+            if (activeIt->second != memberVersion) continue;
+            plan.targets.emplace(memberTarget, label);
+        }
+        plan.targets.emplace(target, label);
+    }
+    return plan;
+}
+
+MetadataReset plan_metadata_reset(const VersionDB& db) {
+    MetadataReset plan;
+    for (const auto& [target, info] : db) {
+        for (const auto& [version, data] : info.versions) {
+            if (data.bindingIntegrityIssues.empty()) continue;
+            MetadataReset::Entry entry{.target = target, .version = version};
+            for (const auto& issue : data.bindingIntegrityIssues) {
+                entry.codes.push_back(issue.code);
+            }
+            plan.entries.push_back(std::move(entry));
+        }
+    }
+    return plan;
+}
+
+std::size_t apply_metadata_reset(VersionDB& db, const MetadataReset& plan) {
+    std::size_t cleared = 0;
+    for (const auto& entry : plan.entries) {
+        auto infoIt = db.find(entry.target);
+        if (infoIt == db.end()) continue;
+        auto dataIt = infoIt->second.versions.find(entry.version);
+        if (dataIt == infoIt->second.versions.end()) continue;
+        auto& data = dataIt->second;
+        if (data.bindingIntegrityIssues.empty()) continue;
+
+        // Everything that describes the release, including the preserved
+        // originals -- leaving those behind would resurrect the corruption
+        // on the next save, which is the one outcome a reset must not have.
+        data.bindingGroup.reset();
+        data.bindingMembers.clear();
+        data.bindingHeaders.clear();
+        data.bindingMembersDeclared = false;
+        data.bindingHeadersDeclared = false;
+        data.bindingIntegrityIssues.clear();
+        data.bindingUnreadable.clear();
+        ++cleared;
+    }
+    return cleared;
+}
+
+DanglingEdgePruning plan_dangling_edge_pruning(const VersionDB& db) {
+    DanglingEdgePruning plan;
+    for (const auto& [target, info] : db) {
+        for (const auto& [peerTarget, edges] : info.bindings) {
+            auto peerIt = db.find(peerTarget);
+            for (const auto& [ownVersion, peerVersion] : edges) {
+                // Source side as well as peer side -- see the matching note in
+                // inspect_binding_state. Skipping the source side left an edge
+                // that no command could remove and that made every
+                // registration of its owner refuse.
+                const bool sourceMissing =
+                    !info.versions.contains(ownVersion);
+                const bool peerMissing =
+                    peerIt == db.end()
+                    || !peerIt->second.versions.contains(peerVersion);
+                if (!sourceMissing && !peerMissing) continue;
+                plan.edges.push_back({target, ownVersion,
+                                      peerTarget, peerVersion});
+            }
+        }
+    }
+    return plan;
+}
+
+std::size_t apply_dangling_edge_pruning(VersionDB& db,
+                                        const DanglingEdgePruning& plan) {
+    std::size_t dropped = 0;
+    for (const auto& edge : plan.edges) {
+        auto infoIt = db.find(edge.target);
+        if (infoIt == db.end()) continue;
+        auto peerIt = infoIt->second.bindings.find(edge.peerTarget);
+        if (peerIt == infoIt->second.bindings.end()) continue;
+        auto versionIt = peerIt->second.find(edge.version);
+        if (versionIt == peerIt->second.end()) continue;
+        if (versionIt->second != edge.peerVersion) continue;
+        peerIt->second.erase(versionIt);
+        ++dropped;
+        if (peerIt->second.empty()) {
+            infoIt->second.bindings.erase(peerIt);
+        }
+    }
+    return dropped;
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::xvm {
+
+[[nodiscard]] bool SubosMetadataRepair::empty() const { return entries.empty(); }
+
+[[nodiscard]] std::size_t SubosMetadataRepair::size() const {
+    std::size_t n = 0;
+    for (const auto& e : entries) {
+        n += e.deactivate.size() + e.dropInstalled.size();
+    }
+    return n;
+}
+
+[[nodiscard]] bool MetadataReset::empty() const { return entries.empty(); }
+
+[[nodiscard]] bool DanglingEdgePruning::empty() const { return edges.empty(); }
+
+} // namespace xlings::xvm
diff --git a/src/core/xvm/inspect.cppm b/src/core/xvm/inspect.cppm
index 7bf9f9f0..40675582 100644
--- a/src/core/xvm/inspect.cppm
+++ b/src/core/xvm/inspect.cppm
@@ -20,61 +20,6 @@ import xlings.core.xvm.db;   // display_coordinate
 // test, and doctor stays a renderer.
 namespace xlings::xvm::detail_ {
 
-// Does the release this version belongs to declare any file asset?
-//
-// Asked of the release rather than the entry itself because a file asset is
-// registered as its own target (`<pkg>.files.<n>`) bound to the release, not
-// as a field on the package's own entry.
-bool release_declares_file_assets_(const VersionDB& db,
-                                   const std::string& target,
-                                   const std::string& version) {
-    auto selection = resolve_binding_selection(db, target, version);
-    if (!selection) return false;
-    for (const auto& [memberTarget, memberVersion] : selection->members) {
-        auto infoIt = db.find(memberTarget);
-        if (infoIt == db.end()) continue;
-        auto dataIt = infoIt->second.versions.find(memberVersion);
-        if (dataIt == infoIt->second.versions.end()) continue;
-        if (effective_kind(infoIt->second, dataIt->second) == "files") {
-            return true;
-        }
-    }
-    return false;
-}
-
-// Is this member's name currently held by a DIFFERENT provider?
-//
-// Two packages can register the same program name: node's release registers
-// `npm`, and a standalone npm package registers it too. Whichever is active,
-// the other release's member is "wrong" by version alone -- and treating that
-// as a broken release is wrong twice over. As a report it tells the user to
-// run a `use` that would take the name away from the package they chose; as a
-// REPAIR it tears down a release that is working. A contest with the SAME
-// provider is a genuinely split release and is neither.
-//
-// Extracted because the reporter and the repairer disagreed about it and that
-// disagreement shipped. `analyze_bindings` (INV-2) learned this rule in
-// 2026.8.1.1; `plan_incoherent_deactivation` -- which is what `self doctor
-// --fix` actually executes -- did not. So doctor said "this home is fine" and
-// `--fix`, on the same home, took `gcc` and `ld` down. One predicate, both
-// callers: the two cannot drift again.
-bool held_by_another_provider_(const VersionDB& db,
-                               const Workspace& workspace,
-                               const std::string& memberTarget,
-                               const std::string& releaseProvider) {
-    const auto activeIt = workspace.find(memberTarget);
-    if (activeIt == workspace.end()) return false;
-    const auto holderIt = db.find(memberTarget);
-    if (holderIt == db.end()) return false;
-    const auto heldIt = holderIt->second.versions.find(activeIt->second);
-    if (heldIt == holderIt->second.versions.end()) return false;
-    // No group metadata means an entry written before providers were
-    // recorded. Treated as the same provider, so old homes keep the older,
-    // stricter behaviour rather than silently losing a coherence check.
-    if (!heldIt->second.bindingGroup) return false;
-    return heldIt->second.bindingGroup->provider != releaseProvider;
-}
-
 }  // namespace xlings::xvm::detail_
 
 export namespace xlings::xvm {
@@ -109,235 +54,7 @@ struct BindingFinding {
 // symptom, so reporting the symptoms above it would just be noise.
 std::vector<BindingFinding> inspect_binding_state(
         const VersionDB& db,
-        const Workspace& workspace) {
-    std::vector<BindingFinding> findings;
-
-    // ── Metadata integrity ───────────────────────────────────────────
-    for (const auto& [target, info] : db) {
-        for (const auto& [version, data] : info.versions) {
-            for (const auto& issue : data.bindingIntegrityIssues) {
-                findings.push_back({
-                    .code = "xvm-binding-metadata-corrupt",
-                    .summary = std::format(
-                        "stored binding metadata is unreadable ({})",
-                        issue.code),
-                    .target = target,
-                    .version = version,
-                    .field = issue.path,
-                    // Reinstall first: it restores the release. The reset
-                    // only discards it, and is the answer when the package
-                    // is no longer installable.
-                    .hint = "reinstall the package that owns this entry, or "
-                            "run `xlings self doctor --reset-metadata` to "
-                            "discard the unreadable release metadata",
-                });
-            }
-        }
-    }
-
-    // ── INV-1: the workspace points at something that exists ─────────
-    for (const auto& [target, version] : workspace) {
-        auto infoIt = db.find(target);
-        if (infoIt != db.end() && infoIt->second.versions.contains(version)) {
-            continue;
-        }
-        findings.push_back({
-            .code = "xvm-active-version-missing",
-            .summary = "the active version is not registered",
-            .target = target,
-            .version = version,
-            .hint = std::format(
-                "run `xlings install {}` to restore it, or `xlings use {} "
-                "<other-version>`", target, target),
-        });
-    }
-
-    // ── INV-4: every group resolves ──────────────────────────────────
-    //
-    // One report per group rather than per member: a five-member toolchain
-    // with one missing member is one problem, and printing it five times
-    // buries the rest of the output.
-    std::set<std::tuple<std::string, std::string, std::string>> seenGroups;
-    for (const auto& [target, info] : db) {
-        for (const auto& [version, data] : info.versions) {
-            if (!data.bindingGroup) continue;
-            if (!data.bindingIntegrityIssues.empty()) continue;  // already reported
-            const auto& ref = *data.bindingGroup;
-            if (!seenGroups.emplace(ref.provider, ref.providerVersion,
-                                    ref.group).second) {
-                continue;
-            }
-            auto selection = resolve_binding_selection(db, target, version);
-            if (selection) continue;
-            const auto described = describe(selection.error());
-            findings.push_back({
-                .code = described.code,
-                .summary = std::format("release {}@{} does not resolve: {}",
-                                       ref.provider, ref.providerVersion,
-                                       described.what),
-                .target = described.target,
-                .version = described.version,
-                .hint = described.hint,
-            });
-        }
-    }
-
-    // ── Dangling legacy edges ────────────────────────────────────────
-    //
-    // The INV-4 pass above only looks at entries that carry a
-    // `bindingGroup`. Everything written before 0.4.70 does not, so its
-    // pairwise edges were never checked -- and a pairwise edge pointing at a
-    // version that no longer exists makes the whole release unresolvable.
-    //
-    // This is not hypothetical. On a real installation `gcc@15.1.0` carries
-    // an edge to `xim-gnu-gcc@15.1.0`, an anchor that only exists at 16.1.0,
-    // so `xlings use gcc 15.1.0` -- which worked on 0.4.68 -- is refused with
-    // "a member of this release is registered at no such version". Nothing
-    // reported it and `--fix` could not repair it, leaving reinstall as the
-    // only way out. That is the upgrade being anything but seamless.
-    //
-    // An edge whose destination does not exist carries no information: it
-    // cannot name a member to switch, it can only cause a refusal. Reporting
-    // it separately from INV-4 keeps the remedy separate too -- this one is
-    // repairable without guessing, and INV-4's is not.
-    for (const auto& [target, info] : db) {
-        for (const auto& [peerTarget, edges] : info.bindings) {
-            auto peerIt = db.find(peerTarget);
-            for (const auto& [ownVersion, peerVersion] : edges) {
-                // Two ways an edge can name nothing, and both were treated
-                // very differently for no reason.
-                //
-                // The peer side was reported and repaired. The SOURCE side --
-                // an edge keyed by a version of the owner that is not itself
-                // registered -- was skipped by this loop and by the pruning
-                // plan, so it was invisible AND permanent. It is not
-                // harmless: resolve_binding_selection walks it and fails with
-                // "legacy binding source version is missing", which makes
-                // every future registration of that target refuse. Measured
-                // on a real home, `xim-musl-gnu-gcc` carries five such edges
-                // keyed at `15.1.0-musl` while only `15.1.0` is registered,
-                // and `xlings install musl-gcc@15.1.0` had been failing on it
-                // with no finding anywhere that named the cause.
-                const bool sourceMissing =
-                    !info.versions.contains(ownVersion);
-                const bool peerMissing =
-                    peerIt == db.end()
-                    || !peerIt->second.versions.contains(peerVersion);
-                if (!sourceMissing && !peerMissing) continue;
-                findings.push_back({
-                    .code = "xvm-legacy-edge-dangling",
-                    .summary = sourceMissing
-                        ? std::format(
-                            "a binding edge is keyed at '{}', which is not "
-                            "registered",
-                            display_coordinate(target, ownVersion))
-                        : std::format(
-                            "a binding edge points at '{}', which is not "
-                            "registered",
-                            display_coordinate(peerTarget, peerVersion)),
-                    .target = target,
-                    .version = ownVersion,
-                    .field = std::format("/bindings/{}", peerTarget),
-                    .hint = "run `xlings self doctor --fix` to drop the edge; "
-                            "it names nothing and only blocks switching",
-                });
-            }
-        }
-    }
-
-    // ── Sysroot assets placed before this client tracked them ────────
-    //
-    // Before 2026.7.27.0 a recipe put headers into the sysroot with plain
-    // Lua inside `config()` -- `os.cp`, or `sysroot.install_headers`.
-    // Nothing recorded it, so those files are invisible to the version
-    // database and `xlings use` cannot move them.
-    //
-    // On its own that is not new: such a version could never switch its
-    // headers. What upgrading changes is that it becomes *inconsistent* --
-    // one version of a package now switches its headers and another
-    // silently does not, and the failure surfaces as a build picking up the
-    // wrong header, long after the `use` that reported success.
-    //
-    // Hence the pairing requirement: reported only when another version of
-    // the same target does declare file assets. Without it, every package
-    // that simply ships no headers would be flagged.
-    for (const auto& [target, info] : db) {
-        if (info.versions.size() < 2) continue;
-        std::vector<std::string> untracked;
-        bool anyTracked = false;
-        for (const auto& [version, data] : info.versions) {
-            // Only the entry point users actually switch. Members of a
-            // release resolve to the same set, so checking them too would
-            // report one problem once per library in the toolchain.
-            if (effective_kind(info, data) != "program") continue;
-            if (detail_::release_declares_file_assets_(db, target, version)) {
-                anyTracked = true;
-            } else {
-                untracked.push_back(version);
-            }
-        }
-        if (!anyTracked || untracked.empty()) continue;
-        for (const auto& version : untracked) {
-            findings.push_back({
-                .code = "xvm-sysroot-untracked",
-                .summary = std::format(
-                    "installed before file tracking: sysroot files for {}@{} "
-                    "will not follow a version switch", target, version),
-                .target = target,
-                .version = version,
-                .hint = std::format(
-                    "run `xlings install {}` to re-register them",
-                    display_coordinate(target, version)),
-                .severity = BindingSeverity::Notice,
-            });
-        }
-    }
-
-    // ── INV-2: an active release is active as a whole ────────────────
-    std::set<std::string> reportedIncoherent;
-    for (const auto& [target, version] : workspace) {
-        auto infoIt = db.find(target);
-        if (infoIt == db.end()) continue;
-        auto dataIt = infoIt->second.versions.find(version);
-        if (dataIt == infoIt->second.versions.end()) continue;
-        if (!dataIt->second.bindingGroup) continue;
-        auto selection = resolve_binding_selection(db, target, version);
-        if (!selection) continue;  // reported by INV-4 already
-
-        for (const auto& [memberTarget, memberVersion] : selection->members) {
-            auto activeIt = workspace.find(memberTarget);
-            const bool coherent = activeIt != workspace.end()
-                && activeIt->second == memberVersion;
-            if (coherent) continue;
-
-            if (detail_::held_by_another_provider_(
-                    db, workspace, memberTarget,
-                    dataIt->second.bindingGroup->provider)) {
-                continue;
-            }
-            const auto key = dataIt->second.bindingGroup->provider + "@"
-                + dataIt->second.bindingGroup->providerVersion + "/"
-                + memberTarget;
-            if (!reportedIncoherent.insert(key).second) continue;
-            findings.push_back({
-                .code = "xvm-active-group-incoherent",
-                .summary = std::format(
-                    "'{}' is active at {} but '{}' of the same release is {}",
-                    target, version, memberTarget,
-                    activeIt == workspace.end()
-                        ? std::string("not active")
-                        : std::format("active at {}", activeIt->second)),
-                .target = memberTarget,
-                .version = memberVersion,
-                .hint = std::format(
-                    "run `xlings use {} {}` to bring the whole release back "
-                    "in step", target, version),
-            });
-        }
-    }
-
-    return findings;
-}
+        const Workspace& workspace);
 
 // One other subos's workspace, as the caller read it off disk.
 //
@@ -367,16 +84,7 @@ struct OwnershipVerdict {
 bool subos_claims(const Workspace& active,
                   const WorkspaceInstalled& installed,
                   const std::string& target,
-                  const std::string& version) {
-    if (auto it = active.find(target);
-        it != active.end() && it->second == version) {
-        return true;
-    }
-    if (auto it = installed.find(target); it != installed.end()) {
-        return std::ranges::find(it->second, version) != it->second.end();
-    }
-    return false;
-}
+                  const std::string& version);
 
 // Ownership of a (target, version) across the home.
 //
@@ -390,19 +98,7 @@ OwnershipVerdict subos_ownership(const Workspace& active,
                                  const WorkspaceInstalled& installed,
                                  const std::vector<SubosRef>& others,
                                  const std::string& target,
-                                 const std::string& version) {
-    OwnershipVerdict verdict;
-    verdict.ownedHere = subos_claims(active, installed, target, version);
-    for (const auto& other : others) {
-        if (subos_claims(other.active, other.installed, target, version)) {
-            verdict.otherSubos.push_back(other.subos);
-        }
-    }
-    std::ranges::sort(verdict.otherSubos);
-    auto dup = std::ranges::unique(verdict.otherSubos);
-    verdict.otherSubos.erase(dup.begin(), dup.end());
-    return verdict;
-}
+                                 const std::string& version);
 
 // What the OTHER subos of this home point at that the shared DB no longer has.
 //
@@ -421,57 +117,7 @@ OwnershipVerdict subos_ownership(const Workspace& active,
 // Pure over (db, others): the caller reads the files.
 std::vector<BindingFinding> inspect_subos_references(
         const VersionDB& db,
-        const std::vector<SubosRef>& others) {
-    std::vector<BindingFinding> findings;
-
-    const auto registered = [&](const std::string& target,
-                                const std::string& version) {
-        auto it = db.find(target);
-        return it != db.end() && it->second.versions.contains(version);
-    };
-
-    for (const auto& other : others) {
-        for (const auto& [target, version] : other.active) {
-            if (version.empty() || registered(target, version)) continue;
-            findings.push_back({
-                .code = "xvm-subos-active-missing",
-                .summary = std::format(
-                    "subos '{}' has '{}' active at {}, which is not registered",
-                    other.subos, target, version),
-                .target = target,
-                .version = version,
-                .hint = std::format(
-                    "run `xlings subos use {}` then `xlings install {}` to "
-                    "restore it, or `xlings use {} <other-version>` there",
-                    other.subos, display_coordinate(target, version), target),
-            });
-        }
-        for (const auto& [target, versions] : other.installed) {
-            for (const auto& version : versions) {
-                if (version.empty() || registered(target, version)) continue;
-                // Notice, not Broken: nothing dispatches through installed[],
-                // so this subos still works. It matters because removal counts
-                // references through this set -- a dangling entry keeps a
-                // payload pinned against a version that no longer exists.
-                findings.push_back({
-                    .code = "xvm-subos-installed-dangling",
-                    .summary = std::format(
-                        "subos '{}' lists '{}' as installed, but it is not "
-                        "registered", other.subos,
-                        display_coordinate(target, version)),
-                    .target = target,
-                    .version = version,
-                    .hint = std::format(
-                        "run `xlings subos use {}` then `xlings remove {}` "
-                        "to drop the stale entry", other.subos,
-                        display_coordinate(target, version)),
-                    .severity = BindingSeverity::Notice,
-                });
-            }
-        }
-    }
-    return findings;
-}
+        const std::vector<SubosRef>& others);
 
 // One entry found in the subos, as the caller read it off disk.
 struct SysrootEntry {
@@ -502,59 +148,7 @@ std::vector<BindingFinding> inspect_sysroot_ownership(
         const VersionDB& db,
         const Workspace& workspace,
         const std::vector<SysrootEntry>& entries,
-        std::string_view payloadRoot) {
-    std::vector<BindingFinding> findings;
-    if (payloadRoot.empty()) return findings;
-
-    // Destinations the active selection says should be ours.
-    std::map<std::string, std::pair<std::string, std::string>> claimed;
-    for (const auto& [target, version] : workspace) {
-        auto infoIt = db.find(target);
-        if (infoIt == db.end()) continue;
-        auto dataIt = infoIt->second.versions.find(version);
-        if (dataIt == infoIt->second.versions.end()) continue;
-        if (!dataIt->second.fileDst.empty()) {
-            claimed.emplace(dataIt->second.fileDst,
-                            std::pair{target, version});
-        }
-    }
-
-    for (const auto& entry : entries) {
-        const bool ours = !entry.linkTarget.empty()
-            && std::string_view{entry.linkTarget}.starts_with(payloadRoot);
-        if (ours) continue;
-
-        if (auto it = claimed.find(entry.path); it != claimed.end()) {
-            // Declared, but what is on disk is not the link we would have
-            // made. Something replaced it after the fact.
-            findings.push_back({
-                .code = "xvm-sysroot-drift",
-                .summary = std::format(
-                    "'{}' is declared by {}@{} but is not the link xlings "
-                    "placed", entry.path, it->second.first,
-                    it->second.second),
-                .target = it->second.first,
-                .version = it->second.second,
-                .hint = std::format(
-                    "run `xlings use {} {}` to put it back",
-                    it->second.first, it->second.second),
-            });
-            continue;
-        }
-
-        // Nothing claims it. Could be the host image, could be a package
-        // that placed it by hand and is now gone -- either way xlings will
-        // not move it on a version switch, and cannot remove it.
-        findings.push_back({
-            .code = "xvm-sysroot-unmanaged",
-            .summary = std::format(
-                "'{}' is in the subos but no package declares it", entry.path),
-            .hint = "left as-is; xlings only moves what a package declares",
-            .severity = BindingSeverity::Notice,
-        });
-    }
-    return findings;
-}
+        std::string_view payloadRoot);
 
 // What another subos's state file has to lose to stop pointing at nothing.
 //
@@ -581,14 +175,8 @@ struct SubosMetadataRepair {
     };
     std::vector<Entry> entries;
 
-    [[nodiscard]] bool empty() const { return entries.empty(); }
-    [[nodiscard]] std::size_t size() const {
-        std::size_t n = 0;
-        for (const auto& e : entries) {
-            n += e.deactivate.size() + e.dropInstalled.size();
-        }
-        return n;
-    }
+    [[nodiscard]] bool empty() const;
+    [[nodiscard]] std::size_t size() const;
 };
 
 // Pure: returns the plan, applies nothing. Mirrors inspect_subos_references
@@ -596,51 +184,13 @@ struct SubosMetadataRepair {
 // reported.
 SubosMetadataRepair plan_subos_metadata_repair(
         const VersionDB& db,
-        const std::vector<SubosRef>& others) {
-    const auto registered = [&](const std::string& target,
-                                const std::string& version) {
-        auto it = db.find(target);
-        return it != db.end() && it->second.versions.contains(version);
-    };
-
-    SubosMetadataRepair plan;
-    for (const auto& other : others) {
-        SubosMetadataRepair::Entry entry{.subos = other.subos};
-        for (const auto& [target, version] : other.active) {
-            if (version.empty() || registered(target, version)) continue;
-            entry.deactivate.push_back(target);
-        }
-        for (const auto& [target, versions] : other.installed) {
-            for (const auto& version : versions) {
-                if (version.empty() || registered(target, version)) continue;
-                entry.dropInstalled.emplace_back(target, version);
-            }
-        }
-        if (entry.deactivate.empty() && entry.dropInstalled.empty()) continue;
-        plan.entries.push_back(std::move(entry));
-    }
-    return plan;
-}
+        const std::vector<SubosRef>& others);
 
 // Apply one subos's share of the plan to its own workspace maps.
 // Returns how many references were dropped.
 std::size_t apply_subos_metadata_repair(
         SubosWorkspace& workspace,
-        const SubosMetadataRepair::Entry& entry) {
-    std::size_t dropped = 0;
-    for (const auto& target : entry.deactivate) {
-        dropped += workspace.active.erase(target);
-    }
-    for (const auto& [target, version] : entry.dropInstalled) {
-        auto it = workspace.installed.find(target);
-        if (it == workspace.installed.end()) continue;
-        const auto before = it->second.size();
-        std::erase(it->second, version);
-        dropped += before - it->second.size();
-        if (it->second.empty()) workspace.installed.erase(it);
-    }
-    return dropped;
-}
+        const SubosMetadataRepair::Entry& entry);
 
 // Targets whose ACTIVE version this subos no longer has registered.
 //
@@ -650,16 +200,7 @@ std::size_t apply_subos_metadata_repair(
 // choosing for the user.
 std::vector<std::string> plan_unregistered_active_deactivation(
         const VersionDB& db,
-        const Workspace& workspace) {
-    std::vector<std::string> targets;
-    for (const auto& [target, version] : workspace) {
-        if (version.empty()) continue;
-        auto it = db.find(target);
-        if (it != db.end() && it->second.versions.contains(version)) continue;
-        targets.push_back(target);
-    }
-    return targets;
-}
+        const Workspace& workspace);
 
 struct DeactivationPlan {
     // Targets to drop from the active workspace, and the release each
@@ -679,51 +220,7 @@ struct DeactivationPlan {
 //
 // Pure: returns the plan, applies nothing.
 DeactivationPlan plan_incoherent_deactivation(const VersionDB& db,
-                                              const Workspace& workspace) {
-    DeactivationPlan plan;
-    for (const auto& [target, version] : workspace) {
-        auto infoIt = db.find(target);
-        if (infoIt == db.end()) continue;
-        auto dataIt = infoIt->second.versions.find(version);
-        if (dataIt == infoIt->second.versions.end()) continue;
-        if (!dataIt->second.bindingGroup) continue;
-        auto selection = resolve_binding_selection(db, target, version);
-        if (!selection) continue;  // unresolvable is a different problem
-
-        const auto& ref = *dataIt->second.bindingGroup;
-
-        // Exactly the predicate INV-2 reports with. A member whose name is
-        // held by another provider is not this release breaking step, so it
-        // must not put this release on the teardown list either -- which it
-        // did until 2026.8.1.2, making `--fix` demolish releases `self doctor`
-        // had just called healthy.
-        const bool coherent = std::ranges::all_of(
-            selection->members, [&](const auto& member) {
-                auto activeIt = workspace.find(member.first);
-                if (activeIt != workspace.end()
-                    && activeIt->second == member.second) {
-                    return true;
-                }
-                return detail_::held_by_another_provider_(
-                    db, workspace, member.first, ref.provider);
-            });
-        if (coherent) continue;
-
-        const auto label =
-            std::format("{}@{}", ref.provider, ref.providerVersion);
-        // Take down every member of this release that is active, not just
-        // the entry point: leaving the rest behind would swap one
-        // incoherent state for another.
-        for (const auto& [memberTarget, memberVersion] : selection->members) {
-            auto activeIt = workspace.find(memberTarget);
-            if (activeIt == workspace.end()) continue;
-            if (activeIt->second != memberVersion) continue;
-            plan.targets.emplace(memberTarget, label);
-        }
-        plan.targets.emplace(target, label);
-    }
-    return plan;
-}
+                                              const Workspace& workspace);
 
 // Entries whose binding metadata cannot be read, and would be discarded.
 struct MetadataReset {
@@ -736,7 +233,7 @@ struct MetadataReset {
     };
     std::vector<Entry> entries;
 
-    [[nodiscard]] bool empty() const { return entries.empty(); }
+    [[nodiscard]] bool empty() const;
 };
 
 // Collect every entry carrying unreadable binding metadata.
@@ -752,46 +249,10 @@ struct MetadataReset {
 // indistinguishable from the silent rewrite that destroyed it.
 //
 // Pure: returns the plan, applies nothing.
-MetadataReset plan_metadata_reset(const VersionDB& db) {
-    MetadataReset plan;
-    for (const auto& [target, info] : db) {
-        for (const auto& [version, data] : info.versions) {
-            if (data.bindingIntegrityIssues.empty()) continue;
-            MetadataReset::Entry entry{.target = target, .version = version};
-            for (const auto& issue : data.bindingIntegrityIssues) {
-                entry.codes.push_back(issue.code);
-            }
-            plan.entries.push_back(std::move(entry));
-        }
-    }
-    return plan;
-}
+MetadataReset plan_metadata_reset(const VersionDB& db);
 
 // Apply the reset. Returns how many entries were cleared.
-std::size_t apply_metadata_reset(VersionDB& db, const MetadataReset& plan) {
-    std::size_t cleared = 0;
-    for (const auto& entry : plan.entries) {
-        auto infoIt = db.find(entry.target);
-        if (infoIt == db.end()) continue;
-        auto dataIt = infoIt->second.versions.find(entry.version);
-        if (dataIt == infoIt->second.versions.end()) continue;
-        auto& data = dataIt->second;
-        if (data.bindingIntegrityIssues.empty()) continue;
-
-        // Everything that describes the release, including the preserved
-        // originals -- leaving those behind would resurrect the corruption
-        // on the next save, which is the one outcome a reset must not have.
-        data.bindingGroup.reset();
-        data.bindingMembers.clear();
-        data.bindingHeaders.clear();
-        data.bindingMembersDeclared = false;
-        data.bindingHeadersDeclared = false;
-        data.bindingIntegrityIssues.clear();
-        data.bindingUnreadable.clear();
-        ++cleared;
-    }
-    return cleared;
-}
+std::size_t apply_metadata_reset(VersionDB& db, const MetadataReset& plan);
 
 // Edges to drop: (owner target, owner version, peer target, peer version).
 struct DanglingEdgePruning {
@@ -803,7 +264,7 @@ struct DanglingEdgePruning {
     };
     std::vector<Edge> edges;
 
-    [[nodiscard]] bool empty() const { return edges.empty(); }
+    [[nodiscard]] bool empty() const;
 };
 
 // Collect every pairwise binding edge whose destination is not registered.
@@ -814,49 +275,10 @@ struct DanglingEdgePruning {
 // makes `resolve_binding_selection` refuse the release.
 //
 // Pure: returns the plan, applies nothing.
-DanglingEdgePruning plan_dangling_edge_pruning(const VersionDB& db) {
-    DanglingEdgePruning plan;
-    for (const auto& [target, info] : db) {
-        for (const auto& [peerTarget, edges] : info.bindings) {
-            auto peerIt = db.find(peerTarget);
-            for (const auto& [ownVersion, peerVersion] : edges) {
-                // Source side as well as peer side -- see the matching note in
-                // inspect_binding_state. Skipping the source side left an edge
-                // that no command could remove and that made every
-                // registration of its owner refuse.
-                const bool sourceMissing =
-                    !info.versions.contains(ownVersion);
-                const bool peerMissing =
-                    peerIt == db.end()
-                    || !peerIt->second.versions.contains(peerVersion);
-                if (!sourceMissing && !peerMissing) continue;
-                plan.edges.push_back({target, ownVersion,
-                                      peerTarget, peerVersion});
-            }
-        }
-    }
-    return plan;
-}
+DanglingEdgePruning plan_dangling_edge_pruning(const VersionDB& db);
 
 // Apply the pruning. Returns how many edges were dropped.
 std::size_t apply_dangling_edge_pruning(VersionDB& db,
-                                        const DanglingEdgePruning& plan) {
-    std::size_t dropped = 0;
-    for (const auto& edge : plan.edges) {
-        auto infoIt = db.find(edge.target);
-        if (infoIt == db.end()) continue;
-        auto peerIt = infoIt->second.bindings.find(edge.peerTarget);
-        if (peerIt == infoIt->second.bindings.end()) continue;
-        auto versionIt = peerIt->second.find(edge.version);
-        if (versionIt == peerIt->second.end()) continue;
-        if (versionIt->second != edge.peerVersion) continue;
-        peerIt->second.erase(versionIt);
-        ++dropped;
-        if (peerIt->second.empty()) {
-            infoIt->second.bindings.erase(peerIt);
-        }
-    }
-    return dropped;
-}
+                                        const DanglingEdgePruning& plan);
 
 }  // namespace xlings::xvm
diff --git a/src/core/xvm/lock.cpp b/src/core/xvm/lock.cpp
new file mode 100644
index 00000000..8339c63a
--- /dev/null
+++ b/src/core/xvm/lock.cpp
@@ -0,0 +1,110 @@
+module xlings.core.xvm.lock;
+
+import std;
+import xlings.platform;
+import xlings.core.log;
+import xlings.core.utils;
+
+namespace xlings::xvm {
+
+std::string lock_scope_key(const std::filesystem::path& home) {
+    std::error_code ec;
+    auto canonical = std::filesystem::weakly_canonical(home, ec);
+    return (ec ? home : canonical).string();
+}
+
+std::filesystem::path state_lock_path(const std::filesystem::path& home) {
+    return home / ".xlings.lock";
+}
+
+std::expected<StateLock, std::string> acquire_state_lock(const std::filesystem::path& home, std::chrono::milliseconds timeout) {
+    StateLock lock;
+
+    if (utils::get_env_or_default(std::string(no_lock_env())) == "1") {
+        log::warn(
+            "{}=1 — running without the state lock; a concurrent xlings can "
+            "silently discard this command's changes",
+            no_lock_env());
+        lock.bypassed_ = true;
+        lock.held_ = true;
+        return lock;
+    }
+
+    const auto scope = lock_scope_key(home);
+    const auto marker = utils::get_env_or_default(std::string(reentry_env()));
+    if (!marker.empty() && marker == scope) {
+        // An ancestor already holds this home. Waiting would deadlock: the
+        // holder cannot finish until this child does.
+        lock.inherited_ = true;
+        lock.held_ = true;
+        return lock;
+    }
+
+    std::error_code ec;
+    std::filesystem::create_directories(home, ec);
+
+    const auto path = state_lock_path(home);
+    std::string error;
+    if (!lock.lock_.acquire(path, timeout, {}, error)) {
+        return std::unexpected(std::format(
+            "another xlings process is changing this installation; waited "
+            "{}s. Wait for it to finish, or set {}=1 to proceed anyway "
+            "(which can discard one of the two commands' changes)",
+            std::chrono::duration_cast<std::chrono::seconds>(timeout).count(),
+            no_lock_env()));
+    }
+
+    // Children spawned from here on inherit this and skip locking -- but
+    // only for this home.
+    lock.previousMarker_ = marker;
+    platform::set_env_variable(std::string(reentry_env()), scope);
+    lock.ownsMarker_ = true;
+    lock.held_ = true;
+    return lock;
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::xvm {
+
+StateLock::StateLock(StateLock&& other) noexcept : lock_(std::move(other.lock_)),
+      held_(std::exchange(other.held_, false)),
+      bypassed_(std::exchange(other.bypassed_, false)),
+      inherited_(std::exchange(other.inherited_, false)),
+      ownsMarker_(std::exchange(other.ownsMarker_, false)),
+      previousMarker_(std::move(other.previousMarker_)) {}
+
+StateLock& StateLock::operator=(StateLock&& other) noexcept {
+    if (this != &other) {
+        clear_marker_();
+        lock_ = std::move(other.lock_);
+        held_ = std::exchange(other.held_, false);
+        bypassed_ = std::exchange(other.bypassed_, false);
+        inherited_ = std::exchange(other.inherited_, false);
+        ownsMarker_ = std::exchange(other.ownsMarker_, false);
+        previousMarker_ = std::move(other.previousMarker_);
+    }
+    return *this;
+}
+
+StateLock::~StateLock() { clear_marker_(); }
+
+[[nodiscard]] bool StateLock::held() const { return held_; }
+
+[[nodiscard]] bool StateLock::bypassed() const { return bypassed_; }
+
+[[nodiscard]] bool StateLock::inherited() const { return inherited_; }
+
+void StateLock::clear_marker_() {
+    if (!ownsMarker_) return;
+    // Restore whatever was there rather than clearing outright: locking
+    // a second home while holding the first must not erase the first
+    // one's marker, or a later child would try to re-lock it and hang.
+    platform::set_env_variable(std::string(reentry_env()), previousMarker_);
+    ownsMarker_ = false;
+}
+
+} // namespace xlings::xvm
diff --git a/src/core/xvm/lock.cppm b/src/core/xvm/lock.cppm
index f3c8c149..674e8e09 100644
--- a/src/core/xvm/lock.cppm
+++ b/src/core/xvm/lock.cppm
@@ -3,8 +3,6 @@ export module xlings.core.xvm.lock;
 import std;
 
 import xlings.platform;
-import xlings.core.log;
-import xlings.core.utils;
 
 // Serialize the commands that mutate xlings state.
 //
@@ -47,66 +45,36 @@ constexpr std::string_view no_lock_env() { return "XLINGS_NO_LOCK"; }
 // reintroducing the lost update this exists to prevent.
 constexpr std::string_view reentry_env() { return "XLINGS_STATE_LOCK_HELD"; }
 
-std::string lock_scope_key(const std::filesystem::path& home) {
-    std::error_code ec;
-    auto canonical = std::filesystem::weakly_canonical(home, ec);
-    return (ec ? home : canonical).string();
-}
+std::string lock_scope_key(const std::filesystem::path& home);
 
 constexpr std::chrono::milliseconds default_lock_timeout() {
     return std::chrono::seconds{30};
 }
 
-std::filesystem::path state_lock_path(const std::filesystem::path& home) {
-    return home / ".xlings.lock";
-}
+std::filesystem::path state_lock_path(const std::filesystem::path& home);
 
 class StateLock {
 public:
     StateLock() = default;
     StateLock(const StateLock&) = delete;
     StateLock& operator=(const StateLock&) = delete;
-    StateLock(StateLock&& other) noexcept
-        : lock_(std::move(other.lock_)),
-          held_(std::exchange(other.held_, false)),
-          bypassed_(std::exchange(other.bypassed_, false)),
-          inherited_(std::exchange(other.inherited_, false)),
-          ownsMarker_(std::exchange(other.ownsMarker_, false)),
-          previousMarker_(std::move(other.previousMarker_)) {}
-    StateLock& operator=(StateLock&& other) noexcept {
-        if (this != &other) {
-            clear_marker_();
-            lock_ = std::move(other.lock_);
-            held_ = std::exchange(other.held_, false);
-            bypassed_ = std::exchange(other.bypassed_, false);
-            inherited_ = std::exchange(other.inherited_, false);
-            ownsMarker_ = std::exchange(other.ownsMarker_, false);
-            previousMarker_ = std::move(other.previousMarker_);
-        }
-        return *this;
-    }
-    ~StateLock() { clear_marker_(); }
+    StateLock(StateLock&& other) noexcept;
+    StateLock& operator=(StateLock&& other) noexcept;
+    ~StateLock();
 
     // True when the command may proceed. Also true for the bypass and for a
     // lock inherited from an ancestor, so callers cannot accidentally treat
     // either as a failure.
-    [[nodiscard]] bool held() const { return held_; }
-    [[nodiscard]] bool bypassed() const { return bypassed_; }
+    [[nodiscard]] bool held() const;
+    [[nodiscard]] bool bypassed() const;
     // Covered by an ancestor's lock rather than holding one of its own.
-    [[nodiscard]] bool inherited() const { return inherited_; }
+    [[nodiscard]] bool inherited() const;
 
 private:
     friend std::expected<StateLock, std::string> acquire_state_lock(
         const std::filesystem::path&, std::chrono::milliseconds);
 
-    void clear_marker_() {
-        if (!ownsMarker_) return;
-        // Restore whatever was there rather than clearing outright: locking
-        // a second home while holding the first must not erase the first
-        // one's marker, or a later child would try to re-lock it and hang.
-        platform::set_env_variable(std::string(reentry_env()), previousMarker_);
-        ownsMarker_ = false;
-    }
+    void clear_marker_();
 
     platform::FileLock lock_;
     bool held_ { false };
@@ -131,50 +99,6 @@ private:
 // exists only as something to flock.
 std::expected<StateLock, std::string> acquire_state_lock(
         const std::filesystem::path& home,
-        std::chrono::milliseconds timeout = default_lock_timeout()) {
-    StateLock lock;
-
-    if (utils::get_env_or_default(std::string(no_lock_env())) == "1") {
-        log::warn(
-            "{}=1 — running without the state lock; a concurrent xlings can "
-            "silently discard this command's changes",
-            no_lock_env());
-        lock.bypassed_ = true;
-        lock.held_ = true;
-        return lock;
-    }
-
-    const auto scope = lock_scope_key(home);
-    const auto marker = utils::get_env_or_default(std::string(reentry_env()));
-    if (!marker.empty() && marker == scope) {
-        // An ancestor already holds this home. Waiting would deadlock: the
-        // holder cannot finish until this child does.
-        lock.inherited_ = true;
-        lock.held_ = true;
-        return lock;
-    }
-
-    std::error_code ec;
-    std::filesystem::create_directories(home, ec);
-
-    const auto path = state_lock_path(home);
-    std::string error;
-    if (!lock.lock_.acquire(path, timeout, {}, error)) {
-        return std::unexpected(std::format(
-            "another xlings process is changing this installation; waited "
-            "{}s. Wait for it to finish, or set {}=1 to proceed anyway "
-            "(which can discard one of the two commands' changes)",
-            std::chrono::duration_cast<std::chrono::seconds>(timeout).count(),
-            no_lock_env()));
-    }
-
-    // Children spawned from here on inherit this and skip locking -- but
-    // only for this home.
-    lock.previousMarker_ = marker;
-    platform::set_env_variable(std::string(reentry_env()), scope);
-    lock.ownsMarker_ = true;
-    lock.held_ = true;
-    return lock;
-}
+        std::chrono::milliseconds timeout = default_lock_timeout());
 
 }  // namespace xlings::xvm
diff --git a/src/core/xvm/owner.cpp b/src/core/xvm/owner.cpp
new file mode 100644
index 00000000..8aab3255
--- /dev/null
+++ b/src/core/xvm/owner.cpp
@@ -0,0 +1,138 @@
+module xlings.core.xvm.owner;
+
+import std;
+import xlings.core.xvm.types;
+import xlings.core.xvm.db;
+import xlings.core.xvm.bindings;
+
+namespace xlings::xvm {
+
+std::optional<InstallCoordinate>
+coordinate_from_payload_path(std::string_view payloadPath) {
+    if (payloadPath.empty()) return std::nullopt;
+    std::string path{payloadPath};
+    std::ranges::replace(path, '\\', '/');
+
+    std::vector<std::string> parts;
+    for (const auto piece : std::views::split(path, '/')) {
+        std::string component{piece.begin(), piece.end()};
+        if (!component.empty()) parts.push_back(std::move(component));
+    }
+
+    // Find the LAST `xpkgs` component: a home may itself live under a path
+    // containing that word, and the store is always the innermost one.
+    std::size_t storeIndex = parts.size();
+    for (std::size_t i = parts.size(); i-- > 0;) {
+        if (parts[i] == "xpkgs") { storeIndex = i; break; }
+    }
+    if (storeIndex == parts.size()) return std::nullopt;
+    // `<store>/<version>` must both follow it; anything deeper is a bindir.
+    if (parts.size() < storeIndex + 3) return std::nullopt;
+
+    const auto& store   = parts[storeIndex + 1];
+    const auto& version = parts[storeIndex + 2];
+    if (store.empty() || version.empty()) return std::nullopt;
+
+    InstallCoordinate coord;
+    coord.version = version;
+    if (const auto sep = store.find("-x-"); sep != std::string::npos) {
+        coord.ns      = store.substr(0, sep);
+        coord.package = store.substr(sep + 3);
+    } else {
+        coord.package = store;
+    }
+    if (coord.package.empty()) return std::nullopt;
+    return coord;
+}
+
+std::vector<InstallCoordinate>
+owner_candidates(const VersionDB& db,
+                 const std::string& target,
+                 const std::string& version) {
+    std::vector<InstallCoordinate> candidates;
+    const auto push = [&](InstallCoordinate coord) {
+        if (coord.empty() || coord.version.empty()) return;
+        if (std::ranges::find(candidates, coord) != candidates.end()) return;
+        candidates.push_back(std::move(coord));
+    };
+    // A target/version pair as stored becomes a coordinate by moving the
+    // namespace from the version onto the front.
+    const auto from_entry = [](const std::string& name,
+                               const std::string& versionKey) {
+        const auto [ns, bare] = parse_ns_version(versionKey);
+        return InstallCoordinate{.ns = ns, .package = name, .version = bare};
+    };
+
+    const VData* data = nullptr;
+    if (const auto infoIt = db.find(target); infoIt != db.end()) {
+        if (const auto dataIt = infoIt->second.versions.find(version);
+            dataIt != infoIt->second.versions.end()) {
+            data = &dataIt->second;
+        }
+    }
+
+    if (data && data->bindingGroup) {
+        // `provider` is stored canonically ("xim:llvm"), so it already carries
+        // its namespace and must not be given a second one.
+        const auto& group = *data->bindingGroup;
+        const auto colon = group.provider.find(':');
+        InstallCoordinate coord;
+        if (colon == std::string::npos) {
+            coord.package = group.provider;
+        } else {
+            coord.ns      = group.provider.substr(0, colon);
+            coord.package = group.provider.substr(colon + 1);
+        }
+        coord.version = strip_namespace(group.providerVersion);
+        push(std::move(coord));
+    }
+
+    if (data) {
+        if (auto fromPath = coordinate_from_payload_path(data->path)) {
+            push(std::move(*fromPath));
+        }
+    }
+
+    push(from_entry(target, version));
+
+    if (auto selection = resolve_binding_selection(db, target, version)) {
+        for (const auto& [memberTarget, memberVersion] : selection->members) {
+            if (memberTarget == target) continue;
+            if (!is_binding_root(db, memberTarget, memberVersion)) continue;
+            push(from_entry(memberTarget, memberVersion));
+            if (const auto memberInfoIt = db.find(memberTarget);
+                memberInfoIt != db.end()) {
+                const auto memberDataIt =
+                    memberInfoIt->second.versions.find(memberVersion);
+                if (memberDataIt != memberInfoIt->second.versions.end()) {
+                    if (auto fromPath = coordinate_from_payload_path(
+                            memberDataIt->second.path)) {
+                        push(std::move(*fromPath));
+                    }
+                }
+            }
+        }
+    }
+
+    return candidates;
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::xvm {
+
+[[nodiscard]] bool InstallCoordinate::empty() const { return package.empty(); }
+
+[[nodiscard]] std::string InstallCoordinate::canonical() const {
+    if (ns.empty()) return std::format("{}@{}", package, version);
+    return std::format("{}:{}@{}", ns, package, version);
+}
+
+[[nodiscard]] std::string InstallCoordinate::install_command() const {
+    return std::format("xlings install {}", canonical());
+}
+
+} // namespace xlings::xvm
diff --git a/src/core/xvm/owner.cppm b/src/core/xvm/owner.cppm
index aaa40281..1efec4dc 100644
--- a/src/core/xvm/owner.cppm
+++ b/src/core/xvm/owner.cppm
@@ -33,16 +33,11 @@ struct InstallCoordinate {
     std::string package;   // the PACKAGE name, not the xvm target
     std::string version;   // bare version, never carries the namespace
 
-    [[nodiscard]] bool empty() const { return package.empty(); }
+    [[nodiscard]] bool empty() const;
 
-    [[nodiscard]] std::string canonical() const {
-        if (ns.empty()) return std::format("{}@{}", package, version);
-        return std::format("{}:{}@{}", ns, package, version);
-    }
+    [[nodiscard]] std::string canonical() const;
 
-    [[nodiscard]] std::string install_command() const {
-        return std::format("xlings install {}", canonical());
-    }
+    [[nodiscard]] std::string install_command() const;
 
     friend bool operator==(const InstallCoordinate&,
                            const InstallCoordinate&) = default;
@@ -67,42 +62,7 @@ struct InstallCoordinate {
 // Linux carries backslashes, and that record is exactly the one nothing else
 // can identify.
 std::optional<InstallCoordinate>
-coordinate_from_payload_path(std::string_view payloadPath) {
-    if (payloadPath.empty()) return std::nullopt;
-    std::string path{payloadPath};
-    std::ranges::replace(path, '\\', '/');
-
-    std::vector<std::string> parts;
-    for (const auto piece : std::views::split(path, '/')) {
-        std::string component{piece.begin(), piece.end()};
-        if (!component.empty()) parts.push_back(std::move(component));
-    }
-
-    // Find the LAST `xpkgs` component: a home may itself live under a path
-    // containing that word, and the store is always the innermost one.
-    std::size_t storeIndex = parts.size();
-    for (std::size_t i = parts.size(); i-- > 0;) {
-        if (parts[i] == "xpkgs") { storeIndex = i; break; }
-    }
-    if (storeIndex == parts.size()) return std::nullopt;
-    // `<store>/<version>` must both follow it; anything deeper is a bindir.
-    if (parts.size() < storeIndex + 3) return std::nullopt;
-
-    const auto& store   = parts[storeIndex + 1];
-    const auto& version = parts[storeIndex + 2];
-    if (store.empty() || version.empty()) return std::nullopt;
-
-    InstallCoordinate coord;
-    coord.version = version;
-    if (const auto sep = store.find("-x-"); sep != std::string::npos) {
-        coord.ns      = store.substr(0, sep);
-        coord.package = store.substr(sep + 3);
-    } else {
-        coord.package = store;
-    }
-    if (coord.package.empty()) return std::nullopt;
-    return coord;
-}
+coordinate_from_payload_path(std::string_view payloadPath);
 
 // Candidate owners for a (target, version), most trustworthy first.
 //
@@ -122,73 +82,6 @@ coordinate_from_payload_path(std::string_view payloadPath) {
 std::vector<InstallCoordinate>
 owner_candidates(const VersionDB& db,
                  const std::string& target,
-                 const std::string& version) {
-    std::vector<InstallCoordinate> candidates;
-    const auto push = [&](InstallCoordinate coord) {
-        if (coord.empty() || coord.version.empty()) return;
-        if (std::ranges::find(candidates, coord) != candidates.end()) return;
-        candidates.push_back(std::move(coord));
-    };
-    // A target/version pair as stored becomes a coordinate by moving the
-    // namespace from the version onto the front.
-    const auto from_entry = [](const std::string& name,
-                               const std::string& versionKey) {
-        const auto [ns, bare] = parse_ns_version(versionKey);
-        return InstallCoordinate{.ns = ns, .package = name, .version = bare};
-    };
-
-    const VData* data = nullptr;
-    if (const auto infoIt = db.find(target); infoIt != db.end()) {
-        if (const auto dataIt = infoIt->second.versions.find(version);
-            dataIt != infoIt->second.versions.end()) {
-            data = &dataIt->second;
-        }
-    }
-
-    if (data && data->bindingGroup) {
-        // `provider` is stored canonically ("xim:llvm"), so it already carries
-        // its namespace and must not be given a second one.
-        const auto& group = *data->bindingGroup;
-        const auto colon = group.provider.find(':');
-        InstallCoordinate coord;
-        if (colon == std::string::npos) {
-            coord.package = group.provider;
-        } else {
-            coord.ns      = group.provider.substr(0, colon);
-            coord.package = group.provider.substr(colon + 1);
-        }
-        coord.version = strip_namespace(group.providerVersion);
-        push(std::move(coord));
-    }
-
-    if (data) {
-        if (auto fromPath = coordinate_from_payload_path(data->path)) {
-            push(std::move(*fromPath));
-        }
-    }
-
-    push(from_entry(target, version));
-
-    if (auto selection = resolve_binding_selection(db, target, version)) {
-        for (const auto& [memberTarget, memberVersion] : selection->members) {
-            if (memberTarget == target) continue;
-            if (!is_binding_root(db, memberTarget, memberVersion)) continue;
-            push(from_entry(memberTarget, memberVersion));
-            if (const auto memberInfoIt = db.find(memberTarget);
-                memberInfoIt != db.end()) {
-                const auto memberDataIt =
-                    memberInfoIt->second.versions.find(memberVersion);
-                if (memberDataIt != memberInfoIt->second.versions.end()) {
-                    if (auto fromPath = coordinate_from_payload_path(
-                            memberDataIt->second.path)) {
-                        push(std::move(*fromPath));
-                    }
-                }
-            }
-        }
-    }
-
-    return candidates;
-}
+                 const std::string& version);
 
 }  // namespace xlings::xvm
diff --git a/src/core/xvm/registration.cpp b/src/core/xvm/registration.cpp
new file mode 100644
index 00000000..8f8a7172
--- /dev/null
+++ b/src/core/xvm/registration.cpp
@@ -0,0 +1,1002 @@
+module xlings.core.xvm.registration;
+
+import std;
+import xlings.core.xvm.types;
+import xlings.core.xvm.bindings;
+
+namespace xlings::xvm::detail_ {
+
+RegistrationError registration_error_(
+    RegistrationErrorKind kind,
+    std::string path,
+    std::string target,
+    std::string version,
+    std::string message) {
+    return {
+        .kind = kind,
+        .path = std::move(path),
+        .target = std::move(target),
+        .version = std::move(version),
+        .message = std::move(message),
+    };
+}
+
+bool same_registration_group_(
+    const BindingGroupRef& lhs,
+    const BindingGroupRef& rhs) {
+    return lhs.provider == rhs.provider
+        && lhs.providerVersion == rhs.providerVersion
+        && lhs.group == rhs.group
+        && lhs.rootTarget == rhs.rootTarget
+        && lhs.rootVersion == rhs.rootVersion;
+}
+
+RegistrationGroupIdentity registration_group_identity_(
+    const BindingGroupRef& group) {
+    return {
+        group.provider,
+        group.providerVersion,
+        group.group,
+        group.rootTarget,
+        group.rootVersion,
+    };
+}
+
+// Moved to xvm.types so the switch planner reads them identically -- see the
+// comment there. Kept as thin aliases so this file's call sites stay legible.
+std::string effective_kind_(
+    const VInfo& info,
+    const VData& data) {
+    return effective_kind(info, data);
+}
+
+std::string effective_source_name_(
+    const std::string& target,
+    const VInfo& info,
+    const VData& data,
+    std::string_view kind) {
+    return effective_source_name(target, info, data, kind);
+}
+
+std::string effective_destination_name_(
+    const std::string& target,
+    const VData& data,
+    std::string_view kind,
+    std::string_view sourceName) {
+    return effective_destination_name(target, data, kind, sourceName);
+}
+
+std::optional<std::string> legacy_payload_mismatch_(
+    const RegistrationNode& node,
+    const VInfo& info,
+    const VData& data) {
+    const auto kind = effective_kind_(info, data);
+    const auto sourceName = effective_source_name_(
+        node.target, info, data, kind);
+    const auto destinationName = effective_destination_name_(
+        node.target, data, kind, sourceName);
+    const auto namesAnArtifact =
+        node.kind != "group" && node.kind != "files";
+    const auto expectedSourceName = namesAnArtifact
+        ? std::string_view{node.sourceName}
+        : std::string_view{};
+    const auto expectedDestinationName = namesAnArtifact
+        ? std::string_view{node.destinationName}
+        : std::string_view{};
+    if (data.path != node.path) return "path";
+    if (kind != node.kind) return "kind";
+    if (sourceName != expectedSourceName) return "sourceName";
+    if (destinationName != expectedDestinationName) {
+        return "destinationName";
+    }
+    if (data.alias != node.alias) return "alias";
+    if (data.envs != node.envs) return "envs";
+    return std::nullopt;
+}
+
+std::string registration_path_token_(std::string_view token) {
+    std::string escaped;
+    escaped.reserve(token.size());
+    for (const auto ch : token) {
+        if (ch == '~') {
+            escaped += "~0";
+        } else if (ch == '/') {
+            escaped += "~1";
+        } else {
+            escaped += ch;
+        }
+    }
+    return escaped;
+}
+
+// Path comparison that survives a record written on another platform.
+//
+// Not a filesystem question: `db` holds whatever string the client that wrote
+// it produced, and a home carried over from Windows holds
+// `C:\…` / `/home/you/.xlings\data\xpkgs\…` on a machine where those separators
+// mean nothing. Normalising to '/' is what lets a Linux client recognise the
+// record as its own.
+std::string normalized_payload_path_(std::string_view path) {
+    std::string out{path};
+    std::ranges::replace(out, '\\', '/');
+    while (out.size() > 1 && out.back() == '/') out.pop_back();
+    return out;
+}
+
+// Is `candidate` the same payload as `root`, or something inside it?
+bool payload_path_covers_(std::string_view root, std::string_view candidate) {
+    if (root.empty() || candidate.empty()) return false;
+    if (candidate == root) return true;
+    return candidate.size() > root.size()
+        && candidate.starts_with(root)
+        && candidate[root.size()] == '/';
+}
+
+void erase_exact_registration_edges_(
+    VersionDB& db,
+    const std::set<RegistrationExactKey>& exactNodes) {
+    for (auto& [sourceTarget, info] : db) {
+        for (auto bindingIt = info.bindings.begin();
+             bindingIt != info.bindings.end();) {
+            const auto& peerTarget = bindingIt->first;
+            std::erase_if(
+                bindingIt->second,
+                [&](const auto& edge) {
+                    const auto& [sourceVersion, peerVersion] = edge;
+                    return exactNodes.contains(
+                               RegistrationExactKey{
+                                   sourceTarget, sourceVersion})
+                        || exactNodes.contains(
+                               RegistrationExactKey{
+                                   peerTarget, peerVersion});
+                });
+            if (bindingIt->second.empty()) {
+                bindingIt = info.bindings.erase(bindingIt);
+            } else {
+                ++bindingIt;
+            }
+        }
+    }
+}
+
+}
+
+namespace xlings::xvm {
+
+std::expected<std::vector<RegisteredMember>, RegistrationError>
+apply_registration_batch(
+    VersionDB& db,
+    Workspace& workspace,
+    WorkspaceInstalled& installed,
+    const RegistrationBatch& batch,
+    std::vector<DetachedLegacyMember>* detached) {
+    if (batch.provider.empty()) {
+        return std::unexpected(detail_::registration_error_(
+            RegistrationErrorKind::InvalidBatchIdentity,
+            "/provider", {}, {}, "registration provider is empty"));
+    }
+    if (batch.providerVersion.empty()) {
+        return std::unexpected(detail_::registration_error_(
+            RegistrationErrorKind::InvalidBatchIdentity,
+            "/providerVersion", {}, {},
+            "registration provider release is empty"));
+    }
+
+    std::map<detail_::RegistrationExactKey, std::size_t> nodeIndexes;
+    for (std::size_t index = 0; index < batch.nodes.size(); ++index) {
+        const auto& node = batch.nodes[index];
+        const auto nodePath = std::format("/nodes/{}", index);
+        if (node.target.empty()) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::InvalidNodeIdentity,
+                nodePath + "/target", node.target, node.version,
+                "registration target is empty"));
+        }
+        if (node.version.empty()) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::InvalidNodeIdentity,
+                nodePath + "/version", node.target, node.version,
+                "registration version is empty"));
+        }
+        if (node.kind != "program"
+            && node.kind != "lib"
+            && node.kind != "group"
+            && node.kind != "files") {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::InvalidNodePayload,
+                nodePath + "/kind", node.target, node.version,
+                std::format(
+                    "unsupported registration node kind '{}'",
+                    node.kind)));
+        }
+        // `group` and `files` name no artifact to dispatch, so neither
+        // carries a source or destination *name*. A files entry is validated
+        // on its src/dst pair instead -- that is what it does carry.
+        const bool namesAnArtifact =
+            node.kind != "group" && node.kind != "files";
+        if (namesAnArtifact && node.sourceName.empty()) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::InvalidNodePayload,
+                nodePath + "/sourceName", node.target, node.version,
+                "materialized registration source name is empty"));
+        }
+        if (namesAnArtifact && node.destinationName.empty()) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::InvalidNodePayload,
+                nodePath + "/destinationName", node.target, node.version,
+                "materialized registration destination name is empty"));
+        }
+        if (node.kind == "files") {
+            if (node.fileSrc.empty()) {
+                return std::unexpected(detail_::registration_error_(
+                    RegistrationErrorKind::InvalidNodePayload,
+                    nodePath + "/src", node.target, node.version,
+                    "file asset declares no source"));
+            }
+            if (!is_permitted_file_destination(node.fileDst)) {
+                return std::unexpected(detail_::registration_error_(
+                    RegistrationErrorKind::InvalidNodePayload,
+                    nodePath + "/dst", node.target, node.version,
+                    std::format(
+                        "file asset destination '{}' is not allowed: it must "
+                        "be relative to the subos root, must not walk "
+                        "upward, and must live under usr/, etc/ or share/",
+                        node.fileDst)));
+            }
+        }
+        if (node.binding && node.binding->rootTarget.empty()) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::InvalidBindingIdentity,
+                nodePath + "/binding/rootTarget",
+                node.target, node.version,
+                "registration binding root target is empty"));
+        }
+        if (node.binding && node.binding->rootVersion.empty()) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::InvalidBindingIdentity,
+                nodePath + "/binding/rootVersion",
+                node.target, node.version,
+                "registration binding root version is empty"));
+        }
+
+        const detail_::RegistrationExactKey key{
+            node.target,
+            node.version,
+        };
+        if (const auto [_, inserted] =
+                nodeIndexes.emplace(key, index);
+            !inserted) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::DuplicateNode,
+                nodePath, node.target, node.version,
+                "duplicate exact registration node"));
+        }
+    }
+
+    std::map<std::string, detail_::RegistrationGroup> groups;
+    std::map<detail_::RegistrationExactKey, std::string> rootGroups;
+    std::map<detail_::RegistrationExactKey, std::string> nodeGroups;
+    const auto addMember = [&](
+        detail_::RegistrationGroup& group,
+        const RegistrationNode& node,
+        std::size_t index)
+        -> std::optional<RegistrationError> {
+        auto [memberIt, inserted] =
+            group.members.emplace(node.target, node.version);
+        if (!inserted && memberIt->second != node.version) {
+            return detail_::registration_error_(
+                RegistrationErrorKind::TargetVersionConflict,
+                std::format("/nodes/{}", index),
+                node.target, node.version,
+                std::format(
+                    "group '{}' selects two versions of target '{}'",
+                    group.label, node.target));
+        }
+        return std::nullopt;
+    };
+
+    for (std::size_t index = 0; index < batch.nodes.size(); ++index) {
+        const auto& node = batch.nodes[index];
+        if (!node.binding) continue;
+        const auto nodePath = std::format("/nodes/{}", index);
+        const detail_::RegistrationExactKey key{
+            node.target,
+            node.version,
+        };
+        const detail_::RegistrationExactKey root{
+            node.binding->rootTarget,
+            node.binding->rootVersion,
+        };
+        if (key == root) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::SelfBinding,
+                nodePath + "/binding", node.target, node.version,
+                "registration node cannot bind to itself"));
+        }
+        if (!nodeIndexes.contains(root)) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::RootNotInBatch,
+                nodePath + "/binding",
+                root.first, root.second,
+                "registration binding root is not an exact batch node"));
+        }
+
+        const auto label = node.binding->group.empty()
+            ? node.binding->rootTarget
+            : node.binding->group;
+        if (auto groupIt = groups.find(label);
+            groupIt != groups.end() && groupIt->second.root != root) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::GroupConflict,
+                nodePath + "/binding/group",
+                node.target, node.version,
+                std::format(
+                    "registration group '{}' has multiple roots", label)));
+        }
+        if (auto rootIt = rootGroups.find(root);
+            rootIt != rootGroups.end() && rootIt->second != label) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::GroupConflict,
+                nodePath + "/binding/group",
+                node.target, node.version,
+                "registration root is assigned to multiple groups"));
+        }
+        if (auto nodeIt = nodeGroups.find(key);
+            nodeIt != nodeGroups.end() && nodeIt->second != label) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::GroupConflict,
+                nodePath + "/binding/group",
+                node.target, node.version,
+                "registration node is assigned to multiple groups"));
+        }
+        if (auto rootNodeIt = nodeGroups.find(root);
+            rootNodeIt != nodeGroups.end()
+            && rootNodeIt->second != label) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::GroupConflict,
+                nodePath + "/binding/group",
+                node.target, node.version,
+                "registration root is assigned to multiple groups"));
+        }
+
+        auto [groupIt, _] = groups.try_emplace(
+            label,
+            detail_::RegistrationGroup{
+                .label = label,
+                .root = root,
+                .identityNode = key,
+                .identityPath = node.binding->group.empty()
+                    ? nodePath + "/binding/rootTarget"
+                    : nodePath + "/binding/group",
+            });
+        rootGroups[root] = label;
+        nodeGroups[key] = label;
+        nodeGroups[root] = label;
+        if (auto error = addMember(groupIt->second, node, index)) {
+            return std::unexpected(std::move(*error));
+        }
+        const auto& rootNode =
+            batch.nodes[nodeIndexes.at(root)];
+        if (auto error = addMember(
+                groupIt->second, rootNode, nodeIndexes.at(root))) {
+            return std::unexpected(std::move(*error));
+        }
+    }
+
+    for (std::size_t index = 0; index < batch.nodes.size(); ++index) {
+        const auto& node = batch.nodes[index];
+        const detail_::RegistrationExactKey key{
+            node.target,
+            node.version,
+        };
+        if (nodeGroups.contains(key)) continue;
+        const auto label = node.target;
+        if (auto groupIt = groups.find(label);
+            groupIt != groups.end() && groupIt->second.root != key) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::GroupConflict,
+                std::format("/nodes/{}", index),
+                node.target, node.version,
+                std::format(
+                    "registration group '{}' has multiple roots", label)));
+        }
+        auto [groupIt, _] = groups.try_emplace(
+            label,
+            detail_::RegistrationGroup{
+                .label = label,
+                .root = key,
+                .identityNode = key,
+                .identityPath =
+                    std::format("/nodes/{}/target", index),
+            });
+        nodeGroups[key] = label;
+        rootGroups[key] = label;
+        if (auto error = addMember(groupIt->second, node, index)) {
+            return std::unexpected(std::move(*error));
+        }
+    }
+
+    struct PersistedRegistrationGroup {
+        detail_::RegistrationExactKey root;
+        std::set<detail_::RegistrationExactKey> members;
+    };
+    std::map<std::string, PersistedRegistrationGroup> persistedGroups;
+    for (const auto& [target, info] : db) {
+        for (const auto& [version, data] : info.versions) {
+            if (!data.bindingGroup) continue;
+            const auto& ref = *data.bindingGroup;
+            if (ref.provider != batch.provider
+                || ref.providerVersion != batch.providerVersion) {
+                continue;
+            }
+            const detail_::RegistrationExactKey root{
+                ref.rootTarget,
+                ref.rootVersion,
+            };
+            auto [groupIt, inserted] = persistedGroups.try_emplace(
+                ref.group,
+                PersistedRegistrationGroup{
+                    .root = root,
+                });
+            if (!inserted && groupIt->second.root != root) {
+                return std::unexpected(detail_::registration_error_(
+                    RegistrationErrorKind::GroupConflict,
+                    "/bindingGroups/"
+                        + detail_::registration_path_token_(ref.group),
+                    target, version,
+                    std::format(
+                        "persisted registration group '{}' has multiple roots",
+                        ref.group)));
+            }
+            groupIt->second.members.emplace(target, version);
+        }
+    }
+    for (const auto& [label, group] : groups) {
+        const auto persistedIt = persistedGroups.find(label);
+        if (persistedIt == persistedGroups.end()) continue;
+        const auto missingMemberIt = std::ranges::find_if(
+            persistedIt->second.members,
+            [&](const auto& member) {
+                return !nodeIndexes.contains(member);
+            });
+        if (persistedIt->second.root != group.root) {
+            if (missingMemberIt
+                == persistedIt->second.members.end()) {
+                continue;
+            }
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::GroupConflict,
+                group.identityPath,
+                group.identityNode.first,
+                group.identityNode.second,
+                std::format(
+                    "registration group '{}' conflicts with persisted root '{}@{}'",
+                    label,
+                    persistedIt->second.root.first,
+                    persistedIt->second.root.second)));
+        }
+        if (missingMemberIt
+            == persistedIt->second.members.end()) {
+            continue;
+        }
+        return std::unexpected(detail_::registration_error_(
+            RegistrationErrorKind::IncompleteOwnedGroup,
+            group.identityPath,
+            missingMemberIt->first,
+            missingMemberIt->second,
+            std::format(
+                "same-owner registration omits an existing member of group '{}'",
+                label)));
+    }
+
+    for (std::size_t index = 0; index < batch.headers.size(); ++index) {
+        const auto& header = batch.headers[index];
+        const auto headerPath = std::format("/headers/{}", index);
+        if (header.sourceDir.empty()) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::InvalidHeader,
+                headerPath + "/sourceDir", {}, {},
+                "registration header source directory is empty"));
+        }
+
+        auto groupIt = groups.end();
+        if (!header.group.empty()) {
+            groupIt = groups.find(header.group);
+            if (groupIt == groups.end()) {
+                return std::unexpected(detail_::registration_error_(
+                    RegistrationErrorKind::HeaderGroupNotFound,
+                    headerPath + "/group", header.group, {},
+                    std::format(
+                        "registration header group '{}' does not exist",
+                        header.group)));
+            }
+        } else if (groups.size() == 1) {
+            groupIt = groups.begin();
+        } else {
+            // More than one candidate. A recipe registering several
+            // independent targets (a program plus a library, say) makes every
+            // ungrouped node its own singleton group, so requiring exactly one
+            // candidate would reject perfectly ordinary recipes. Break the tie
+            // with the package's own target: headers shipped by package `p`
+            // belong with `p`.
+            //
+            // Only when that target resolves to exactly one group. If it is
+            // absent, or registered at versions that landed in different
+            // groups, naming it identifies no single owner and guessing would
+            // attach the headers to an arbitrary group.
+            std::string_view resolved;
+            bool spansGroups = false;
+            if (!batch.primaryTarget.empty()) {
+                for (const auto& [key, label] : nodeGroups) {
+                    if (key.first != batch.primaryTarget) continue;
+                    if (resolved.empty()) {
+                        resolved = label;
+                    } else if (resolved != label) {
+                        spansGroups = true;
+                        break;
+                    }
+                }
+            }
+            if (resolved.empty() || spansGroups) {
+                return std::unexpected(detail_::registration_error_(
+                    RegistrationErrorKind::HeaderAmbiguous,
+                    headerPath + "/group", batch.primaryTarget, {},
+                    std::format(
+                        "ungrouped registration header has {} candidate "
+                        "groups and primaryTarget '{}' {}; name the owning "
+                        "group on the header",
+                        groups.size(), batch.primaryTarget,
+                        spansGroups ? "spans several of them"
+                                    : "is not one of them")));
+            }
+            groupIt = groups.find(std::string(resolved));
+        }
+        groupIt->second.headers.push_back({
+            .sourceDir = header.sourceDir,
+            .destinationPrefix = header.destinationPrefix,
+        });
+    }
+    for (auto& [_, group] : groups) {
+        std::ranges::sort(
+            group.headers,
+            [](const HeaderAsset& lhs, const HeaderAsset& rhs) {
+                return std::tie(lhs.sourceDir, lhs.destinationPrefix)
+                    < std::tie(rhs.sourceDir, rhs.destinationPrefix);
+            });
+        group.headers.erase(
+            std::unique(
+                group.headers.begin(),
+                group.headers.end(),
+                [](const HeaderAsset& lhs, const HeaderAsset& rhs) {
+                    return lhs.sourceDir == rhs.sourceDir
+                        && lhs.destinationPrefix
+                            == rhs.destinationPrefix;
+                }),
+            group.headers.end());
+    }
+
+    // Owner-less entries this batch takes over, and the field that differed.
+    // Collected during validation and reported with the result; see the
+    // adoption comment below.
+    std::map<detail_::RegistrationExactKey, std::string> adoptedLegacy;
+
+    for (std::size_t index = 0; index < batch.nodes.size(); ++index) {
+        const auto& node = batch.nodes[index];
+        const auto infoIt = db.find(node.target);
+        if (infoIt == db.end()) continue;
+        const auto dataIt = infoIt->second.versions.find(node.version);
+        if (dataIt == infoIt->second.versions.end()) continue;
+        const auto& data = dataIt->second;
+        const auto nodePath = std::format("/nodes/{}", index);
+
+        if (data.bindingGroup) {
+            const auto& owner = *data.bindingGroup;
+            if (owner.provider != batch.provider
+                || owner.providerVersion != batch.providerVersion) {
+                return std::unexpected(detail_::registration_error_(
+                    RegistrationErrorKind::OwnershipConflict,
+                    nodePath, node.target, node.version,
+                    std::format(
+                        "exact registration is owned by '{}@{}'",
+                        owner.provider, owner.providerVersion)));
+            }
+
+            std::set<detail_::RegistrationExactKey> oldMembers;
+            for (const auto& [target, info] : db) {
+                for (const auto& [version, member] : info.versions) {
+                    if (member.bindingGroup
+                        && detail_::same_registration_group_(
+                            *member.bindingGroup, owner)) {
+                        oldMembers.emplace(target, version);
+                    }
+                }
+            }
+            const auto rootInfoIt = db.find(owner.rootTarget);
+            if (rootInfoIt != db.end()) {
+                const auto rootIt = rootInfoIt->second.versions.find(
+                    owner.rootVersion);
+                if (rootIt != rootInfoIt->second.versions.end()
+                    && rootIt->second.bindingGroup
+                    && detail_::same_registration_group_(
+                        *rootIt->second.bindingGroup, owner)) {
+                    for (const auto& [target, version] :
+                         rootIt->second.bindingMembers) {
+                        const auto memberInfoIt = db.find(target);
+                        if (memberInfoIt != db.end()
+                            && memberInfoIt->second.versions.contains(
+                                version)) {
+                            oldMembers.emplace(target, version);
+                        }
+                    }
+                }
+            }
+            for (const auto& oldMember : oldMembers) {
+                if (nodeIndexes.contains(oldMember)) continue;
+                return std::unexpected(detail_::registration_error_(
+                    RegistrationErrorKind::IncompleteOwnedGroup,
+                    nodePath, oldMember.first, oldMember.second,
+                    "same-owner registration omits an existing group member"));
+            }
+            continue;
+        }
+
+        // Owner-less entry with different contents: ADOPT it, do not refuse.
+        //
+        // This used to be RegistrationErrorKind::LegacyPayloadMismatch, whose
+        // hint told the user to uninstall the package first. Nothing owns an
+        // owner-less entry, so there is no claim to protect -- and `remove`
+        // keeps exactly these entries when another subos still references the
+        // version (#443), so the hint pointed at a door that does not open.
+        // The two ends met and the only remaining exit was hand-editing the
+        // state file (#422).
+        //
+        // Adoption is also a repair, not just an escape: the entry comes out
+        // of it OWNED (the group pass below assigns bindingGroup), so the next
+        // provider that tries to take the same name@version meets
+        // OwnershipConflict -- a protection the owner-less entry could never
+        // raise. The refusal preserved damage it could not fix; the measured
+        // case is an llvm@20.1.7 whose recorded path used Windows backslashes
+        // on Linux.
+        //
+        // The group-integrity checks below are NOT relaxed: a batch that would
+        // rewrite part of a bound group is still rejected.
+        if (auto field = detail_::legacy_payload_mismatch_(
+                node, infoIt->second, data)) {
+            adoptedLegacy.insert_or_assign(
+                detail_::RegistrationExactKey{node.target, node.version},
+                *field);
+        }
+        auto selection = resolve_binding_selection(
+            db, node.target, node.version);
+        if (!selection) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::BindingValidationFailed,
+                nodePath, selection.error().target,
+                selection.error().version,
+                selection.error().message));
+        }
+        for (const auto& [target, version] : selection->members) {
+            if (nodeIndexes.contains(
+                    detail_::RegistrationExactKey{target, version})) {
+                continue;
+            }
+            // The batch does not cover the whole legacy component.
+            //
+            // Refusing outright is right when the missing member could belong
+            // to somebody else. It is wrong when the member is plainly this
+            // package's own leftover, and then it is a trap: the component was
+            // recorded by a client on ANOTHER PLATFORM, which registered names
+            // this platform's recipe never produces. Measured on a real home,
+            // an llvm@20.1.7 registered on Windows leaves `cl`, `lib`, `link`
+            // and `rc` bound to it; on Linux the recipe emits no such nodes, so
+            // every install refused -- and `remove` refused too, for its own
+            // reasons, so nothing could move.
+            //
+            // Three conditions make the member safe to detach instead:
+            //   1. it is OWNER-LESS. Nothing claims it, so no provider's
+            //      selection is being rewritten behind its back.
+            //   2. its payload lies inside a payload this batch is
+            //      registering. That is the evidence it belongs to this
+            //      package rather than merely resembling it.
+            //
+            // Being ACTIVE is deliberately NOT a third condition. It was one at
+            // first, and it turned out to veto exactly the case this exists
+            // for: on the measured home `cl`, `lib`, `link` and `rc` are all
+            // active, so the refusal survived the fix. It also protects
+            // nothing. Detaching does not deregister the entry and does not
+            // deactivate it -- the shim still dispatches to the same place. All
+            // that changes is that the entry stops claiming membership in a
+            // release that no longer registers it, which is simply true.
+            //
+            // Detach, not delete: the entry stays in the database, only its
+            // edges to this batch go (erase_exact_registration_edges_ below
+            // drops them, since the peer side IS in the batch). What is left
+            // is a standalone owner-less record with a payload that does not
+            // resolve -- which `self doctor` already knows how to see and, at
+            // the end of its ladder, to prune. Deleting it here would make a
+            // registration silently destroy state on behalf of a repair that
+            // has its own preview and its own reporting.
+            const VData* memberData = nullptr;
+            if (const auto memberInfoIt = db.find(target);
+                memberInfoIt != db.end()) {
+                const auto memberDataIt =
+                    memberInfoIt->second.versions.find(version);
+                if (memberDataIt != memberInfoIt->second.versions.end()) {
+                    memberData = &memberDataIt->second;
+                }
+            }
+            const bool ownerLess = memberData && !memberData->bindingGroup;
+            const auto memberPath = memberData
+                ? detail_::normalized_payload_path_(memberData->path)
+                : std::string{};
+            const bool insideBatchPayload = !memberPath.empty()
+                && std::ranges::any_of(batch.nodes, [&](const auto& n) {
+                    return detail_::payload_path_covers_(
+                        detail_::normalized_payload_path_(n.path), memberPath);
+                });
+            if (ownerLess && insideBatchPayload) {
+                if (detached) detached->push_back({target, version});
+                continue;
+            }
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::IncompleteLegacyComponent,
+                nodePath, target, version,
+                "legacy component is not completely represented in batch"));
+        }
+    }
+
+    auto candidateDb = db;
+    auto candidateWorkspace = workspace;
+    auto candidateInstalled = installed;
+
+    for (const auto& [_, index] : nodeIndexes) {
+        const auto& node = batch.nodes[index];
+        auto& info = candidateDb[node.target];
+        if (info.type.empty()) info.type = node.kind;
+        if (info.filename.empty() && node.kind != "group") {
+            info.filename = node.sourceName;
+        }
+        auto& data = info.versions[node.version];
+        data.path = node.path;
+        data.kind = node.kind;
+        data.fileSrc = node.fileSrc;
+        data.fileDst = node.fileDst;
+        data.sourceName =
+            node.kind == "group" ? std::string{} : node.sourceName;
+        data.destinationName =
+            node.kind == "group" ? std::string{} : node.destinationName;
+        data.alias = node.alias;
+        data.envs = node.envs;
+        data.bindingGroup.reset();
+        data.bindingMembers.clear();
+        data.bindingMembersDeclared = false;
+        data.bindingHeaders.clear();
+        data.bindingHeadersDeclared = false;
+        data.bindingIntegrityIssues.clear();
+    }
+    std::set<detail_::RegistrationExactKey> exactNodes;
+    for (const auto& [key, _] : nodeIndexes) {
+        exactNodes.insert(key);
+    }
+    detail_::erase_exact_registration_edges_(
+        candidateDb, exactNodes);
+
+    std::vector<RegisteredMember> registered;
+    for (const auto& [_, group] : groups) {
+        // Decide activation once for the release, not once per member.
+        //
+        // Per member, a release that adds a name the previous one did not
+        // have would activate just that name: the new member goes to this
+        // release while everything else stays on the old one, and the
+        // workspace ends up spanning two of them -- the exact state the
+        // binding-group model exists to prevent, produced by install.
+        //
+        // Leaving a name alone when something already owns it is also the
+        // right answer across providers: installing gcc must not silently
+        // take `cc` away from an active llvm.
+        //
+        // But leaving the name alone is all that was ever intended, and this
+        // used to do much more than that: ANY member name being active vetoed
+        // the WHOLE group, including members nobody was contesting. Installing
+        // node while a standalone npm package held `npm` therefore activated
+        // nothing at all -- `node` and `npx`, which no other package provides,
+        // came out installed and unreachable, with no shim and no error. The
+        // user met it as `/usr/bin/env: 'node': No such file or directory`
+        // from a tool that had nothing to do with xlings.
+        //
+        // Who holds a contested name decides whether it vetoes:
+        //
+        //   same provider   -- an older release of this same package. Moving
+        //                      part of the workspace to the new release and
+        //                      leaving the rest on the old one is exactly the
+        //                      split the binding-group model exists to
+        //                      prevent, and choosing between two releases of
+        //                      one package is the user's call: `use`. Veto.
+        //   other provider  -- a different package owns that name and keeps
+        //                      it. That is ownership, not incoherence, and it
+        //                      says nothing about this release's other names.
+        //                      No veto; the contested name is skipped below.
+        //   unknown         -- an entry with no group metadata, written before
+        //                      providers were recorded. Treated as the same
+        //                      provider, so old homes keep today's behaviour.
+        const auto contested_by =
+            [&](const std::string& memberTarget)
+            -> std::optional<std::string> {
+            const auto activeIt = candidateWorkspace.find(memberTarget);
+            if (activeIt == candidateWorkspace.end()) return std::nullopt;
+            const auto dbIt = candidateDb.find(memberTarget);
+            if (dbIt == candidateDb.end()) return std::string{};
+            const auto verIt = dbIt->second.versions.find(activeIt->second);
+            if (verIt == dbIt->second.versions.end()) return std::string{};
+            if (!verIt->second.bindingGroup) return std::string{};
+            return verIt->second.bindingGroup->provider;
+        };
+
+        std::set<std::string> contested;
+        bool sameProviderContest = false;
+        for (const auto& member : group.members) {
+            const auto owner = contested_by(member.first);
+            if (!owner) continue;
+            contested.insert(member.first);
+            if (*owner == batch.provider) sameProviderContest = true;
+        }
+
+        // Is there anything left worth activating?
+        //
+        // A virtual root exists only to anchor the release its libraries
+        // belong to; there is no command behind it. Activating one writes a
+        // shim that can only print "no active version", which is issue #452:
+        // `self doctor` called the file an orphan, `--fix` deleted it, and the
+        // next install put it straight back. A group whose only uncontested
+        // members are anchors therefore stays inactive, exactly as before.
+        //
+        // Neither the path nor the kind can answer this on its own. A real
+        // anchor carries a payload path like everything else --
+        // `xim-musl-gnu-gcc` records musl-gcc's own directory, and the #452
+        // fixture's root, registered with no bindir at all, still ends up with
+        // the package install dir -- and `kind` defaults to "program" for both.
+        // So the batch's own answer (RegistrationNode::runnable, set by
+        // whoever materialised the payload) is what decides, with the kind and
+        // path as the cheap checks in front of it.
+        const bool anyRealUncontested = std::ranges::any_of(
+            group.members, [&](const auto& member) {
+                if (contested.contains(member.first)) return false;
+                const auto dbIt = candidateDb.find(member.first);
+                if (dbIt == candidateDb.end()) return false;
+                const auto verIt = dbIt->second.versions.find(member.second);
+                if (verIt == dbIt->second.versions.end()) return false;
+                if (verIt->second.path.empty()) return false;
+                if (effective_kind(dbIt->second, verIt->second) != "program") {
+                    return false;
+                }
+                const auto nodeIt = std::ranges::find_if(
+                    batch.nodes, [&](const RegistrationNode& n) {
+                        return n.target == member.first
+                            && n.version == member.second;
+                    });
+                return nodeIt == batch.nodes.end() || nodeIt->runnable;
+            });
+
+        // `contested.empty()` first, and not folded into the clause after it.
+        //
+        // The anchor guard exists to stop #452 coming back through the door
+        // the cross-provider rule opens, so it applies only to that door. A
+        // release nobody is contesting activates exactly as it always has --
+        // including a batch that is nothing but a virtual root, which is how
+        // a library-only package registers and which has to stay activated
+        // for anything to bind to it.
+        const bool activateGroup =
+            batch.useAfterInstall
+            || contested.empty()
+            || (!sameProviderContest && anyRealUncontested);
+
+        const BindingGroupRef ref{
+            .provider = batch.provider,
+            .providerVersion = batch.providerVersion,
+            .group = group.label,
+            .rootTarget = group.root.first,
+            .rootVersion = group.root.second,
+        };
+        for (const auto& [target, version] : group.members) {
+            auto& data =
+                candidateDb.at(target).versions.at(version);
+            data.bindingGroup = ref;
+            data.bindingMembers.clear();
+            data.bindingMembersDeclared = false;
+            data.bindingHeaders.clear();
+            data.bindingHeadersDeclared = false;
+            const auto adoptedIt = adoptedLegacy.find(
+                detail_::RegistrationExactKey{target, version});
+            registered.push_back({
+                .target = target,
+                .version = version,
+                .kind = data.kind,
+                .adoptedLegacy = adoptedIt != adoptedLegacy.end(),
+                .adoptedLegacyField = adoptedIt != adoptedLegacy.end()
+                    ? adoptedIt->second : std::string{},
+            });
+            auto& versions = candidateInstalled[target];
+            bool foundVersion = false;
+            std::erase_if(
+                versions,
+                [&](const std::string& installedVersion) {
+                    if (installedVersion != version) return false;
+                    if (!foundVersion) {
+                        foundVersion = true;
+                        return false;
+                    }
+                    return true;
+                });
+            if (!foundVersion) {
+                versions.push_back(version);
+            }
+            // A contested name stays with whoever holds it. `useAfterInstall`
+            // is the one exception, and it is not an exception to the rule so
+            // much as a different question: the user typed the switch, so
+            // taking the name is what they asked for.
+            if (activateGroup
+                && (batch.useAfterInstall || !contested.contains(target))) {
+                candidateWorkspace[target] = version;
+            }
+        }
+
+        auto& root =
+            candidateDb.at(group.root.first)
+                .versions.at(group.root.second);
+        root.bindingMembers = group.members;
+        root.bindingMembersDeclared = true;
+        root.bindingHeaders = group.headers;
+        root.bindingHeadersDeclared = !group.headers.empty();
+        for (const auto& [target, version] : group.members) {
+            if (target == group.root.first
+                && version == group.root.second) {
+                continue;
+            }
+            candidateDb.at(group.root.first)
+                .bindings[target][group.root.second] = version;
+            candidateDb.at(target)
+                .bindings[group.root.first][version] = group.root.second;
+        }
+    }
+
+    std::map<
+        detail_::RegistrationGroupIdentity,
+        detail_::RegistrationExactKey> candidateGroups;
+    for (const auto& [target, info] : candidateDb) {
+        for (const auto& [version, data] : info.versions) {
+            if (!data.bindingGroup) continue;
+            const auto& ref = *data.bindingGroup;
+            if (ref.provider != batch.provider
+                || ref.providerVersion != batch.providerVersion) {
+                continue;
+            }
+            candidateGroups.try_emplace(
+                detail_::registration_group_identity_(ref),
+                target, version);
+        }
+    }
+    for (const auto& [_, representative] : candidateGroups) {
+        const auto& ref =
+            *candidateDb.at(representative.first)
+                 .versions.at(representative.second)
+                 .bindingGroup;
+        auto selection = resolve_binding_selection(
+            candidateDb, representative.first, representative.second);
+        if (!selection) {
+            return std::unexpected(detail_::registration_error_(
+                RegistrationErrorKind::BindingValidationFailed,
+                "/bindingGroups/"
+                    + detail_::registration_path_token_(ref.group),
+                selection.error().target,
+                selection.error().version,
+                selection.error().message));
+        }
+    }
+
+    db.swap(candidateDb);
+    workspace.swap(candidateWorkspace);
+    installed.swap(candidateInstalled);
+    return registered;
+}
+
+}
diff --git a/src/core/xvm/registration.cppm b/src/core/xvm/registration.cppm
index 43322b53..f7fdfaa7 100644
--- a/src/core/xvm/registration.cppm
+++ b/src/core/xvm/registration.cppm
@@ -146,159 +146,6 @@ struct RegistrationGroup {
     std::vector<HeaderAsset> headers;
 };
 
-RegistrationError registration_error_(
-    RegistrationErrorKind kind,
-    std::string path,
-    std::string target,
-    std::string version,
-    std::string message) {
-    return {
-        .kind = kind,
-        .path = std::move(path),
-        .target = std::move(target),
-        .version = std::move(version),
-        .message = std::move(message),
-    };
-}
-
-bool same_registration_group_(
-    const BindingGroupRef& lhs,
-    const BindingGroupRef& rhs) {
-    return lhs.provider == rhs.provider
-        && lhs.providerVersion == rhs.providerVersion
-        && lhs.group == rhs.group
-        && lhs.rootTarget == rhs.rootTarget
-        && lhs.rootVersion == rhs.rootVersion;
-}
-
-RegistrationGroupIdentity registration_group_identity_(
-    const BindingGroupRef& group) {
-    return {
-        group.provider,
-        group.providerVersion,
-        group.group,
-        group.rootTarget,
-        group.rootVersion,
-    };
-}
-
-// Moved to xvm.types so the switch planner reads them identically -- see the
-// comment there. Kept as thin aliases so this file's call sites stay legible.
-std::string effective_kind_(
-    const VInfo& info,
-    const VData& data) {
-    return effective_kind(info, data);
-}
-
-std::string effective_source_name_(
-    const std::string& target,
-    const VInfo& info,
-    const VData& data,
-    std::string_view kind) {
-    return effective_source_name(target, info, data, kind);
-}
-
-std::string effective_destination_name_(
-    const std::string& target,
-    const VData& data,
-    std::string_view kind,
-    std::string_view sourceName) {
-    return effective_destination_name(target, data, kind, sourceName);
-}
-
-std::optional<std::string> legacy_payload_mismatch_(
-    const RegistrationNode& node,
-    const VInfo& info,
-    const VData& data) {
-    const auto kind = effective_kind_(info, data);
-    const auto sourceName = effective_source_name_(
-        node.target, info, data, kind);
-    const auto destinationName = effective_destination_name_(
-        node.target, data, kind, sourceName);
-    const auto namesAnArtifact =
-        node.kind != "group" && node.kind != "files";
-    const auto expectedSourceName = namesAnArtifact
-        ? std::string_view{node.sourceName}
-        : std::string_view{};
-    const auto expectedDestinationName = namesAnArtifact
-        ? std::string_view{node.destinationName}
-        : std::string_view{};
-    if (data.path != node.path) return "path";
-    if (kind != node.kind) return "kind";
-    if (sourceName != expectedSourceName) return "sourceName";
-    if (destinationName != expectedDestinationName) {
-        return "destinationName";
-    }
-    if (data.alias != node.alias) return "alias";
-    if (data.envs != node.envs) return "envs";
-    return std::nullopt;
-}
-
-std::string registration_path_token_(std::string_view token) {
-    std::string escaped;
-    escaped.reserve(token.size());
-    for (const auto ch : token) {
-        if (ch == '~') {
-            escaped += "~0";
-        } else if (ch == '/') {
-            escaped += "~1";
-        } else {
-            escaped += ch;
-        }
-    }
-    return escaped;
-}
-
-// Path comparison that survives a record written on another platform.
-//
-// Not a filesystem question: `db` holds whatever string the client that wrote
-// it produced, and a home carried over from Windows holds
-// `C:\…` / `/home/you/.xlings\data\xpkgs\…` on a machine where those separators
-// mean nothing. Normalising to '/' is what lets a Linux client recognise the
-// record as its own.
-std::string normalized_payload_path_(std::string_view path) {
-    std::string out{path};
-    std::ranges::replace(out, '\\', '/');
-    while (out.size() > 1 && out.back() == '/') out.pop_back();
-    return out;
-}
-
-// Is `candidate` the same payload as `root`, or something inside it?
-bool payload_path_covers_(std::string_view root, std::string_view candidate) {
-    if (root.empty() || candidate.empty()) return false;
-    if (candidate == root) return true;
-    return candidate.size() > root.size()
-        && candidate.starts_with(root)
-        && candidate[root.size()] == '/';
-}
-
-void erase_exact_registration_edges_(
-    VersionDB& db,
-    const std::set<RegistrationExactKey>& exactNodes) {
-    for (auto& [sourceTarget, info] : db) {
-        for (auto bindingIt = info.bindings.begin();
-             bindingIt != info.bindings.end();) {
-            const auto& peerTarget = bindingIt->first;
-            std::erase_if(
-                bindingIt->second,
-                [&](const auto& edge) {
-                    const auto& [sourceVersion, peerVersion] = edge;
-                    return exactNodes.contains(
-                               RegistrationExactKey{
-                                   sourceTarget, sourceVersion})
-                        || exactNodes.contains(
-                               RegistrationExactKey{
-                                   peerTarget, peerVersion});
-                });
-            if (bindingIt->second.empty()) {
-                bindingIt = info.bindings.erase(bindingIt);
-            } else {
-                ++bindingIt;
-            }
-        }
-    }
-}
-
 }  // namespace xlings::xvm::detail_
 
 namespace xlings::xvm {
@@ -309,834 +156,6 @@ apply_registration_batch(
     Workspace& workspace,
     WorkspaceInstalled& installed,
     const RegistrationBatch& batch,
-    std::vector<DetachedLegacyMember>* detached) {
-    if (batch.provider.empty()) {
-        return std::unexpected(detail_::registration_error_(
-            RegistrationErrorKind::InvalidBatchIdentity,
-            "/provider", {}, {}, "registration provider is empty"));
-    }
-    if (batch.providerVersion.empty()) {
-        return std::unexpected(detail_::registration_error_(
-            RegistrationErrorKind::InvalidBatchIdentity,
-            "/providerVersion", {}, {},
-            "registration provider release is empty"));
-    }
-
-    std::map<detail_::RegistrationExactKey, std::size_t> nodeIndexes;
-    for (std::size_t index = 0; index < batch.nodes.size(); ++index) {
-        const auto& node = batch.nodes[index];
-        const auto nodePath = std::format("/nodes/{}", index);
-        if (node.target.empty()) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::InvalidNodeIdentity,
-                nodePath + "/target", node.target, node.version,
-                "registration target is empty"));
-        }
-        if (node.version.empty()) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::InvalidNodeIdentity,
-                nodePath + "/version", node.target, node.version,
-                "registration version is empty"));
-        }
-        if (node.kind != "program"
-            && node.kind != "lib"
-            && node.kind != "group"
-            && node.kind != "files") {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::InvalidNodePayload,
-                nodePath + "/kind", node.target, node.version,
-                std::format(
-                    "unsupported registration node kind '{}'",
-                    node.kind)));
-        }
-        // `group` and `files` name no artifact to dispatch, so neither
-        // carries a source or destination *name*. A files entry is validated
-        // on its src/dst pair instead -- that is what it does carry.
-        const bool namesAnArtifact =
-            node.kind != "group" && node.kind != "files";
-        if (namesAnArtifact && node.sourceName.empty()) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::InvalidNodePayload,
-                nodePath + "/sourceName", node.target, node.version,
-                "materialized registration source name is empty"));
-        }
-        if (namesAnArtifact && node.destinationName.empty()) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::InvalidNodePayload,
-                nodePath + "/destinationName", node.target, node.version,
-                "materialized registration destination name is empty"));
-        }
-        if (node.kind == "files") {
-            if (node.fileSrc.empty()) {
-                return std::unexpected(detail_::registration_error_(
-                    RegistrationErrorKind::InvalidNodePayload,
-                    nodePath + "/src", node.target, node.version,
-                    "file asset declares no source"));
-            }
-            if (!is_permitted_file_destination(node.fileDst)) {
-                return std::unexpected(detail_::registration_error_(
-                    RegistrationErrorKind::InvalidNodePayload,
-                    nodePath + "/dst", node.target, node.version,
-                    std::format(
-                        "file asset destination '{}' is not allowed: it must "
-                        "be relative to the subos root, must not walk "
-                        "upward, and must live under usr/, etc/ or share/",
-                        node.fileDst)));
-            }
-        }
-        if (node.binding && node.binding->rootTarget.empty()) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::InvalidBindingIdentity,
-                nodePath + "/binding/rootTarget",
-                node.target, node.version,
-                "registration binding root target is empty"));
-        }
-        if (node.binding && node.binding->rootVersion.empty()) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::InvalidBindingIdentity,
-                nodePath + "/binding/rootVersion",
-                node.target, node.version,
-                "registration binding root version is empty"));
-        }
-
-        const detail_::RegistrationExactKey key{
-            node.target,
-            node.version,
-        };
-        if (const auto [_, inserted] =
-                nodeIndexes.emplace(key, index);
-            !inserted) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::DuplicateNode,
-                nodePath, node.target, node.version,
-                "duplicate exact registration node"));
-        }
-    }
-
-    std::map<std::string, detail_::RegistrationGroup> groups;
-    std::map<detail_::RegistrationExactKey, std::string> rootGroups;
-    std::map<detail_::RegistrationExactKey, std::string> nodeGroups;
-    const auto addMember = [&](
-        detail_::RegistrationGroup& group,
-        const RegistrationNode& node,
-        std::size_t index)
-        -> std::optional<RegistrationError> {
-        auto [memberIt, inserted] =
-            group.members.emplace(node.target, node.version);
-        if (!inserted && memberIt->second != node.version) {
-            return detail_::registration_error_(
-                RegistrationErrorKind::TargetVersionConflict,
-                std::format("/nodes/{}", index),
-                node.target, node.version,
-                std::format(
-                    "group '{}' selects two versions of target '{}'",
-                    group.label, node.target));
-        }
-        return std::nullopt;
-    };
-
-    for (std::size_t index = 0; index < batch.nodes.size(); ++index) {
-        const auto& node = batch.nodes[index];
-        if (!node.binding) continue;
-        const auto nodePath = std::format("/nodes/{}", index);
-        const detail_::RegistrationExactKey key{
-            node.target,
-            node.version,
-        };
-        const detail_::RegistrationExactKey root{
-            node.binding->rootTarget,
-            node.binding->rootVersion,
-        };
-        if (key == root) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::SelfBinding,
-                nodePath + "/binding", node.target, node.version,
-                "registration node cannot bind to itself"));
-        }
-        if (!nodeIndexes.contains(root)) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::RootNotInBatch,
-                nodePath + "/binding",
-                root.first, root.second,
-                "registration binding root is not an exact batch node"));
-        }
-
-        const auto label = node.binding->group.empty()
-            ? node.binding->rootTarget
-            : node.binding->group;
-        if (auto groupIt = groups.find(label);
-            groupIt != groups.end() && groupIt->second.root != root) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::GroupConflict,
-                nodePath + "/binding/group",
-                node.target, node.version,
-                std::format(
-                    "registration group '{}' has multiple roots", label)));
-        }
-        if (auto rootIt = rootGroups.find(root);
-            rootIt != rootGroups.end() && rootIt->second != label) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::GroupConflict,
-                nodePath + "/binding/group",
-                node.target, node.version,
-                "registration root is assigned to multiple groups"));
-        }
-        if (auto nodeIt = nodeGroups.find(key);
-            nodeIt != nodeGroups.end() && nodeIt->second != label) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::GroupConflict,
-                nodePath + "/binding/group",
-                node.target, node.version,
-                "registration node is assigned to multiple groups"));
-        }
-        if (auto rootNodeIt = nodeGroups.find(root);
-            rootNodeIt != nodeGroups.end()
-            && rootNodeIt->second != label) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::GroupConflict,
-                nodePath + "/binding/group",
-                node.target, node.version,
-                "registration root is assigned to multiple groups"));
-        }
-
-        auto [groupIt, _] = groups.try_emplace(
-            label,
-            detail_::RegistrationGroup{
-                .label = label,
-                .root = root,
-                .identityNode = key,
-                .identityPath = node.binding->group.empty()
-                    ? nodePath + "/binding/rootTarget"
-                    : nodePath + "/binding/group",
-            });
-        rootGroups[root] = label;
-        nodeGroups[key] = label;
-        nodeGroups[root] = label;
-        if (auto error = addMember(groupIt->second, node, index)) {
-            return std::unexpected(std::move(*error));
-        }
-        const auto& rootNode =
-            batch.nodes[nodeIndexes.at(root)];
-        if (auto error = addMember(
-                groupIt->second, rootNode, nodeIndexes.at(root))) {
-            return std::unexpected(std::move(*error));
-        }
-    }
-
-    for (std::size_t index = 0; index < batch.nodes.size(); ++index) {
-        const auto& node = batch.nodes[index];
-        const detail_::RegistrationExactKey key{
-            node.target,
-            node.version,
-        };
-        if (nodeGroups.contains(key)) continue;
-        const auto label = node.target;
-        if (auto groupIt = groups.find(label);
-            groupIt != groups.end() && groupIt->second.root != key) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::GroupConflict,
-                std::format("/nodes/{}", index),
-                node.target, node.version,
-                std::format(
-                    "registration group '{}' has multiple roots", label)));
-        }
-        auto [groupIt, _] = groups.try_emplace(
-            label,
-            detail_::RegistrationGroup{
-                .label = label,
-                .root = key,
-                .identityNode = key,
-                .identityPath =
-                    std::format("/nodes/{}/target", index),
-            });
-        nodeGroups[key] = label;
-        rootGroups[key] = label;
-        if (auto error = addMember(groupIt->second, node, index)) {
-            return std::unexpected(std::move(*error));
-        }
-    }
-
-    struct PersistedRegistrationGroup {
-        detail_::RegistrationExactKey root;
-        std::set<detail_::RegistrationExactKey> members;
-    };
-    std::map<std::string, PersistedRegistrationGroup> persistedGroups;
-    for (const auto& [target, info] : db) {
-        for (const auto& [version, data] : info.versions) {
-            if (!data.bindingGroup) continue;
-            const auto& ref = *data.bindingGroup;
-            if (ref.provider != batch.provider
-                || ref.providerVersion != batch.providerVersion) {
-                continue;
-            }
-            const detail_::RegistrationExactKey root{
-                ref.rootTarget,
-                ref.rootVersion,
-            };
-            auto [groupIt, inserted] = persistedGroups.try_emplace(
-                ref.group,
-                PersistedRegistrationGroup{
-                    .root = root,
-                });
-            if (!inserted && groupIt->second.root != root) {
-                return std::unexpected(detail_::registration_error_(
-                    RegistrationErrorKind::GroupConflict,
-                    "/bindingGroups/"
-                        + detail_::registration_path_token_(ref.group),
-                    target, version,
-                    std::format(
-                        "persisted registration group '{}' has multiple roots",
-                        ref.group)));
-            }
-            groupIt->second.members.emplace(target, version);
-        }
-    }
-    for (const auto& [label, group] : groups) {
-        const auto persistedIt = persistedGroups.find(label);
-        if (persistedIt == persistedGroups.end()) continue;
-        const auto missingMemberIt = std::ranges::find_if(
-            persistedIt->second.members,
-            [&](const auto& member) {
-                return !nodeIndexes.contains(member);
-            });
-        if (persistedIt->second.root != group.root) {
-            if (missingMemberIt
-                == persistedIt->second.members.end()) {
-                continue;
-            }
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::GroupConflict,
-                group.identityPath,
-                group.identityNode.first,
-                group.identityNode.second,
-                std::format(
-                    "registration group '{}' conflicts with persisted root '{}@{}'",
-                    label,
-                    persistedIt->second.root.first,
-                    persistedIt->second.root.second)));
-        }
-        if (missingMemberIt
-            == persistedIt->second.members.end()) {
-            continue;
-        }
-        return std::unexpected(detail_::registration_error_(
-            RegistrationErrorKind::IncompleteOwnedGroup,
-            group.identityPath,
-            missingMemberIt->first,
-            missingMemberIt->second,
-            std::format(
-                "same-owner registration omits an existing member of group '{}'",
-                label)));
-    }
-
-    for (std::size_t index = 0; index < batch.headers.size(); ++index) {
-        const auto& header = batch.headers[index];
-        const auto headerPath = std::format("/headers/{}", index);
-        if (header.sourceDir.empty()) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::InvalidHeader,
-                headerPath + "/sourceDir", {}, {},
-                "registration header source directory is empty"));
-        }
-
-        auto groupIt = groups.end();
-        if (!header.group.empty()) {
-            groupIt = groups.find(header.group);
-            if (groupIt == groups.end()) {
-                return std::unexpected(detail_::registration_error_(
-                    RegistrationErrorKind::HeaderGroupNotFound,
-                    headerPath + "/group", header.group, {},
-                    std::format(
-                        "registration header group '{}' does not exist",
-                        header.group)));
-            }
-        } else if (groups.size() == 1) {
-            groupIt = groups.begin();
-        } else {
-            // More than one candidate. A recipe registering several
-            // independent targets (a program plus a library, say) makes every
-            // ungrouped node its own singleton group, so requiring exactly one
-            // candidate would reject perfectly ordinary recipes. Break the tie
-            // with the package's own target: headers shipped by package `p`
-            // belong with `p`.
-            //
-            // Only when that target resolves to exactly one group. If it is
-            // absent, or registered at versions that landed in different
-            // groups, naming it identifies no single owner and guessing would
-            // attach the headers to an arbitrary group.
-            std::string_view resolved;
-            bool spansGroups = false;
-            if (!batch.primaryTarget.empty()) {
-                for (const auto& [key, label] : nodeGroups) {
-                    if (key.first != batch.primaryTarget) continue;
-                    if (resolved.empty()) {
-                        resolved = label;
-                    } else if (resolved != label) {
-                        spansGroups = true;
-                        break;
-                    }
-                }
-            }
-            if (resolved.empty() || spansGroups) {
-                return std::unexpected(detail_::registration_error_(
-                    RegistrationErrorKind::HeaderAmbiguous,
-                    headerPath + "/group", batch.primaryTarget, {},
-                    std::format(
-                        "ungrouped registration header has {} candidate "
-                        "groups and primaryTarget '{}' {}; name the owning "
-                        "group on the header",
-                        groups.size(), batch.primaryTarget,
-                        spansGroups ? "spans several of them"
-                                    : "is not one of them")));
-            }
-            groupIt = groups.find(std::string(resolved));
-        }
-        groupIt->second.headers.push_back({
-            .sourceDir = header.sourceDir,
-            .destinationPrefix = header.destinationPrefix,
-        });
-    }
-    for (auto& [_, group] : groups) {
-        std::ranges::sort(
-            group.headers,
-            [](const HeaderAsset& lhs, const HeaderAsset& rhs) {
-                return std::tie(lhs.sourceDir, lhs.destinationPrefix)
-                    < std::tie(rhs.sourceDir, rhs.destinationPrefix);
-            });
-        group.headers.erase(
-            std::unique(
-                group.headers.begin(),
-                group.headers.end(),
-                [](const HeaderAsset& lhs, const HeaderAsset& rhs) {
-                    return lhs.sourceDir == rhs.sourceDir
-                        && lhs.destinationPrefix
-                            == rhs.destinationPrefix;
-                }),
-            group.headers.end());
-    }
-
-    // Owner-less entries this batch takes over, and the field that differed.
-    // Collected during validation and reported with the result; see the
-    // adoption comment below.
-    std::map<detail_::RegistrationExactKey, std::string> adoptedLegacy;
-
-    for (std::size_t index = 0; index < batch.nodes.size(); ++index) {
-        const auto& node = batch.nodes[index];
-        const auto infoIt = db.find(node.target);
-        if (infoIt == db.end()) continue;
-        const auto dataIt = infoIt->second.versions.find(node.version);
-        if (dataIt == infoIt->second.versions.end()) continue;
-        const auto& data = dataIt->second;
-        const auto nodePath = std::format("/nodes/{}", index);
-
-        if (data.bindingGroup) {
-            const auto& owner = *data.bindingGroup;
-            if (owner.provider != batch.provider
-                || owner.providerVersion != batch.providerVersion) {
-                return std::unexpected(detail_::registration_error_(
-                    RegistrationErrorKind::OwnershipConflict,
-                    nodePath, node.target, node.version,
-                    std::format(
-                        "exact registration is owned by '{}@{}'",
-                        owner.provider, owner.providerVersion)));
-            }
-
-            std::set<detail_::RegistrationExactKey> oldMembers;
-            for (const auto& [target, info] : db) {
-                for (const auto& [version, member] : info.versions) {
-                    if (member.bindingGroup
-                        && detail_::same_registration_group_(
-                            *member.bindingGroup, owner)) {
-                        oldMembers.emplace(target, version);
-                    }
-                }
-            }
-            const auto rootInfoIt = db.find(owner.rootTarget);
-            if (rootInfoIt != db.end()) {
-                const auto rootIt = rootInfoIt->second.versions.find(
-                    owner.rootVersion);
-                if (rootIt != rootInfoIt->second.versions.end()
-                    && rootIt->second.bindingGroup
-                    && detail_::same_registration_group_(
-                        *rootIt->second.bindingGroup, owner)) {
-                    for (const auto& [target, version] :
-                         rootIt->second.bindingMembers) {
-                        const auto memberInfoIt = db.find(target);
-                        if (memberInfoIt != db.end()
-                            && memberInfoIt->second.versions.contains(
-                                version)) {
-                            oldMembers.emplace(target, version);
-                        }
-                    }
-                }
-            }
-            for (const auto& oldMember : oldMembers) {
-                if (nodeIndexes.contains(oldMember)) continue;
-                return std::unexpected(detail_::registration_error_(
-                    RegistrationErrorKind::IncompleteOwnedGroup,
-                    nodePath, oldMember.first, oldMember.second,
-                    "same-owner registration omits an existing group member"));
-            }
-            continue;
-        }
-
-        // Owner-less entry with different contents: ADOPT it, do not refuse.
-        //
-        // This used to be RegistrationErrorKind::LegacyPayloadMismatch, whose
-        // hint told the user to uninstall the package first. Nothing owns an
-        // owner-less entry, so there is no claim to protect -- and `remove`
-        // keeps exactly these entries when another subos still references the
-        // version (#443), so the hint pointed at a door that does not open.
-        // The two ends met and the only remaining exit was hand-editing the
-        // state file (#422).
-        //
-        // Adoption is also a repair, not just an escape: the entry comes out
-        // of it OWNED (the group pass below assigns bindingGroup), so the next
-        // provider that tries to take the same name@version meets
-        // OwnershipConflict -- a protection the owner-less entry could never
-        // raise. The refusal preserved damage it could not fix; the measured
-        // case is an llvm@20.1.7 whose recorded path used Windows backslashes
-        // on Linux.
-        //
-        // The group-integrity checks below are NOT relaxed: a batch that would
-        // rewrite part of a bound group is still rejected.
-        if (auto field = detail_::legacy_payload_mismatch_(
-                node, infoIt->second, data)) {
-            adoptedLegacy.insert_or_assign(
-                detail_::RegistrationExactKey{node.target, node.version},
-                *field);
-        }
-        auto selection = resolve_binding_selection(
-            db, node.target, node.version);
-        if (!selection) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::BindingValidationFailed,
-                nodePath, selection.error().target,
-                selection.error().version,
-                selection.error().message));
-        }
-        for (const auto& [target, version] : selection->members) {
-            if (nodeIndexes.contains(
-                    detail_::RegistrationExactKey{target, version})) {
-                continue;
-            }
-            // The batch does not cover the whole legacy component.
-            //
-            // Refusing outright is right when the missing member could belong
-            // to somebody else. It is wrong when the member is plainly this
-            // package's own leftover, and then it is a trap: the component was
-            // recorded by a client on ANOTHER PLATFORM, which registered names
-            // this platform's recipe never produces. Measured on a real home,
-            // an llvm@20.1.7 registered on Windows leaves `cl`, `lib`, `link`
-            // and `rc` bound to it; on Linux the recipe emits no such nodes, so
-            // every install refused -- and `remove` refused too, for its own
-            // reasons, so nothing could move.
-            //
-            // Three conditions make the member safe to detach instead:
-            //   1. it is OWNER-LESS. Nothing claims it, so no provider's
-            //      selection is being rewritten behind its back.
-            //   2. its payload lies inside a payload this batch is
-            //      registering. That is the evidence it belongs to this
-            //      package rather than merely resembling it.
-            //
-            // Being ACTIVE is deliberately NOT a third condition. It was one at
-            // first, and it turned out to veto exactly the case this exists
-            // for: on the measured home `cl`, `lib`, `link` and `rc` are all
-            // active, so the refusal survived the fix. It also protects
-            // nothing. Detaching does not deregister the entry and does not
-            // deactivate it -- the shim still dispatches to the same place. All
-            // that changes is that the entry stops claiming membership in a
-            // release that no longer registers it, which is simply true.
-            //
-            // Detach, not delete: the entry stays in the database, only its
-            // edges to this batch go (erase_exact_registration_edges_ below
-            // drops them, since the peer side IS in the batch). What is left
-            // is a standalone owner-less record with a payload that does not
-            // resolve -- which `self doctor` already knows how to see and, at
-            // the end of its ladder, to prune. Deleting it here would make a
-            // registration silently destroy state on behalf of a repair that
-            // has its own preview and its own reporting.
-            const VData* memberData = nullptr;
-            if (const auto memberInfoIt = db.find(target);
-                memberInfoIt != db.end()) {
-                const auto memberDataIt =
-                    memberInfoIt->second.versions.find(version);
-                if (memberDataIt != memberInfoIt->second.versions.end()) {
-                    memberData = &memberDataIt->second;
-                }
-            }
-            const bool ownerLess = memberData && !memberData->bindingGroup;
-            const auto memberPath = memberData
-                ? detail_::normalized_payload_path_(memberData->path)
-                : std::string{};
-            const bool insideBatchPayload = !memberPath.empty()
-                && std::ranges::any_of(batch.nodes, [&](const auto& n) {
-                    return detail_::payload_path_covers_(
-                        detail_::normalized_payload_path_(n.path), memberPath);
-                });
-            if (ownerLess && insideBatchPayload) {
-                if (detached) detached->push_back({target, version});
-                continue;
-            }
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::IncompleteLegacyComponent,
-                nodePath, target, version,
-                "legacy component is not completely represented in batch"));
-        }
-    }
-
-    auto candidateDb = db;
-    auto candidateWorkspace = workspace;
-    auto candidateInstalled = installed;
-
-    for (const auto& [_, index] : nodeIndexes) {
-        const auto& node = batch.nodes[index];
-        auto& info = candidateDb[node.target];
-        if (info.type.empty()) info.type = node.kind;
-        if (info.filename.empty() && node.kind != "group") {
-            info.filename = node.sourceName;
-        }
-        auto& data = info.versions[node.version];
-        data.path = node.path;
-        data.kind = node.kind;
-        data.fileSrc = node.fileSrc;
-        data.fileDst = node.fileDst;
-        data.sourceName =
-            node.kind == "group" ? std::string{} : node.sourceName;
-        data.destinationName =
-            node.kind == "group" ? std::string{} : node.destinationName;
-        data.alias = node.alias;
-        data.envs = node.envs;
-        data.bindingGroup.reset();
-        data.bindingMembers.clear();
-        data.bindingMembersDeclared = false;
-        data.bindingHeaders.clear();
-        data.bindingHeadersDeclared = false;
-        data.bindingIntegrityIssues.clear();
-    }
-    std::set<detail_::RegistrationExactKey> exactNodes;
-    for (const auto& [key, _] : nodeIndexes) {
-        exactNodes.insert(key);
-    }
-    detail_::erase_exact_registration_edges_(
-        candidateDb, exactNodes);
-
-    std::vector<RegisteredMember> registered;
-    for (const auto& [_, group] : groups) {
-        // Decide activation once for the release, not once per member.
-        //
-        // Per member, a release that adds a name the previous one did not
-        // have would activate just that name: the new member goes to this
-        // release while everything else stays on the old one, and the
-        // workspace ends up spanning two of them -- the exact state the
-        // binding-group model exists to prevent, produced by install.
-        //
-        // Leaving a name alone when something already owns it is also the
-        // right answer across providers: installing gcc must not silently
-        // take `cc` away from an active llvm.
-        //
-        // But leaving the name alone is all that was ever intended, and this
-        // used to do much more than that: ANY member name being active vetoed
-        // the WHOLE group, including members nobody was contesting. Installing
-        // node while a standalone npm package held `npm` therefore activated
-        // nothing at all -- `node` and `npx`, which no other package provides,
-        // came out installed and unreachable, with no shim and no error. The
-        // user met it as `/usr/bin/env: 'node': No such file or directory`
-        // from a tool that had nothing to do with xlings.
-        //
-        // Who holds a contested name decides whether it vetoes:
-        //
-        //   same provider   -- an older release of this same package. Moving
-        //                      part of the workspace to the new release and
-        //                      leaving the rest on the old one is exactly the
-        //                      split the binding-group model exists to
-        //                      prevent, and choosing between two releases of
-        //                      one package is the user's call: `use`. Veto.
-        //   other provider  -- a different package owns that name and keeps
-        //                      it. That is ownership, not incoherence, and it
-        //                      says nothing about this release's other names.
-        //                      No veto; the contested name is skipped below.
-        //   unknown         -- an entry with no group metadata, written before
-        //                      providers were recorded. Treated as the same
-        //                      provider, so old homes keep today's behaviour.
-        const auto contested_by =
-            [&](const std::string& memberTarget)
-            -> std::optional<std::string> {
-            const auto activeIt = candidateWorkspace.find(memberTarget);
-            if (activeIt == candidateWorkspace.end()) return std::nullopt;
-            const auto dbIt = candidateDb.find(memberTarget);
-            if (dbIt == candidateDb.end()) return std::string{};
-            const auto verIt = dbIt->second.versions.find(activeIt->second);
-            if (verIt == dbIt->second.versions.end()) return std::string{};
-            if (!verIt->second.bindingGroup) return std::string{};
-            return verIt->second.bindingGroup->provider;
-        };
-
-        std::set<std::string> contested;
-        bool sameProviderContest = false;
-        for (const auto& member : group.members) {
-            const auto owner = contested_by(member.first);
-            if (!owner) continue;
-            contested.insert(member.first);
-            if (*owner == batch.provider) sameProviderContest = true;
-        }
-
-        // Is there anything left worth activating?
-        //
-        // A virtual root exists only to anchor the release its libraries
-        // belong to; there is no command behind it. Activating one writes a
-        // shim that can only print "no active version", which is issue #452:
-        // `self doctor` called the file an orphan, `--fix` deleted it, and the
-        // next install put it straight back. A group whose only uncontested
-        // members are anchors therefore stays inactive, exactly as before.
-        //
-        // Neither the path nor the kind can answer this on its own. A real
-        // anchor carries a payload path like everything else --
-        // `xim-musl-gnu-gcc` records musl-gcc's own directory, and the #452
-        // fixture's root, registered with no bindir at all, still ends up with
-        // the package install dir -- and `kind` defaults to "program" for both.
-        // So the batch's own answer (RegistrationNode::runnable, set by
-        // whoever materialised the payload) is what decides, with the kind and
-        // path as the cheap checks in front of it.
-        const bool anyRealUncontested = std::ranges::any_of(
-            group.members, [&](const auto& member) {
-                if (contested.contains(member.first)) return false;
-                const auto dbIt = candidateDb.find(member.first);
-                if (dbIt == candidateDb.end()) return false;
-                const auto verIt = dbIt->second.versions.find(member.second);
-                if (verIt == dbIt->second.versions.end()) return false;
-                if (verIt->second.path.empty()) return false;
-                if (effective_kind(dbIt->second, verIt->second) != "program") {
-                    return false;
-                }
-                const auto nodeIt = std::ranges::find_if(
-                    batch.nodes, [&](const RegistrationNode& n) {
-                        return n.target == member.first
-                            && n.version == member.second;
-                    });
-                return nodeIt == batch.nodes.end() || nodeIt->runnable;
-            });
-
-        // `contested.empty()` first, and not folded into the clause after it.
-        //
-        // The anchor guard exists to stop #452 coming back through the door
-        // the cross-provider rule opens, so it applies only to that door. A
-        // release nobody is contesting activates exactly as it always has --
-        // including a batch that is nothing but a virtual root, which is how
-        // a library-only package registers and which has to stay activated
-        // for anything to bind to it.
-        const bool activateGroup =
-            batch.useAfterInstall
-            || contested.empty()
-            || (!sameProviderContest && anyRealUncontested);
-
-        const BindingGroupRef ref{
-            .provider = batch.provider,
-            .providerVersion = batch.providerVersion,
-            .group = group.label,
-            .rootTarget = group.root.first,
-            .rootVersion = group.root.second,
-        };
-        for (const auto& [target, version] : group.members) {
-            auto& data =
-                candidateDb.at(target).versions.at(version);
-            data.bindingGroup = ref;
-            data.bindingMembers.clear();
-            data.bindingMembersDeclared = false;
-            data.bindingHeaders.clear();
-            data.bindingHeadersDeclared = false;
-            const auto adoptedIt = adoptedLegacy.find(
-                detail_::RegistrationExactKey{target, version});
-            registered.push_back({
-                .target = target,
-                .version = version,
-                .kind = data.kind,
-                .adoptedLegacy = adoptedIt != adoptedLegacy.end(),
-                .adoptedLegacyField = adoptedIt != adoptedLegacy.end()
-                    ? adoptedIt->second : std::string{},
-            });
-            auto& versions = candidateInstalled[target];
-            bool foundVersion = false;
-            std::erase_if(
-                versions,
-                [&](const std::string& installedVersion) {
-                    if (installedVersion != version) return false;
-                    if (!foundVersion) {
-                        foundVersion = true;
-                        return false;
-                    }
-                    return true;
-                });
-            if (!foundVersion) {
-                versions.push_back(version);
-            }
-            // A contested name stays with whoever holds it. `useAfterInstall`
-            // is the one exception, and it is not an exception to the rule so
-            // much as a different question: the user typed the switch, so
-            // taking the name is what they asked for.
-            if (activateGroup
-                && (batch.useAfterInstall || !contested.contains(target))) {
-                candidateWorkspace[target] = version;
-            }
-        }
-
-        auto& root =
-            candidateDb.at(group.root.first)
-                .versions.at(group.root.second);
-        root.bindingMembers = group.members;
-        root.bindingMembersDeclared = true;
-        root.bindingHeaders = group.headers;
-        root.bindingHeadersDeclared = !group.headers.empty();
-        for (const auto& [target, version] : group.members) {
-            if (target == group.root.first
-                && version == group.root.second) {
-                continue;
-            }
-            candidateDb.at(group.root.first)
-                .bindings[target][group.root.second] = version;
-            candidateDb.at(target)
-                .bindings[group.root.first][version] = group.root.second;
-        }
-    }
-
-    std::map<
-        detail_::RegistrationGroupIdentity,
-        detail_::RegistrationExactKey> candidateGroups;
-    for (const auto& [target, info] : candidateDb) {
-        for (const auto& [version, data] : info.versions) {
-            if (!data.bindingGroup) continue;
-            const auto& ref = *data.bindingGroup;
-            if (ref.provider != batch.provider
-                || ref.providerVersion != batch.providerVersion) {
-                continue;
-            }
-            candidateGroups.try_emplace(
-                detail_::registration_group_identity_(ref),
-                target, version);
-        }
-    }
-    for (const auto& [_, representative] : candidateGroups) {
-        const auto& ref =
-            *candidateDb.at(representative.first)
-                 .versions.at(representative.second)
-                 .bindingGroup;
-        auto selection = resolve_binding_selection(
-            candidateDb, representative.first, representative.second);
-        if (!selection) {
-            return std::unexpected(detail_::registration_error_(
-                RegistrationErrorKind::BindingValidationFailed,
-                "/bindingGroups/"
-                    + detail_::registration_path_token_(ref.group),
-                selection.error().target,
-                selection.error().version,
-                selection.error().message));
-        }
-    }
-
-    db.swap(candidateDb);
-    workspace.swap(candidateWorkspace);
-    installed.swap(candidateInstalled);
-    return registered;
-}
+    std::vector<DetachedLegacyMember>* detached);
 
 }  // namespace xlings::xvm
diff --git a/src/core/xvm/removal.cpp b/src/core/xvm/removal.cpp
new file mode 100644
index 00000000..30709c85
--- /dev/null
+++ b/src/core/xvm/removal.cpp
@@ -0,0 +1,395 @@
+module xlings.core.xvm.removal;
+
+import std;
+import xlings.core.log;
+import xlings.core.xvm.types;
+import xlings.core.xvm.bindings;
+import xlings.core.xvm.db;
+
+namespace xlings::xvm {
+
+bool has_usable_workspace_version(
+        const VersionDB& db,
+        const WorkspaceInstalled& installed,
+        const std::string& target) {
+    auto installedIt = installed.find(target);
+    auto targetIt = db.find(target);
+    if (installedIt == installed.end() || targetIt == db.end()) {
+        return false;
+    }
+    return std::ranges::any_of(
+        installedIt->second,
+        [&](const std::string& version) {
+            return targetIt->second.versions.contains(version);
+        });
+}
+
+std::expected<RemovalContext, RemovalError>
+snapshot_removal_context(const VersionDB& db,
+                         const std::string& target,
+                         const std::string& version) {
+    auto exactVersion =
+        resolve_exact_version_key(db, target, version);
+    if (!exactVersion) {
+        return std::unexpected(std::move(exactVersion.error()));
+    }
+    const auto& data = db.at(target).versions.at(*exactVersion);
+    auto resolveSelection = [&](const std::string& memberTarget,
+                                const std::string& memberVersion)
+        -> std::expected<BindingSelection, RemovalError> {
+        auto selection = resolve_binding_selection(
+            db, memberTarget, memberVersion);
+        if (!selection) {
+            return std::unexpected(RemovalError{
+                .kind = RemovalErrorKind::SelectionInvalid,
+                .target = selection.error().target,
+                .version = selection.error().version,
+                .message = selection.error().message,
+            });
+        }
+        return std::move(*selection);
+    };
+
+    auto firstSelection = resolveSelection(target, *exactVersion);
+    if (!firstSelection) {
+        // Removal must not depend on the release resolving.
+        //
+        // A state that cannot be resolved -- a legacy edge pointing at a
+        // version that no longer exists, say -- already blocks `use`. Letting
+        // it block `remove` as well leaves the user unable to switch *or* to
+        // take the package out: a dead end with no command that gets out of
+        // it. Reported from the field on a real installation, where
+        // `use gcc 15` and `remove gcc 15` both refused.
+        //
+        // Taking something out needs no understanding of what put it in.
+        // Fall back to the one member we are certain of -- the exact
+        // (target, version) the user named -- and let the rest of the
+        // release be whatever it is. The same reasoning keeps removal
+        // outside the xpackage spec gate in xim/installer.cppm.
+        log::warn("[xvm] {}@{} does not resolve as a release ({}); removing "
+                  "just this entry",
+                  target, *exactVersion, firstSelection.error().message);
+        BindingSelection single;
+        single.members.emplace(target, *exactVersion);
+        firstSelection = std::move(single);
+    }
+    if (!data.bindingGroup) {
+        return RemovalContext{
+            .members = std::move(firstSelection->members),
+            .hasSelection = true,
+        };
+    }
+
+    const auto& owner = *data.bindingGroup;
+    std::set<std::tuple<std::string, std::string, std::string>> groups;
+    for (const auto& [_, info] : db) {
+        for (const auto& [__, member] : info.versions) {
+            if (!member.bindingGroup
+                || member.bindingGroup->provider != owner.provider
+                || member.bindingGroup->providerVersion
+                    != owner.providerVersion) {
+                continue;
+            }
+            groups.emplace(
+                member.bindingGroup->group,
+                member.bindingGroup->rootTarget,
+                member.bindingGroup->rootVersion);
+        }
+    }
+
+    std::map<std::string, std::string> members;
+    for (const auto& [_, rootTarget, rootVersion] : groups) {
+        auto selection = resolveSelection(rootTarget, rootVersion);
+        if (!selection) {
+            return std::unexpected(std::move(selection.error()));
+        }
+        for (const auto& [memberTarget, memberVersion] :
+             selection->members) {
+            auto [it, inserted] =
+                members.emplace(memberTarget, memberVersion);
+            if (!inserted && it->second != memberVersion) {
+                return std::unexpected(RemovalError{
+                    .kind = RemovalErrorKind::SelectionInvalid,
+                    .target = memberTarget,
+                    .version = memberVersion,
+                    .message =
+                        "provider release selects conflicting member versions",
+                });
+            }
+        }
+    }
+
+    return RemovalContext{
+        .members = std::move(members),
+        .provider = owner.provider,
+        .hasSelection = true,
+    };
+}
+
+std::expected<RemovalBatchResult, RemovalError>
+apply_removal_batch(VersionDB& db, Workspace& workspace, WorkspaceInstalled& installed, const std::vector<RemovalOperation>& operations, const RemovalContext& context, const RemovalBatchOptions& options) {
+    std::vector<RemovedVersion> removals;
+    std::vector<RemovedVersion> selectedRecipeMembers;
+    std::set<std::pair<std::string, std::string>> seen;
+
+    for (const auto& operation : operations) {
+        if (operation.op == "remove_all") {
+            if (context.provider.empty()) {
+                return std::unexpected(RemovalError{
+                    .kind = RemovalErrorKind::ProviderRequired,
+                    .target = operation.name,
+                    .version = operation.version,
+                    .message =
+                        "remove_all requires a canonical provider context",
+                });
+            }
+            auto targetIt = db.find(operation.name);
+            bool matched = false;
+            if (targetIt != db.end()) {
+                for (const auto& [version, data] : targetIt->second.versions) {
+                    if (!data.bindingGroup
+                        || data.bindingGroup->provider != context.provider) {
+                        continue;
+                    }
+                    matched = true;
+                    if (seen.emplace(operation.name, version).second) {
+                        removals.push_back({
+                            .target = operation.name,
+                            .version = version,
+                        });
+                    }
+                }
+            }
+            if (!matched) {
+                return std::unexpected(RemovalError{
+                    .kind = RemovalErrorKind::ProviderVersionNotFound,
+                    .target = operation.name,
+                    .version = operation.version,
+                    .message = std::format(
+                        "target has no version owned by provider '{}'",
+                        context.provider),
+                });
+            }
+            continue;
+        }
+        if (operation.op != "remove") continue;
+
+        if (context.hasSelection) {
+            auto memberIt = context.members.find(operation.name);
+            if (memberIt == context.members.end()) {
+                // A name this release does not own is skipped, not fatal.
+                //
+                // Recipes name their removal targets unconditionally, from a
+                // static list or from whatever the payload happens to contain,
+                // and neither has to match what this platform registered.
+                // Measured on a real home: a Windows llvm payload under Linux
+                // makes `uninstall()` ask for `clang++.exe` (never registered
+                // here) and for `cc` (registered, but by gcc). Refusing either
+                // aborted the whole batch, so the package could not be removed
+                // at all -- and the install side was refusing the same records
+                // for its own reasons, which left no command that got the user
+                // out.
+                //
+                // Skipping protects strictly more than refusing did. The
+                // selection is already the authority on what may be deleted:
+                // had the release actually owned this name, it would be IN the
+                // selection and removed below. So there is no entry that
+                // refusing saved and skipping loses -- refusing only turned
+                // "one op does nothing" into "nothing happens at all".
+                //
+                // Said out loud: a recipe naming something it does not own is
+                // worth knowing about, it is just not worth stopping for.
+                if (db.contains(operation.name)) {
+                    log::warn("[xvm] recipe asked to remove '{}', which this "
+                              "release does not own — skipped",
+                              operation.name);
+                }
+                continue;
+            }
+            auto selectedVersion = resolve_exact_version_key(
+                db, operation.name, memberIt->second);
+            if (!selectedVersion) {
+                return std::unexpected(
+                    std::move(selectedVersion.error()));
+            }
+            if (!operation.version.empty()) {
+                auto recipeVersion = resolve_exact_version_key(
+                    db, operation.name, operation.version);
+                if (!recipeVersion) {
+                    return std::unexpected(
+                        std::move(recipeVersion.error()));
+                }
+                if (*recipeVersion != *selectedVersion) {
+                    return std::unexpected(RemovalError{
+                        .kind = RemovalErrorKind::VersionMismatch,
+                        .target = operation.name,
+                        .version = operation.version,
+                        .message = std::format(
+                            "recipe removal version does not match "
+                            "selected owned version '{}'",
+                            *selectedVersion),
+                    });
+                }
+            }
+            selectedRecipeMembers.push_back({
+                .target = operation.name,
+                .version = *selectedVersion,
+            });
+            continue;
+        }
+
+        std::expected<std::string, RemovalError> exactVersion =
+            std::unexpected(RemovalError{
+                .kind = RemovalErrorKind::VersionNotFound,
+                .target = operation.name,
+                .version = operation.version,
+                .message = "removal operation has no exact version",
+            });
+        if (!operation.version.empty()) {
+            exactVersion = resolve_exact_version_key(
+                db, operation.name, operation.version);
+        } else if (auto targetIt = db.find(operation.name);
+                   targetIt != db.end()
+                   && targetIt->second.versions.size() > 1) {
+            exactVersion = std::unexpected(RemovalError{
+                .kind = RemovalErrorKind::AmbiguousVersion,
+                .target = operation.name,
+                .version = operation.version,
+                .message =
+                    "versionless removal has no unique validated selection",
+            });
+        }
+        if (!exactVersion) {
+            return std::unexpected(std::move(exactVersion.error()));
+        }
+        if (seen.emplace(operation.name, *exactVersion).second) {
+            removals.push_back({
+                .target = operation.name,
+                .version = *exactVersion,
+            });
+        }
+    }
+
+    for (const auto& removal : selectedRecipeMembers) {
+        if (seen.emplace(removal.target, removal.version).second) {
+            removals.push_back(removal);
+        }
+    }
+    if (options.purgeSelection || !selectedRecipeMembers.empty()) {
+        for (const auto& [target, version] : context.members) {
+            auto exactVersion =
+                resolve_exact_version_key(db, target, version);
+            if (!exactVersion) {
+                return std::unexpected(
+                    std::move(exactVersion.error()));
+            }
+            if (seen.emplace(target, *exactVersion).second) {
+                removals.push_back({
+                    .target = target,
+                    .version = *exactVersion,
+                });
+            }
+        }
+    }
+
+    auto candidateDb = db;
+    auto candidateWorkspace = workspace;
+    auto candidateInstalled = installed;
+    std::set<std::string> touchedTargets;
+
+    for (const auto& removal : removals) {
+        auto result =
+            remove_version(candidateDb, removal.target, removal.version);
+        if (!result) {
+            return std::unexpected(std::move(result.error()));
+        }
+        touchedTargets.insert(removal.target);
+
+        if (auto installedIt = candidateInstalled.find(removal.target);
+            installedIt != candidateInstalled.end()) {
+            std::erase(installedIt->second, removal.version);
+            if (installedIt->second.empty()) {
+                candidateInstalled.erase(installedIt);
+            }
+        }
+        if (auto activeIt = candidateWorkspace.find(removal.target);
+            activeIt != candidateWorkspace.end()
+            && activeIt->second == removal.version) {
+            candidateWorkspace.erase(activeIt);
+        }
+    }
+
+    // ── Group-coherent reactivation ──────────────────────────────────
+    //
+    // Removing the active release leaves its members with no active version.
+    // Choosing a replacement per target independently is how `gcc` ends up on
+    // GCC 15 while `g++` lands on musl's 15: two targets, two searches, no
+    // shared answer. That is the mixed-toolchain state this whole model
+    // exists to prevent, reintroduced at the moment of removal.
+    //
+    // Move a whole surviving release at once or move nothing. A candidate
+    // qualifies only when every member of its group is still registered, is
+    // opted into this subos, and does not contradict an already-active
+    // version. Otherwise the group stays inactive and the user re-selects
+    // explicitly -- an inactive toolchain is a visible problem, an
+    // incoherent one is not.
+    const auto memberAvailable =
+        [&](const std::string& target, const std::string& version) {
+            auto dbIt = candidateDb.find(target);
+            if (dbIt == candidateDb.end()
+                || !dbIt->second.versions.contains(version)) {
+                return false;
+            }
+            auto installedIt = candidateInstalled.find(target);
+            if (installedIt == candidateInstalled.end()
+                || std::ranges::find(installedIt->second, version)
+                       == installedIt->second.end()) {
+                return false;
+            }
+            auto activeIt = candidateWorkspace.find(target);
+            return activeIt == candidateWorkspace.end()
+                || activeIt->second == version;
+        };
+
+    for (const auto& target : touchedTargets) {
+        if (candidateWorkspace.contains(target)) continue;
+        auto installedIt = candidateInstalled.find(target);
+        if (installedIt == candidateInstalled.end()) continue;
+
+        // Highest surviving release first, by version rather than by the
+        // order the user happened to install things in.
+        auto candidates = installedIt->second;
+        std::ranges::sort(candidates, version_key_greater);
+
+        for (const auto& candidate : candidates) {
+            auto dbIt = candidateDb.find(target);
+            if (dbIt == candidateDb.end()
+                || !dbIt->second.versions.contains(candidate)) {
+                continue;
+            }
+            auto selection =
+                resolve_binding_selection(candidateDb, target, candidate);
+            if (!selection) continue;
+            if (!std::ranges::all_of(
+                    selection->members, [&](const auto& member) {
+                        return memberAvailable(member.first, member.second);
+                    })) {
+                continue;
+            }
+            for (const auto& [memberTarget, memberVersion] :
+                 selection->members) {
+                candidateWorkspace[memberTarget] = memberVersion;
+            }
+            break;
+        }
+    }
+
+    db.swap(candidateDb);
+    workspace.swap(candidateWorkspace);
+    installed.swap(candidateInstalled);
+    return RemovalBatchResult{
+        .removed = std::move(removals),
+    };
+}
+
+}
diff --git a/src/core/xvm/removal.cppm b/src/core/xvm/removal.cppm
index 8390d8a1..c0d51e97 100644
--- a/src/core/xvm/removal.cppm
+++ b/src/core/xvm/removal.cppm
@@ -2,7 +2,6 @@ export module xlings.core.xvm.removal;
 
 import std;
 
-import xlings.core.log;
 import xlings.core.xvm.types;
 import xlings.core.xvm.bindings;
 import xlings.core.xvm.db;
@@ -37,120 +36,12 @@ struct RemovalBatchOptions {
 bool has_usable_workspace_version(
         const VersionDB& db,
         const WorkspaceInstalled& installed,
-        const std::string& target) {
-    auto installedIt = installed.find(target);
-    auto targetIt = db.find(target);
-    if (installedIt == installed.end() || targetIt == db.end()) {
-        return false;
-    }
-    return std::ranges::any_of(
-        installedIt->second,
-        [&](const std::string& version) {
-            return targetIt->second.versions.contains(version);
-        });
-}
+        const std::string& target);
 
 std::expected<RemovalContext, RemovalError>
 snapshot_removal_context(const VersionDB& db,
                          const std::string& target,
-                         const std::string& version) {
-    auto exactVersion =
-        resolve_exact_version_key(db, target, version);
-    if (!exactVersion) {
-        return std::unexpected(std::move(exactVersion.error()));
-    }
-    const auto& data = db.at(target).versions.at(*exactVersion);
-    auto resolveSelection = [&](const std::string& memberTarget,
-                                const std::string& memberVersion)
-        -> std::expected<BindingSelection, RemovalError> {
-        auto selection = resolve_binding_selection(
-            db, memberTarget, memberVersion);
-        if (!selection) {
-            return std::unexpected(RemovalError{
-                .kind = RemovalErrorKind::SelectionInvalid,
-                .target = selection.error().target,
-                .version = selection.error().version,
-                .message = selection.error().message,
-            });
-        }
-        return std::move(*selection);
-    };
-
-    auto firstSelection = resolveSelection(target, *exactVersion);
-    if (!firstSelection) {
-        // Removal must not depend on the release resolving.
-        //
-        // A state that cannot be resolved -- a legacy edge pointing at a
-        // version that no longer exists, say -- already blocks `use`. Letting
-        // it block `remove` as well leaves the user unable to switch *or* to
-        // take the package out: a dead end with no command that gets out of
-        // it. Reported from the field on a real installation, where
-        // `use gcc 15` and `remove gcc 15` both refused.
-        //
-        // Taking something out needs no understanding of what put it in.
-        // Fall back to the one member we are certain of -- the exact
-        // (target, version) the user named -- and let the rest of the
-        // release be whatever it is. The same reasoning keeps removal
-        // outside the xpackage spec gate in xim/installer.cppm.
-        log::warn("[xvm] {}@{} does not resolve as a release ({}); removing "
-                  "just this entry",
-                  target, *exactVersion, firstSelection.error().message);
-        BindingSelection single;
-        single.members.emplace(target, *exactVersion);
-        firstSelection = std::move(single);
-    }
-    if (!data.bindingGroup) {
-        return RemovalContext{
-            .members = std::move(firstSelection->members),
-            .hasSelection = true,
-        };
-    }
-
-    const auto& owner = *data.bindingGroup;
-    std::set<std::tuple<std::string, std::string, std::string>> groups;
-    for (const auto& [_, info] : db) {
-        for (const auto& [__, member] : info.versions) {
-            if (!member.bindingGroup
-                || member.bindingGroup->provider != owner.provider
-                || member.bindingGroup->providerVersion
-                    != owner.providerVersion) {
-                continue;
-            }
-            groups.emplace(
-                member.bindingGroup->group,
-                member.bindingGroup->rootTarget,
-                member.bindingGroup->rootVersion);
-        }
-    }
-
-    std::map<std::string, std::string> members;
-    for (const auto& [_, rootTarget, rootVersion] : groups) {
-        auto selection = resolveSelection(rootTarget, rootVersion);
-        if (!selection) {
-            return std::unexpected(std::move(selection.error()));
-        }
-        for (const auto& [memberTarget, memberVersion] :
-             selection->members) {
-            auto [it, inserted] =
-                members.emplace(memberTarget, memberVersion);
-            if (!inserted && it->second != memberVersion) {
-                return std::unexpected(RemovalError{
-                    .kind = RemovalErrorKind::SelectionInvalid,
-                    .target = memberTarget,
-                    .version = memberVersion,
-                    .message =
-                        "provider release selects conflicting member versions",
-                });
-            }
-        }
-    }
-
-    return RemovalContext{
-        .members = std::move(members),
-        .provider = owner.provider,
-        .hasSelection = true,
-    };
-}
+                         const std::string& version);
 
 std::expected<RemovalBatchResult, RemovalError>
 apply_removal_batch(VersionDB& db,
@@ -158,269 +49,6 @@ apply_removal_batch(VersionDB& db,
                     WorkspaceInstalled& installed,
                     const std::vector<RemovalOperation>& operations,
                     const RemovalContext& context,
-                    const RemovalBatchOptions& options = {}) {
-    std::vector<RemovedVersion> removals;
-    std::vector<RemovedVersion> selectedRecipeMembers;
-    std::set<std::pair<std::string, std::string>> seen;
-
-    for (const auto& operation : operations) {
-        if (operation.op == "remove_all") {
-            if (context.provider.empty()) {
-                return std::unexpected(RemovalError{
-                    .kind = RemovalErrorKind::ProviderRequired,
-                    .target = operation.name,
-                    .version = operation.version,
-                    .message =
-                        "remove_all requires a canonical provider context",
-                });
-            }
-            auto targetIt = db.find(operation.name);
-            bool matched = false;
-            if (targetIt != db.end()) {
-                for (const auto& [version, data] : targetIt->second.versions) {
-                    if (!data.bindingGroup
-                        || data.bindingGroup->provider != context.provider) {
-                        continue;
-                    }
-                    matched = true;
-                    if (seen.emplace(operation.name, version).second) {
-                        removals.push_back({
-                            .target = operation.name,
-                            .version = version,
-                        });
-                    }
-                }
-            }
-            if (!matched) {
-                return std::unexpected(RemovalError{
-                    .kind = RemovalErrorKind::ProviderVersionNotFound,
-                    .target = operation.name,
-                    .version = operation.version,
-                    .message = std::format(
-                        "target has no version owned by provider '{}'",
-                        context.provider),
-                });
-            }
-            continue;
-        }
-        if (operation.op != "remove") continue;
-
-        if (context.hasSelection) {
-            auto memberIt = context.members.find(operation.name);
-            if (memberIt == context.members.end()) {
-                // A name this release does not own is skipped, not fatal.
-                //
-                // Recipes name their removal targets unconditionally, from a
-                // static list or from whatever the payload happens to contain,
-                // and neither has to match what this platform registered.
-                // Measured on a real home: a Windows llvm payload under Linux
-                // makes `uninstall()` ask for `clang++.exe` (never registered
-                // here) and for `cc` (registered, but by gcc). Refusing either
-                // aborted the whole batch, so the package could not be removed
-                // at all -- and the install side was refusing the same records
-                // for its own reasons, which left no command that got the user
-                // out.
-                //
-                // Skipping protects strictly more than refusing did. The
-                // selection is already the authority on what may be deleted:
-                // had the release actually owned this name, it would be IN the
-                // selection and removed below. So there is no entry that
-                // refusing saved and skipping loses -- refusing only turned
-                // "one op does nothing" into "nothing happens at all".
-                //
-                // Said out loud: a recipe naming something it does not own is
-                // worth knowing about, it is just not worth stopping for.
-                if (db.contains(operation.name)) {
-                    log::warn("[xvm] recipe asked to remove '{}', which this "
-                              "release does not own — skipped",
-                              operation.name);
-                }
-                continue;
-            }
-            auto selectedVersion = resolve_exact_version_key(
-                db, operation.name, memberIt->second);
-            if (!selectedVersion) {
-                return std::unexpected(
-                    std::move(selectedVersion.error()));
-            }
-            if (!operation.version.empty()) {
-                auto recipeVersion = resolve_exact_version_key(
-                    db, operation.name, operation.version);
-                if (!recipeVersion) {
-                    return std::unexpected(
-                        std::move(recipeVersion.error()));
-                }
-                if (*recipeVersion != *selectedVersion) {
-                    return std::unexpected(RemovalError{
-                        .kind = RemovalErrorKind::VersionMismatch,
-                        .target = operation.name,
-                        .version = operation.version,
-                        .message = std::format(
-                            "recipe removal version does not match "
-                            "selected owned version '{}'",
-                            *selectedVersion),
-                    });
-                }
-            }
-            selectedRecipeMembers.push_back({
-                .target = operation.name,
-                .version = *selectedVersion,
-            });
-            continue;
-        }
-
-        std::expected<std::string, RemovalError> exactVersion =
-            std::unexpected(RemovalError{
-                .kind = RemovalErrorKind::VersionNotFound,
-                .target = operation.name,
-                .version = operation.version,
-                .message = "removal operation has no exact version",
-            });
-        if (!operation.version.empty()) {
-            exactVersion = resolve_exact_version_key(
-                db, operation.name, operation.version);
-        } else if (auto targetIt = db.find(operation.name);
-                   targetIt != db.end()
-                   && targetIt->second.versions.size() > 1) {
-            exactVersion = std::unexpected(RemovalError{
-                .kind = RemovalErrorKind::AmbiguousVersion,
-                .target = operation.name,
-                .version = operation.version,
-                .message =
-                    "versionless removal has no unique validated selection",
-            });
-        }
-        if (!exactVersion) {
-            return std::unexpected(std::move(exactVersion.error()));
-        }
-        if (seen.emplace(operation.name, *exactVersion).second) {
-            removals.push_back({
-                .target = operation.name,
-                .version = *exactVersion,
-            });
-        }
-    }
-
-    for (const auto& removal : selectedRecipeMembers) {
-        if (seen.emplace(removal.target, removal.version).second) {
-            removals.push_back(removal);
-        }
-    }
-    if (options.purgeSelection || !selectedRecipeMembers.empty()) {
-        for (const auto& [target, version] : context.members) {
-            auto exactVersion =
-                resolve_exact_version_key(db, target, version);
-            if (!exactVersion) {
-                return std::unexpected(
-                    std::move(exactVersion.error()));
-            }
-            if (seen.emplace(target, *exactVersion).second) {
-                removals.push_back({
-                    .target = target,
-                    .version = *exactVersion,
-                });
-            }
-        }
-    }
-
-    auto candidateDb = db;
-    auto candidateWorkspace = workspace;
-    auto candidateInstalled = installed;
-    std::set<std::string> touchedTargets;
-
-    for (const auto& removal : removals) {
-        auto result =
-            remove_version(candidateDb, removal.target, removal.version);
-        if (!result) {
-            return std::unexpected(std::move(result.error()));
-        }
-        touchedTargets.insert(removal.target);
-
-        if (auto installedIt = candidateInstalled.find(removal.target);
-            installedIt != candidateInstalled.end()) {
-            std::erase(installedIt->second, removal.version);
-            if (installedIt->second.empty()) {
-                candidateInstalled.erase(installedIt);
-            }
-        }
-        if (auto activeIt = candidateWorkspace.find(removal.target);
-            activeIt != candidateWorkspace.end()
-            && activeIt->second == removal.version) {
-            candidateWorkspace.erase(activeIt);
-        }
-    }
-
-    // ── Group-coherent reactivation ──────────────────────────────────
-    //
-    // Removing the active release leaves its members with no active version.
-    // Choosing a replacement per target independently is how `gcc` ends up on
-    // GCC 15 while `g++` lands on musl's 15: two targets, two searches, no
-    // shared answer. That is the mixed-toolchain state this whole model
-    // exists to prevent, reintroduced at the moment of removal.
-    //
-    // Move a whole surviving release at once or move nothing. A candidate
-    // qualifies only when every member of its group is still registered, is
-    // opted into this subos, and does not contradict an already-active
-    // version. Otherwise the group stays inactive and the user re-selects
-    // explicitly -- an inactive toolchain is a visible problem, an
-    // incoherent one is not.
-    const auto memberAvailable =
-        [&](const std::string& target, const std::string& version) {
-            auto dbIt = candidateDb.find(target);
-            if (dbIt == candidateDb.end()
-                || !dbIt->second.versions.contains(version)) {
-                return false;
-            }
-            auto installedIt = candidateInstalled.find(target);
-            if (installedIt == candidateInstalled.end()
-                || std::ranges::find(installedIt->second, version)
-                       == installedIt->second.end()) {
-                return false;
-            }
-            auto activeIt = candidateWorkspace.find(target);
-            return activeIt == candidateWorkspace.end()
-                || activeIt->second == version;
-        };
-
-    for (const auto& target : touchedTargets) {
-        if (candidateWorkspace.contains(target)) continue;
-        auto installedIt = candidateInstalled.find(target);
-        if (installedIt == candidateInstalled.end()) continue;
-
-        // Highest surviving release first, by version rather than by the
-        // order the user happened to install things in.
-        auto candidates = installedIt->second;
-        std::ranges::sort(candidates, version_key_greater);
-
-        for (const auto& candidate : candidates) {
-            auto dbIt = candidateDb.find(target);
-            if (dbIt == candidateDb.end()
-                || !dbIt->second.versions.contains(candidate)) {
-                continue;
-            }
-            auto selection =
-                resolve_binding_selection(candidateDb, target, candidate);
-            if (!selection) continue;
-            if (!std::ranges::all_of(
-                    selection->members, [&](const auto& member) {
-                        return memberAvailable(member.first, member.second);
-                    })) {
-                continue;
-            }
-            for (const auto& [memberTarget, memberVersion] :
-                 selection->members) {
-                candidateWorkspace[memberTarget] = memberVersion;
-            }
-            break;
-        }
-    }
-
-    db.swap(candidateDb);
-    workspace.swap(candidateWorkspace);
-    installed.swap(candidateInstalled);
-    return RemovalBatchResult{
-        .removed = std::move(removals),
-    };
-}
+                    const RemovalBatchOptions& options = {});
 
 }  // namespace xlings::xvm
diff --git a/src/core/xvm/shim.cpp b/src/core/xvm/shim.cpp
new file mode 100644
index 00000000..d827e90f
--- /dev/null
+++ b/src/core/xvm/shim.cpp
@@ -0,0 +1,622 @@
+module;
+
+#include <cstdlib>
+
+#if defined(__linux__) || defined(__APPLE__)
+#include <unistd.h>
+#endif
+
+module xlings.core.xvm.shim;
+
+import std;
+import xlings.libs.json;
+import xlings.core.config;
+import xlings.core.log;
+import xlings.platform;
+import xlings.core.xvm.types;
+import xlings.core.xvm.db;
+
+namespace xlings::xvm {
+
+bool is_xlings_binary(std::string_view name) {
+    return name == "xlings";
+}
+
+std::string extract_program_name(const char* argv0) {
+    auto p = std::filesystem::path(argv0);
+    return p.stem().string();
+}
+
+bool is_home_root(const std::filesystem::path& dir) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    if (!fs::is_regular_file(dir / ".xlings.json", ec)) return false;
+    constexpr std::string_view bin_name =
+        (platform::OS_NAME == "windows") ? "xlings.exe" : "xlings";
+    if (!fs::exists(dir / "bin" / bin_name, ec)) return false;
+    if (!fs::is_directory(dir / "subos", ec)) return false;
+    return true;
+}
+
+std::optional<std::filesystem::path>
+resolve_owner_home(const std::filesystem::path& invoked) {
+    namespace fs = std::filesystem;
+
+    auto walk_up = [](fs::path p) -> std::optional<fs::path> {
+        std::error_code ec;
+        auto canon = fs::weakly_canonical(p, ec);
+        if (!ec && !canon.empty()) p = canon;
+        for (auto dir = p.parent_path(); !dir.empty();) {
+            if (is_home_root(dir)) return dir;
+            auto parent = dir.parent_path();
+            if (parent == dir) break;
+            dir = parent;
+        }
+        return std::nullopt;
+    };
+
+    if (invoked.has_parent_path() && !invoked.parent_path().empty()) {
+        std::error_code ec;
+        auto abs = fs::absolute(invoked, ec);
+        if (!ec) {
+            if (auto h = walk_up(abs)) return h;
+        }
+    }
+
+    auto exe = platform::get_executable_path();
+    if (!exe.empty()) {
+        if (auto h = walk_up(exe)) return h;
+    }
+    return std::nullopt;
+}
+
+bool home_knows_program(const std::filesystem::path& home,
+                        const std::string& program) {
+    namespace fs = std::filesystem;
+    std::error_code ec;
+    auto cfg = home / ".xlings.json";
+    if (!fs::is_regular_file(cfg, ec)) return false;
+
+    // Distinguish "unreadable due to ownership" from "genuinely not
+    // registered". A sudo-installed home is root-owned; a later non-root
+    // invocation can't read its .xlings.json and would otherwise get a
+    // misleading "<program>: not installed" instead of a permissions hint.
+    if (std::ifstream probe(cfg, std::ios::binary); !probe.is_open()) {
+        log::warn("[xlings] cannot read {} (permission denied)",
+                  Config::display_path(cfg));
+        log::warn("  this home may be owned by another user — avoid mixing "
+                  "sudo and non-sudo xlings on the same home");
+        return false;
+    }
+
+    try {
+        auto content = platform::read_file_to_string(cfg.string());
+        auto j = nlohmann::json::parse(content, nullptr, false);
+        if (j.is_discarded() || !j.is_object()) return false;
+        if (!j.contains("versions") || !j["versions"].is_object()) return false;
+        const auto& versions = j["versions"];
+
+        auto has_versions = [](const nlohmann::json& e) {
+            return e.is_object() && e.contains("versions")
+                && e["versions"].is_object() && !e["versions"].empty();
+        };
+
+        if (versions.contains(program) && has_versions(versions[program]))
+            return true;
+
+        // The shim file name may differ from the DB key (VInfo::filename).
+        for (auto it = versions.begin(); it != versions.end(); ++it) {
+            const auto& e = it.value();
+            if (!e.is_object()) continue;
+            if (!e.contains("filename") || !e["filename"].is_string()) continue;
+            auto fn = e["filename"].get<std::string>();
+            if (!fn.empty() && fs::path(fn).stem().string() == program
+                && has_versions(e)) {
+                return true;
+            }
+        }
+    } catch (...) {
+        return false;
+    }
+    return false;
+}
+
+std::optional<std::filesystem::path>
+resolve_dispatch_home(const std::string& program, const char* argv0) {
+    namespace fs = std::filesystem;
+
+    auto env_or_empty = [](const char* key) -> std::string {
+        const char* v = std::getenv(key);
+        return v ? std::string(v) : std::string();
+    };
+
+    auto mode = env_or_empty("XLINGS_SHIM_ANCHOR");
+    if (mode == "0" || mode == "legacy" || mode == "off") {
+        log::debug("shim home: anchoring disabled (XLINGS_SHIM_ANCHOR={})", mode);
+        return std::nullopt;
+    }
+
+    auto owner = resolve_owner_home(fs::path(argv0 ? argv0 : ""));
+    auto envHomeStr = env_or_empty("XLINGS_HOME");
+    fs::path envHome = envHomeStr.empty() ? fs::path{} : fs::path(envHomeStr);
+
+    auto same = [](const fs::path& a, const fs::path& b) {
+        if (a.empty() || b.empty()) return false;
+        std::error_code ec;
+        auto ca = fs::weakly_canonical(a, ec);
+        std::error_code ec2;
+        auto cb = fs::weakly_canonical(b, ec2);
+        return (ec || ec2) ? (a == b) : (ca == cb);
+    };
+
+    // hop 1: owner home (the shim's own home) — the contract.
+    if (owner && home_knows_program(*owner, program)) {
+        if (!envHome.empty() && !same(*owner, envHome)
+            && home_knows_program(envHome, program)) {
+            log::warn("shim '{}' owned by {} is also resolvable in XLINGS_HOME={}; "
+                      "using the owner home (env-based shim switching is deprecated "
+                      "— put that home's subos bin on PATH instead)",
+                      program, owner->string(), envHome.string());
+        }
+        log::debug("shim home: owner={} (hop 1)", owner->string());
+        return owner;
+    }
+
+    // hop 2: env XLINGS_HOME — DEPRECATED compat fallback ("borrowing").
+    if (!envHome.empty() && !same(owner.value_or(fs::path{}), envHome)
+        && home_knows_program(envHome, program)) {
+        log::warn("shim '{}' is not installed in its owning home{}; falling back "
+                  "to XLINGS_HOME={} (deprecated, will be removed in a future "
+                  "release)",
+                  program,
+                  owner ? (" " + owner->string()) : std::string(""),
+                  envHome.string());
+        log::debug("shim home: env={} (hop 2)", envHome.string());
+        return envHome;
+    }
+
+    // hop 3: default ~/.xlings — covers orphan shims copied out of a home.
+    fs::path defaultHome = fs::path(platform::get_home_dir()) / ".xlings";
+    if (!same(owner.value_or(fs::path{}), defaultHome)
+        && !same(envHome, defaultHome)
+        && home_knows_program(defaultHome, program)) {
+        log::debug("shim home: default={} (hop 3)", defaultHome.string());
+        return defaultHome;
+    }
+
+    // No candidate knows the program: bind to the owner so the error is
+    // reported against the home this shim belongs to; otherwise leave
+    // Config's legacy resolution (env/default) in place.
+    if (owner) {
+        log::debug("shim home: owner={} (no candidate knows '{}')",
+                   owner->string(), program);
+        return owner;
+    }
+    return std::nullopt;
+}
+
+std::filesystem::path resolve_executable(const std::string& program_name,
+                                         const std::string& path,
+                                         const std::string& xlings_home) {
+    namespace fs = std::filesystem;
+
+    auto expanded = expand_path(path, xlings_home);
+    auto base = fs::path(expanded);
+
+    // Try direct: path/program_name, then path/bin/program_name
+    auto candidate1 = base / program_name;
+    if (fs::exists(candidate1)) return candidate1;
+    auto candidate2 = base / "bin" / program_name;
+    if (fs::exists(candidate2)) return candidate2;
+
+#if defined(_WIN32)
+    // Windows: try .exe / .bat / .cmd (bare name already tried above)
+    constexpr std::string_view win_exts[] = {".exe", ".bat", ".cmd"};
+    for (auto ext : win_exts) {
+        auto p1 = base / (program_name + std::string(ext));
+        if (fs::exists(p1)) return p1;
+        auto p2 = base / "bin" / (program_name + std::string(ext));
+        if (fs::exists(p2)) return p2;
+    }
+#endif
+
+    return {};
+}
+
+AliasResolution resolve_alias_program(const std::string& program_name,
+                                      const std::string& path,
+                                      const std::string& xlings_home,
+                                      const std::filesystem::path& subos_bin,
+                                      std::string_view searchPath) {
+    namespace fs = std::filesystem;
+
+    if (program_name.empty()) return {};
+
+    // An absolute alias is not searched for; it either exists or it does not.
+    // It is NOT a host command -- a recipe that pins a full path into its own
+    // payload store writes one, and calling that "satisfied by the host" gets
+    // the portability question exactly backwards.
+    if (fs::path(program_name).is_absolute()) {
+        std::error_code ec;
+        if (fs::exists(program_name, ec)) {
+            return {AliasOrigin::Absolute, fs::path(program_name)};
+        }
+        return {};
+    }
+
+    if (auto own = resolve_executable(program_name, path, xlings_home);
+        !own.empty()) {
+        return {AliasOrigin::Payload, std::move(own)};
+    }
+
+#if defined(_WIN32)
+    constexpr std::string_view exts[] = {"", ".exe", ".bat", ".cmd"};
+#else
+    constexpr std::string_view exts[] = {""};
+#endif
+
+    const auto probe = [&](const fs::path& dir) -> fs::path {
+        if (dir.empty()) return {};
+        for (auto ext : exts) {
+            auto candidate = dir / (program_name + std::string(ext));
+            std::error_code ec;
+            if (fs::exists(candidate, ec) && !fs::is_directory(candidate, ec)) {
+                return candidate;
+            }
+        }
+        return {};
+    };
+
+    if (auto sibling = probe(subos_bin); !sibling.empty()) {
+        return {AliasOrigin::SubosBin, std::move(sibling)};
+    }
+
+    std::size_t start = 0;
+    while (start <= searchPath.size() && !searchPath.empty()) {
+        auto end = searchPath.find(platform::PATH_SEPARATOR, start);
+        auto part = searchPath.substr(
+            start, end == std::string_view::npos ? std::string_view::npos
+                                                 : end - start);
+        if (!part.empty()) {
+            if (auto hit = probe(fs::path(part)); !hit.empty()) {
+                return {AliasOrigin::SystemPath, std::move(hit)};
+            }
+        }
+        if (end == std::string_view::npos) break;
+        start = end + 1;
+    }
+
+    return {};
+}
+
+std::optional<std::string> merge_shim_env_value(const std::string& expanded,
+                                                const std::string& existing) {
+    if (existing.empty()) return expanded;
+    std::size_t start = 0;
+    while (start <= existing.size()) {
+        auto end = existing.find(platform::PATH_SEPARATOR, start);
+        auto part = existing.substr(start, end == std::string::npos
+                                           ? std::string::npos : end - start);
+        if (part == expanded) return std::nullopt;  // already present
+        if (end == std::string::npos) break;
+        start = end + 1;
+    }
+    return expanded + platform::PATH_SEPARATOR + existing;
+}
+
+std::optional<std::string> setup_envs(const VData& vdata,
+                const std::string& resolved_path,
+                const std::string& xlings_home,
+                const std::string& active_subos_dir) {
+    // The subos library farm, declared by the layer that resolved WHICH subos
+    // this process runs in.
+    //
+    // The same contract the shell profile, `subos spawn` and `--sandbox` each
+    // declare (E2a, 2026.8.11.1) -- but those three cover entry into a subos,
+    // and a shim is the fourth way a program starts: `gcc` invoked from a
+    // plain shell that never sourced the profile, or from a build system that
+    // sanitises the environment. The `ld` wrapper in the binutils payload
+    // reads this variable, so a path where nobody sets it is a path where the
+    // wrapper silently does nothing -- which is indistinguishable from it
+    // working.
+    //
+    // Set unconditionally rather than only-if-absent: this layer resolved the
+    // ACTIVE subos for this process (project > env > home), and the profile's
+    // value is the home's default, which is the wrong one inside a project
+    // subos. The most specific answerer wins.
+    if (!active_subos_dir.empty()) {
+        platform::set_env_variable(
+            "XLINGS_SUBOS_LIB",
+            (std::filesystem::path(active_subos_dir) / "lib").string());
+    }
+
+    // Set envs from VData
+    for (auto& [key, value] : vdata.envs) {
+        // Same hazard as the alias: an env value recorded at install time can
+        // name that install's subos. Re-point it at the active one.
+        auto expanded = expand_subos_placeholder(
+            normalize_subos_paths(expand_path(value, xlings_home),
+                                  xlings_home, active_subos_dir),
+            active_subos_dir);
+        if (auto vanishing = vanishing_xlings_reference(expanded)) {
+            return vanishing;
+        }
+        auto existing = std::string(std::getenv(key.c_str()) ? std::getenv(key.c_str()) : "");
+        if (auto merged = merge_shim_env_value(expanded, existing))
+            platform::set_env_variable(key, *merged);
+    }
+
+    // Prepend resolved program's directory to PATH
+    if (!resolved_path.empty()) {
+        auto dir = std::filesystem::path(resolved_path).parent_path().string();
+        auto existing_path = std::string(std::getenv("PATH") ? std::getenv("PATH") : "");
+        auto bin_dir = Config::paths().binDir.string();
+        std::string new_path;
+        if (!dir.empty()) new_path = dir;
+        if (!bin_dir.empty()) {
+            if (!new_path.empty()) new_path += platform::PATH_SEPARATOR;
+            new_path += bin_dir;
+        }
+        if (!existing_path.empty()) {
+            if (!new_path.empty()) new_path += platform::PATH_SEPARATOR;
+            new_path += existing_path;
+        }
+        platform::set_env_variable("PATH", new_path);
+    }
+    return std::nullopt;
+}
+
+void report_vanishing_reference_(const std::string& program_name,
+                                 const std::string& name) {
+    if (name == "XLINGS_DYNAMIC_SUBOS_DIR") {
+        log::error("xlings: '{}' needs the active subos, and none resolved",
+                   program_name);
+        log::error("  hint: xlings subos list   (then `xlings subos use <name>`)");
+        return;
+    }
+    log::error("xlings: '{}' is registered against '{}', which this client "
+               "does not provide", program_name, name);
+    log::error("  this record was written by a newer index than the xlings "
+               "running it");
+    log::error("  hint: xlings self update   (entry: {})",
+               std::string(Info::VERSION));
+}
+
+int shim_dispatch(const std::string& program_name, int argc, char* argv[]) {
+    // Recursion guard: detect infinite shim re-invocation
+    constexpr int MAX_SHIM_DEPTH = 8;
+    constexpr int FALLBACK_DEPTH = MAX_SHIM_DEPTH + 2;
+    auto depth_str = std::getenv("XLINGS_SHIM_DEPTH");
+    int depth = depth_str ? std::atoi(depth_str) : 0;
+    if (depth >= FALLBACK_DEPTH) {
+        log::error("xlings: shim recursion detected for '{}' (depth={})", program_name, depth);
+        log::error("  hint: the real '{}' binary may not be installed", program_name);
+        return 1;
+    }
+
+    log::debug("shim dispatch: program={}, depth={}", program_name, depth);
+
+    auto& cfg = Config::paths();
+    auto xlings_home = cfg.homeDir.string();
+    // The one resolution point that is correct in all three selection modes
+    // (project subos > XLINGS_ACTIVE_SUBOS > the home's activeSubos field).
+    auto active_subos_dir = Config::xvm_artifact_subos_dir().string();
+
+    // Get effective workspace (project > subos > global)
+    auto workspace = Config::effective_workspace();
+
+    // Look up active version for this program
+    auto version = get_active_version(workspace, program_name);
+    auto db = Config::versions();
+    if (version.empty()) {
+        // Tri-state diagnostic, scoped to the CURRENT subos's installed[]
+        // (NOT the global versions DB — pre-0.4.19 the "available" list
+        // showed every version every subos had ever installed, which was
+        // misleading from inside a fresh / pruned subos):
+        //
+        //   * installed[] empty + global DB empty       → never installed
+        //   * installed[] empty + global DB has entries → installed in
+        //     another subos, current subos has no view of it (suggest
+        //     `xlings install` — payload is shared, but this subos
+        //     needs to opt in)
+        //   * installed[] non-empty                     → some versions
+        //     are opted-in but no active pointer; list THOSE versions
+        //     and tell the user to `xlings use` one of them
+        const auto& subos_installed = Config::workspace_installed();
+        std::vector<std::string> here;
+        if (auto it = subos_installed.find(program_name); it != subos_installed.end()) {
+            here = it->second;
+        }
+
+        if (here.empty()) {
+            auto global_all = get_all_versions(db, program_name);
+            if (global_all.empty()) {
+                log::error("xlings: '{}' is not installed", program_name);
+                log::error("  hint: xlings install {}", program_name);
+            } else {
+                log::error("xlings: '{}' is not installed in current subos", program_name);
+                log::error("  hint: xlings install {}", program_name);
+            }
+        } else {
+            log::error("xlings: no active version of '{}' in current subos", program_name);
+            std::string avail;
+            for (auto& v : here) {
+                if (!avail.empty()) avail += " ";
+                avail += v;
+            }
+            log::error("  available: {}", avail);
+            log::error("  hint: xlings use {} <version>", program_name);
+        }
+        return 1;
+    }
+
+    // Resolve version (fuzzy match)
+    auto resolved_version = match_version(db, program_name, version);
+    if (resolved_version.empty()) {
+        log::error("xlings: version '{}' not found for '{}'", version, program_name);
+        auto all = get_all_versions(db, program_name);
+        if (!all.empty()) {
+            std::string avail = "  available:";
+            for (auto& v : all) avail += " " + v;
+            log::error("{}", avail);
+        }
+        return 1;
+    }
+
+    log::debug("resolved version: {} -> {}", version, resolved_version);
+
+    auto vdata = get_vdata(db, program_name, resolved_version);
+    if (!vdata) {
+        log::error("xlings: no path info for {} {}", program_name, resolved_version);
+        return 1;
+    }
+
+    // Each target (including binding targets) has its own workspace version
+    // and vdata, so use program_name directly for execution.
+    std::string exec_name = program_name;
+
+    if (!vdata->alias.empty()) {
+        // Env alias fallback: prepend bindir to PATH, run alias via system
+        auto expanded_path = expand_path(vdata->path, xlings_home);
+        auto bin_path = (std::filesystem::path(expanded_path) / "bin").string();
+        auto existing_path = std::string(std::getenv("PATH") ? std::getenv("PATH") : "");
+        auto cfg_bin = Config::paths().binDir.string();
+
+        std::string new_path;
+        if (!expanded_path.empty() && std::filesystem::exists(expanded_path))
+            new_path = expanded_path;
+        if (std::filesystem::exists(bin_path)) {
+            if (!new_path.empty()) new_path += platform::PATH_SEPARATOR;
+            new_path += bin_path;
+        }
+        if (!cfg_bin.empty()) {
+            if (!new_path.empty()) new_path += platform::PATH_SEPARATOR;
+            new_path += cfg_bin;
+        }
+        if (!existing_path.empty()) {
+            if (!new_path.empty()) new_path += platform::PATH_SEPARATOR;
+            new_path += existing_path;
+        }
+        platform::set_env_variable("PATH", new_path);
+
+        // Setup custom envs
+        if (auto vanishing =
+                setup_envs(*vdata, "", xlings_home, active_subos_dir)) {
+            report_vanishing_reference_(program_name, *vanishing);
+            return 1;
+        }
+
+        // COMPAT: an alias written before the placeholder existed carries the
+        // absolute path of whatever subos was active at install time. Re-point
+        // it at the subos THIS process resolves to -- project, env and global
+        // selection all land on xvm_artifact_subos_dir(). A record written by
+        // a current xlings has no such path, so this is a no-op for it.
+        //
+        // Kept for records written before the placeholder existed. New
+        // records carry `${XLINGS_SUBOS}` and have no path here to rewrite.
+        std::string alias_cmd = normalize_subos_paths(
+            vdata->alias[0], xlings_home, active_subos_dir);
+
+        // The record stored a marker rather than one subos's answer, and this
+        // is the only layer that knows which subos this process resolved to
+        // -- which is exactly why the answer was not in the database.
+        alias_cmd = expand_subos_placeholder(alias_cmd, active_subos_dir);
+
+        // Refuse rather than hand a vanishing reference to the shell.
+        //
+        // This is the guard the 0.4.51 incident needed: that client predated
+        // the marker, passed it through, and `sh` turned `--sysroot=<marker>`
+        // into `--sysroot=` -- a valid flag meaning "use the host root". Every
+        // build in the home silently stopped being self-contained and the
+        // first visible symptom was a missing crt1.o three layers down.
+        //
+        // Checked AFTER setup_envs, so a variable the alias legitimately
+        // defers to (`${XLINGS_SUBOS_LIB}`) has already been exported and does
+        // not trip this.
+        if (auto vanishing = vanishing_xlings_reference(alias_cmd)) {
+            report_vanishing_reference_(program_name, *vanishing);
+            return 1;
+        }
+
+        if (depth >= MAX_SHIM_DEPTH) {
+            // Fallback: resolve alias command to full path to break recursion
+            auto expanded_pkg = expand_path(vdata->path, xlings_home);
+            log::debug("shim alias fallback (depth={}): program={}, alias='{}'", depth, program_name, alias_cmd);
+            log::debug("  package path: {}", expanded_pkg);
+            log::debug("  PATH: {}", std::getenv("PATH") ? std::getenv("PATH") : "(null)");
+
+            auto first_space = alias_cmd.find(' ');
+            std::string alias_prog = (first_space != std::string::npos)
+                ? alias_cmd.substr(0, first_space) : alias_cmd;
+
+            auto alias_exe = resolve_executable(alias_prog, vdata->path, xlings_home);
+            if (!alias_exe.empty()) {
+                std::string alias_rest = (first_space != std::string::npos)
+                    ? alias_cmd.substr(first_space) : "";
+                alias_cmd = platform::shell_quote(alias_exe.string()) + alias_rest;
+                log::debug("  resolved: {} -> {}", alias_prog, alias_exe.string());
+            } else if (alias_prog == program_name) {
+                log::error("xlings: alias for '{}' references itself but real binary not found", program_name);
+                log::error("  path: {}", expanded_pkg);
+                return 1;
+            }
+        }
+
+        platform::set_env_variable("XLINGS_SHIM_DEPTH", std::to_string(depth + 1));
+
+        // Build command: resolved alias + original args, run via platform::exec
+        std::string cmd = alias_cmd;
+        for (int i = 1; i < argc; ++i) {
+            cmd += " ";
+            cmd += platform::shell_quote(argv[i]);
+        }
+        return platform::exec(cmd);
+    }
+
+    auto exe_path = resolve_executable(exec_name, vdata->path, xlings_home);
+    if (exe_path.empty()) {
+        log::error("xlings: executable '{}' not found", exec_name);
+        log::error("  path: {}", expand_path(vdata->path, xlings_home));
+        log::error("  hint: install with xlings install {}@{}", program_name, resolved_version);
+        return 1;
+    }
+
+    log::debug("exe path: {}", exe_path.string());
+
+    // Setup environment
+    if (auto vanishing = setup_envs(*vdata, exe_path.string(), xlings_home,
+                                    active_subos_dir)) {
+        report_vanishing_reference_(program_name, *vanishing);
+        return 1;
+    }
+
+    // Build argv for execvp
+    auto exe_str = exe_path.string();
+    std::vector<const char*> new_argv;
+    new_argv.push_back(exe_str.c_str());
+    for (int i = 1; i < argc; ++i) {
+        new_argv.push_back(argv[i]);
+    }
+    new_argv.push_back(nullptr);
+
+    // Increment shim depth before exec so child processes see it
+    platform::set_env_variable("XLINGS_SHIM_DEPTH", std::to_string(depth + 1));
+
+#if defined(__linux__) || defined(__APPLE__)
+    execvp(exe_path.c_str(), const_cast<char* const*>(new_argv.data()));
+    // If execvp returns, it failed
+    log::error("xlings: failed to exec '{}'",
+               Config::display_path(exe_path));
+    return 1;
+#else
+    // Fallback for platforms without execvp
+    std::string cmd = platform::shell_quote(exe_path.string());
+    for (int i = 1; i < argc; ++i) {
+        cmd += " ";
+        cmd += platform::shell_quote(argv[i]);
+    }
+    return platform::exec(cmd);
+#endif
+}
+
+}
diff --git a/src/core/xvm/shim.cppm b/src/core/xvm/shim.cppm
index 09e42630..e0e2551f 100644
--- a/src/core/xvm/shim.cppm
+++ b/src/core/xvm/shim.cppm
@@ -10,10 +10,7 @@ export module xlings.core.xvm.shim;
 
 import std;
 
-import xlings.libs.json;
 import xlings.core.config;
-import xlings.core.log;
-import xlings.platform;
 import xlings.core.xvm.types;
 import xlings.core.xvm.db;
 
@@ -25,15 +22,10 @@ export namespace xlings::xvm {
 // `xim` / `xvm` as multicall aliases, but they have been removed (see
 // main.cpp's deprecated-alias path for the migration error). The set is
 // closed and intentional: only the literal name `xlings`.
-bool is_xlings_binary(std::string_view name) {
-    return name == "xlings";
-}
+bool is_xlings_binary(std::string_view name);
 
 // Extract basename from argv[0], stripping path and extension
-std::string extract_program_name(const char* argv0) {
-    auto p = std::filesystem::path(argv0);
-    return p.stem().string();
-}
+std::string extract_program_name(const char* argv0);
 
 // ─── Owner-anchored dispatch home (0.4.48) ──────────────────────────
 //
@@ -54,16 +46,7 @@ std::string extract_program_name(const char* argv0) {
 // state dir (`<project>/.xlings`) has no `bin/xlings` — so neither can
 // false-match. Project shims must anchor to the GLOBAL home (their
 // payloads live there); the project state dir is excluded by design.
-bool is_home_root(const std::filesystem::path& dir) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    if (!fs::is_regular_file(dir / ".xlings.json", ec)) return false;
-    constexpr std::string_view bin_name =
-        (platform::OS_NAME == "windows") ? "xlings.exe" : "xlings";
-    if (!fs::exists(dir / "bin" / bin_name, ec)) return false;
-    if (!fs::is_directory(dir / "subos", ec)) return false;
-    return true;
-}
+bool is_home_root(const std::filesystem::path& dir);
 
 // Find the home that owns the invoked shim by walking parents upward.
 // Tries the shim file as invoked first (only when argv[0] carries a
@@ -73,36 +56,7 @@ bool is_home_root(const std::filesystem::path& dir) {
 // inside the owning home). The walk meets the INNERMOST home root
 // first, so nested homes resolve to the nearest owner.
 std::optional<std::filesystem::path>
-resolve_owner_home(const std::filesystem::path& invoked) {
-    namespace fs = std::filesystem;
-
-    auto walk_up = [](fs::path p) -> std::optional<fs::path> {
-        std::error_code ec;
-        auto canon = fs::weakly_canonical(p, ec);
-        if (!ec && !canon.empty()) p = canon;
-        for (auto dir = p.parent_path(); !dir.empty();) {
-            if (is_home_root(dir)) return dir;
-            auto parent = dir.parent_path();
-            if (parent == dir) break;
-            dir = parent;
-        }
-        return std::nullopt;
-    };
-
-    if (invoked.has_parent_path() && !invoked.parent_path().empty()) {
-        std::error_code ec;
-        auto abs = fs::absolute(invoked, ec);
-        if (!ec) {
-            if (auto h = walk_up(abs)) return h;
-        }
-    }
-
-    auto exe = platform::get_executable_path();
-    if (!exe.empty()) {
-        if (auto h = walk_up(exe)) return h;
-    }
-    return std::nullopt;
-}
+resolve_owner_home(const std::filesystem::path& invoked);
 
 // Lightweight probe: does <home>'s version DB register `program` (with
 // at least one version)? Reads <home>/.xlings.json directly — no Config
@@ -111,162 +65,19 @@ resolve_owner_home(const std::filesystem::path& invoked) {
 // hit: the error is then reported against that home instead of silently
 // jumping homes (genuine breakage must not be masked).
 bool home_knows_program(const std::filesystem::path& home,
-                        const std::string& program) {
-    namespace fs = std::filesystem;
-    std::error_code ec;
-    auto cfg = home / ".xlings.json";
-    if (!fs::is_regular_file(cfg, ec)) return false;
-
-    // Distinguish "unreadable due to ownership" from "genuinely not
-    // registered". A sudo-installed home is root-owned; a later non-root
-    // invocation can't read its .xlings.json and would otherwise get a
-    // misleading "<program>: not installed" instead of a permissions hint.
-    if (std::ifstream probe(cfg, std::ios::binary); !probe.is_open()) {
-        log::warn("[xlings] cannot read {} (permission denied)",
-                  Config::display_path(cfg));
-        log::warn("  this home may be owned by another user — avoid mixing "
-                  "sudo and non-sudo xlings on the same home");
-        return false;
-    }
-
-    try {
-        auto content = platform::read_file_to_string(cfg.string());
-        auto j = nlohmann::json::parse(content, nullptr, false);
-        if (j.is_discarded() || !j.is_object()) return false;
-        if (!j.contains("versions") || !j["versions"].is_object()) return false;
-        const auto& versions = j["versions"];
-
-        auto has_versions = [](const nlohmann::json& e) {
-            return e.is_object() && e.contains("versions")
-                && e["versions"].is_object() && !e["versions"].empty();
-        };
-
-        if (versions.contains(program) && has_versions(versions[program]))
-            return true;
-
-        // The shim file name may differ from the DB key (VInfo::filename).
-        for (auto it = versions.begin(); it != versions.end(); ++it) {
-            const auto& e = it.value();
-            if (!e.is_object()) continue;
-            if (!e.contains("filename") || !e["filename"].is_string()) continue;
-            auto fn = e["filename"].get<std::string>();
-            if (!fn.empty() && fs::path(fn).stem().string() == program
-                && has_versions(e)) {
-                return true;
-            }
-        }
-    } catch (...) {
-        return false;
-    }
-    return false;
-}
+                        const std::string& program);
 
 // Choose the dispatch home for a shim invocation: owner → env →
 // default (§3 of the design doc). Returns the home to inject via
 // Config::override_home(), or nullopt to leave Config's legacy
 // resolution untouched (legacy mode, or no candidate knows better).
 std::optional<std::filesystem::path>
-resolve_dispatch_home(const std::string& program, const char* argv0) {
-    namespace fs = std::filesystem;
-
-    auto env_or_empty = [](const char* key) -> std::string {
-        const char* v = std::getenv(key);
-        return v ? std::string(v) : std::string();
-    };
-
-    auto mode = env_or_empty("XLINGS_SHIM_ANCHOR");
-    if (mode == "0" || mode == "legacy" || mode == "off") {
-        log::debug("shim home: anchoring disabled (XLINGS_SHIM_ANCHOR={})", mode);
-        return std::nullopt;
-    }
-
-    auto owner = resolve_owner_home(fs::path(argv0 ? argv0 : ""));
-    auto envHomeStr = env_or_empty("XLINGS_HOME");
-    fs::path envHome = envHomeStr.empty() ? fs::path{} : fs::path(envHomeStr);
-
-    auto same = [](const fs::path& a, const fs::path& b) {
-        if (a.empty() || b.empty()) return false;
-        std::error_code ec;
-        auto ca = fs::weakly_canonical(a, ec);
-        std::error_code ec2;
-        auto cb = fs::weakly_canonical(b, ec2);
-        return (ec || ec2) ? (a == b) : (ca == cb);
-    };
-
-    // hop 1: owner home (the shim's own home) — the contract.
-    if (owner && home_knows_program(*owner, program)) {
-        if (!envHome.empty() && !same(*owner, envHome)
-            && home_knows_program(envHome, program)) {
-            log::warn("shim '{}' owned by {} is also resolvable in XLINGS_HOME={}; "
-                      "using the owner home (env-based shim switching is deprecated "
-                      "— put that home's subos bin on PATH instead)",
-                      program, owner->string(), envHome.string());
-        }
-        log::debug("shim home: owner={} (hop 1)", owner->string());
-        return owner;
-    }
-
-    // hop 2: env XLINGS_HOME — DEPRECATED compat fallback ("borrowing").
-    if (!envHome.empty() && !same(owner.value_or(fs::path{}), envHome)
-        && home_knows_program(envHome, program)) {
-        log::warn("shim '{}' is not installed in its owning home{}; falling back "
-                  "to XLINGS_HOME={} (deprecated, will be removed in a future "
-                  "release)",
-                  program,
-                  owner ? (" " + owner->string()) : std::string(""),
-                  envHome.string());
-        log::debug("shim home: env={} (hop 2)", envHome.string());
-        return envHome;
-    }
-
-    // hop 3: default ~/.xlings — covers orphan shims copied out of a home.
-    fs::path defaultHome = fs::path(platform::get_home_dir()) / ".xlings";
-    if (!same(owner.value_or(fs::path{}), defaultHome)
-        && !same(envHome, defaultHome)
-        && home_knows_program(defaultHome, program)) {
-        log::debug("shim home: default={} (hop 3)", defaultHome.string());
-        return defaultHome;
-    }
-
-    // No candidate knows the program: bind to the owner so the error is
-    // reported against the home this shim belongs to; otherwise leave
-    // Config's legacy resolution (env/default) in place.
-    if (owner) {
-        log::debug("shim home: owner={} (no candidate knows '{}')",
-                   owner->string(), program);
-        return owner;
-    }
-    return std::nullopt;
-}
+resolve_dispatch_home(const std::string& program, const char* argv0);
 
 // Resolve the real executable path for a shim target
 std::filesystem::path resolve_executable(const std::string& program_name,
                                          const std::string& path,
-                                         const std::string& xlings_home) {
-    namespace fs = std::filesystem;
-
-    auto expanded = expand_path(path, xlings_home);
-    auto base = fs::path(expanded);
-
-    // Try direct: path/program_name, then path/bin/program_name
-    auto candidate1 = base / program_name;
-    if (fs::exists(candidate1)) return candidate1;
-    auto candidate2 = base / "bin" / program_name;
-    if (fs::exists(candidate2)) return candidate2;
-
-#if defined(_WIN32)
-    // Windows: try .exe / .bat / .cmd (bare name already tried above)
-    constexpr std::string_view win_exts[] = {".exe", ".bat", ".cmd"};
-    for (auto ext : win_exts) {
-        auto p1 = base / (program_name + std::string(ext));
-        if (fs::exists(p1)) return p1;
-        auto p2 = base / "bin" / (program_name + std::string(ext));
-        if (fs::exists(p2)) return p2;
-    }
-#endif
-
-    return {};
-}
+                                         const std::string& xlings_home);
 
 // Where an alias's program was found, in the order the runtime looks.
 //
@@ -309,67 +120,7 @@ AliasResolution resolve_alias_program(const std::string& program_name,
                                       const std::string& path,
                                       const std::string& xlings_home,
                                       const std::filesystem::path& subos_bin,
-                                      std::string_view searchPath) {
-    namespace fs = std::filesystem;
-
-    if (program_name.empty()) return {};
-
-    // An absolute alias is not searched for; it either exists or it does not.
-    // It is NOT a host command -- a recipe that pins a full path into its own
-    // payload store writes one, and calling that "satisfied by the host" gets
-    // the portability question exactly backwards.
-    if (fs::path(program_name).is_absolute()) {
-        std::error_code ec;
-        if (fs::exists(program_name, ec)) {
-            return {AliasOrigin::Absolute, fs::path(program_name)};
-        }
-        return {};
-    }
-
-    if (auto own = resolve_executable(program_name, path, xlings_home);
-        !own.empty()) {
-        return {AliasOrigin::Payload, std::move(own)};
-    }
-
-#if defined(_WIN32)
-    constexpr std::string_view exts[] = {"", ".exe", ".bat", ".cmd"};
-#else
-    constexpr std::string_view exts[] = {""};
-#endif
-
-    const auto probe = [&](const fs::path& dir) -> fs::path {
-        if (dir.empty()) return {};
-        for (auto ext : exts) {
-            auto candidate = dir / (program_name + std::string(ext));
-            std::error_code ec;
-            if (fs::exists(candidate, ec) && !fs::is_directory(candidate, ec)) {
-                return candidate;
-            }
-        }
-        return {};
-    };
-
-    if (auto sibling = probe(subos_bin); !sibling.empty()) {
-        return {AliasOrigin::SubosBin, std::move(sibling)};
-    }
-
-    std::size_t start = 0;
-    while (start <= searchPath.size() && !searchPath.empty()) {
-        auto end = searchPath.find(platform::PATH_SEPARATOR, start);
-        auto part = searchPath.substr(
-            start, end == std::string_view::npos ? std::string_view::npos
-                                                 : end - start);
-        if (!part.empty()) {
-            if (auto hit = probe(fs::path(part)); !hit.empty()) {
-                return {AliasOrigin::SystemPath, std::move(hit)};
-            }
-        }
-        if (end == std::string_view::npos) break;
-        start = end + 1;
-    }
-
-    return {};
-}
+                                      std::string_view searchPath);
 
 // Merge a shim-injected env value into the existing one. PATH-style vars
 // prepend (new first), but a value already present — as the whole value or as
@@ -380,19 +131,7 @@ AliasResolution resolve_alias_program(const std::string& program_name,
 // (xim-pkgindex#406) resolve the same bundle path). Returns the value to set,
 // or nullopt for "leave the env untouched".
 std::optional<std::string> merge_shim_env_value(const std::string& expanded,
-                                                const std::string& existing) {
-    if (existing.empty()) return expanded;
-    std::size_t start = 0;
-    while (start <= existing.size()) {
-        auto end = existing.find(platform::PATH_SEPARATOR, start);
-        auto part = existing.substr(start, end == std::string::npos
-                                           ? std::string::npos : end - start);
-        if (part == expanded) return std::nullopt;  // already present
-        if (end == std::string::npos) break;
-        start = end + 1;
-    }
-    return expanded + platform::PATH_SEPARATOR + existing;
-}
+                                                const std::string& existing);
 
 // Set environment variables for a program before exec.
 //
@@ -402,319 +141,14 @@ std::optional<std::string> merge_shim_env_value(const std::string& expanded,
 std::optional<std::string> setup_envs(const VData& vdata,
                 const std::string& resolved_path,
                 const std::string& xlings_home,
-                const std::string& active_subos_dir) {
-    // The subos library farm, declared by the layer that resolved WHICH subos
-    // this process runs in.
-    //
-    // The same contract the shell profile, `subos spawn` and `--sandbox` each
-    // declare (E2a, 2026.8.11.1) -- but those three cover entry into a subos,
-    // and a shim is the fourth way a program starts: `gcc` invoked from a
-    // plain shell that never sourced the profile, or from a build system that
-    // sanitises the environment. The `ld` wrapper in the binutils payload
-    // reads this variable, so a path where nobody sets it is a path where the
-    // wrapper silently does nothing -- which is indistinguishable from it
-    // working.
-    //
-    // Set unconditionally rather than only-if-absent: this layer resolved the
-    // ACTIVE subos for this process (project > env > home), and the profile's
-    // value is the home's default, which is the wrong one inside a project
-    // subos. The most specific answerer wins.
-    if (!active_subos_dir.empty()) {
-        platform::set_env_variable(
-            "XLINGS_SUBOS_LIB",
-            (std::filesystem::path(active_subos_dir) / "lib").string());
-    }
-
-    // Set envs from VData
-    for (auto& [key, value] : vdata.envs) {
-        // Same hazard as the alias: an env value recorded at install time can
-        // name that install's subos. Re-point it at the active one.
-        auto expanded = expand_subos_placeholder(
-            normalize_subos_paths(expand_path(value, xlings_home),
-                                  xlings_home, active_subos_dir),
-            active_subos_dir);
-        if (auto vanishing = vanishing_xlings_reference(expanded)) {
-            return vanishing;
-        }
-        auto existing = std::string(std::getenv(key.c_str()) ? std::getenv(key.c_str()) : "");
-        if (auto merged = merge_shim_env_value(expanded, existing))
-            platform::set_env_variable(key, *merged);
-    }
-
-    // Prepend resolved program's directory to PATH
-    if (!resolved_path.empty()) {
-        auto dir = std::filesystem::path(resolved_path).parent_path().string();
-        auto existing_path = std::string(std::getenv("PATH") ? std::getenv("PATH") : "");
-        auto bin_dir = Config::paths().binDir.string();
-        std::string new_path;
-        if (!dir.empty()) new_path = dir;
-        if (!bin_dir.empty()) {
-            if (!new_path.empty()) new_path += platform::PATH_SEPARATOR;
-            new_path += bin_dir;
-        }
-        if (!existing_path.empty()) {
-            if (!new_path.empty()) new_path += platform::PATH_SEPARATOR;
-            new_path += existing_path;
-        }
-        platform::set_env_variable("PATH", new_path);
-    }
-    return std::nullopt;
-}
+                const std::string& active_subos_dir);
 
 // One message for both ways a `${XLINGS_*}` reference can vanish, because the
 // user's next move differs and only one of the two is their problem.
 void report_vanishing_reference_(const std::string& program_name,
-                                 const std::string& name) {
-    if (name == "XLINGS_DYNAMIC_SUBOS_DIR") {
-        log::error("xlings: '{}' needs the active subos, and none resolved",
-                   program_name);
-        log::error("  hint: xlings subos list   (then `xlings subos use <name>`)");
-        return;
-    }
-    log::error("xlings: '{}' is registered against '{}', which this client "
-               "does not provide", program_name, name);
-    log::error("  this record was written by a newer index than the xlings "
-               "running it");
-    log::error("  hint: xlings self update   (entry: {})",
-               std::string(Info::VERSION));
-}
+                                 const std::string& name);
 
 // Main shim dispatch: called when argv[0] is a tool name (not xlings/xim)
-int shim_dispatch(const std::string& program_name, int argc, char* argv[]) {
-    // Recursion guard: detect infinite shim re-invocation
-    constexpr int MAX_SHIM_DEPTH = 8;
-    constexpr int FALLBACK_DEPTH = MAX_SHIM_DEPTH + 2;
-    auto depth_str = std::getenv("XLINGS_SHIM_DEPTH");
-    int depth = depth_str ? std::atoi(depth_str) : 0;
-    if (depth >= FALLBACK_DEPTH) {
-        log::error("xlings: shim recursion detected for '{}' (depth={})", program_name, depth);
-        log::error("  hint: the real '{}' binary may not be installed", program_name);
-        return 1;
-    }
-
-    log::debug("shim dispatch: program={}, depth={}", program_name, depth);
-
-    auto& cfg = Config::paths();
-    auto xlings_home = cfg.homeDir.string();
-    // The one resolution point that is correct in all three selection modes
-    // (project subos > XLINGS_ACTIVE_SUBOS > the home's activeSubos field).
-    auto active_subos_dir = Config::xvm_artifact_subos_dir().string();
-
-    // Get effective workspace (project > subos > global)
-    auto workspace = Config::effective_workspace();
-
-    // Look up active version for this program
-    auto version = get_active_version(workspace, program_name);
-    auto db = Config::versions();
-    if (version.empty()) {
-        // Tri-state diagnostic, scoped to the CURRENT subos's installed[]
-        // (NOT the global versions DB — pre-0.4.19 the "available" list
-        // showed every version every subos had ever installed, which was
-        // misleading from inside a fresh / pruned subos):
-        //
-        //   * installed[] empty + global DB empty       → never installed
-        //   * installed[] empty + global DB has entries → installed in
-        //     another subos, current subos has no view of it (suggest
-        //     `xlings install` — payload is shared, but this subos
-        //     needs to opt in)
-        //   * installed[] non-empty                     → some versions
-        //     are opted-in but no active pointer; list THOSE versions
-        //     and tell the user to `xlings use` one of them
-        const auto& subos_installed = Config::workspace_installed();
-        std::vector<std::string> here;
-        if (auto it = subos_installed.find(program_name); it != subos_installed.end()) {
-            here = it->second;
-        }
-
-        if (here.empty()) {
-            auto global_all = get_all_versions(db, program_name);
-            if (global_all.empty()) {
-                log::error("xlings: '{}' is not installed", program_name);
-                log::error("  hint: xlings install {}", program_name);
-            } else {
-                log::error("xlings: '{}' is not installed in current subos", program_name);
-                log::error("  hint: xlings install {}", program_name);
-            }
-        } else {
-            log::error("xlings: no active version of '{}' in current subos", program_name);
-            std::string avail;
-            for (auto& v : here) {
-                if (!avail.empty()) avail += " ";
-                avail += v;
-            }
-            log::error("  available: {}", avail);
-            log::error("  hint: xlings use {} <version>", program_name);
-        }
-        return 1;
-    }
-
-    // Resolve version (fuzzy match)
-    auto resolved_version = match_version(db, program_name, version);
-    if (resolved_version.empty()) {
-        log::error("xlings: version '{}' not found for '{}'", version, program_name);
-        auto all = get_all_versions(db, program_name);
-        if (!all.empty()) {
-            std::string avail = "  available:";
-            for (auto& v : all) avail += " " + v;
-            log::error("{}", avail);
-        }
-        return 1;
-    }
-
-    log::debug("resolved version: {} -> {}", version, resolved_version);
-
-    auto vdata = get_vdata(db, program_name, resolved_version);
-    if (!vdata) {
-        log::error("xlings: no path info for {} {}", program_name, resolved_version);
-        return 1;
-    }
-
-    // Each target (including binding targets) has its own workspace version
-    // and vdata, so use program_name directly for execution.
-    std::string exec_name = program_name;
-
-    if (!vdata->alias.empty()) {
-        // Env alias fallback: prepend bindir to PATH, run alias via system
-        auto expanded_path = expand_path(vdata->path, xlings_home);
-        auto bin_path = (std::filesystem::path(expanded_path) / "bin").string();
-        auto existing_path = std::string(std::getenv("PATH") ? std::getenv("PATH") : "");
-        auto cfg_bin = Config::paths().binDir.string();
-
-        std::string new_path;
-        if (!expanded_path.empty() && std::filesystem::exists(expanded_path))
-            new_path = expanded_path;
-        if (std::filesystem::exists(bin_path)) {
-            if (!new_path.empty()) new_path += platform::PATH_SEPARATOR;
-            new_path += bin_path;
-        }
-        if (!cfg_bin.empty()) {
-            if (!new_path.empty()) new_path += platform::PATH_SEPARATOR;
-            new_path += cfg_bin;
-        }
-        if (!existing_path.empty()) {
-            if (!new_path.empty()) new_path += platform::PATH_SEPARATOR;
-            new_path += existing_path;
-        }
-        platform::set_env_variable("PATH", new_path);
-
-        // Setup custom envs
-        if (auto vanishing =
-                setup_envs(*vdata, "", xlings_home, active_subos_dir)) {
-            report_vanishing_reference_(program_name, *vanishing);
-            return 1;
-        }
-
-        // COMPAT: an alias written before the placeholder existed carries the
-        // absolute path of whatever subos was active at install time. Re-point
-        // it at the subos THIS process resolves to -- project, env and global
-        // selection all land on xvm_artifact_subos_dir(). A record written by
-        // a current xlings has no such path, so this is a no-op for it.
-        //
-        // Kept for records written before the placeholder existed. New
-        // records carry `${XLINGS_SUBOS}` and have no path here to rewrite.
-        std::string alias_cmd = normalize_subos_paths(
-            vdata->alias[0], xlings_home, active_subos_dir);
-
-        // The record stored a marker rather than one subos's answer, and this
-        // is the only layer that knows which subos this process resolved to
-        // -- which is exactly why the answer was not in the database.
-        alias_cmd = expand_subos_placeholder(alias_cmd, active_subos_dir);
-
-        // Refuse rather than hand a vanishing reference to the shell.
-        //
-        // This is the guard the 0.4.51 incident needed: that client predated
-        // the marker, passed it through, and `sh` turned `--sysroot=<marker>`
-        // into `--sysroot=` -- a valid flag meaning "use the host root". Every
-        // build in the home silently stopped being self-contained and the
-        // first visible symptom was a missing crt1.o three layers down.
-        //
-        // Checked AFTER setup_envs, so a variable the alias legitimately
-        // defers to (`${XLINGS_SUBOS_LIB}`) has already been exported and does
-        // not trip this.
-        if (auto vanishing = vanishing_xlings_reference(alias_cmd)) {
-            report_vanishing_reference_(program_name, *vanishing);
-            return 1;
-        }
-
-        if (depth >= MAX_SHIM_DEPTH) {
-            // Fallback: resolve alias command to full path to break recursion
-            auto expanded_pkg = expand_path(vdata->path, xlings_home);
-            log::debug("shim alias fallback (depth={}): program={}, alias='{}'", depth, program_name, alias_cmd);
-            log::debug("  package path: {}", expanded_pkg);
-            log::debug("  PATH: {}", std::getenv("PATH") ? std::getenv("PATH") : "(null)");
-
-            auto first_space = alias_cmd.find(' ');
-            std::string alias_prog = (first_space != std::string::npos)
-                ? alias_cmd.substr(0, first_space) : alias_cmd;
-
-            auto alias_exe = resolve_executable(alias_prog, vdata->path, xlings_home);
-            if (!alias_exe.empty()) {
-                std::string alias_rest = (first_space != std::string::npos)
-                    ? alias_cmd.substr(first_space) : "";
-                alias_cmd = platform::shell_quote(alias_exe.string()) + alias_rest;
-                log::debug("  resolved: {} -> {}", alias_prog, alias_exe.string());
-            } else if (alias_prog == program_name) {
-                log::error("xlings: alias for '{}' references itself but real binary not found", program_name);
-                log::error("  path: {}", expanded_pkg);
-                return 1;
-            }
-        }
-
-        platform::set_env_variable("XLINGS_SHIM_DEPTH", std::to_string(depth + 1));
-
-        // Build command: resolved alias + original args, run via platform::exec
-        std::string cmd = alias_cmd;
-        for (int i = 1; i < argc; ++i) {
-            cmd += " ";
-            cmd += platform::shell_quote(argv[i]);
-        }
-        return platform::exec(cmd);
-    }
-
-    auto exe_path = resolve_executable(exec_name, vdata->path, xlings_home);
-    if (exe_path.empty()) {
-        log::error("xlings: executable '{}' not found", exec_name);
-        log::error("  path: {}", expand_path(vdata->path, xlings_home));
-        log::error("  hint: install with xlings install {}@{}", program_name, resolved_version);
-        return 1;
-    }
-
-    log::debug("exe path: {}", exe_path.string());
-
-    // Setup environment
-    if (auto vanishing = setup_envs(*vdata, exe_path.string(), xlings_home,
-                                    active_subos_dir)) {
-        report_vanishing_reference_(program_name, *vanishing);
-        return 1;
-    }
-
-    // Build argv for execvp
-    auto exe_str = exe_path.string();
-    std::vector<const char*> new_argv;
-    new_argv.push_back(exe_str.c_str());
-    for (int i = 1; i < argc; ++i) {
-        new_argv.push_back(argv[i]);
-    }
-    new_argv.push_back(nullptr);
-
-    // Increment shim depth before exec so child processes see it
-    platform::set_env_variable("XLINGS_SHIM_DEPTH", std::to_string(depth + 1));
-
-#if defined(__linux__) || defined(__APPLE__)
-    execvp(exe_path.c_str(), const_cast<char* const*>(new_argv.data()));
-    // If execvp returns, it failed
-    log::error("xlings: failed to exec '{}'",
-               Config::display_path(exe_path));
-    return 1;
-#else
-    // Fallback for platforms without execvp
-    std::string cmd = platform::shell_quote(exe_path.string());
-    for (int i = 1; i < argc; ++i) {
-        cmd += " ";
-        cmd += platform::shell_quote(argv[i]);
-    }
-    return platform::exec(cmd);
-#endif
-}
+int shim_dispatch(const std::string& program_name, int argc, char* argv[]);
 
 } // namespace xlings::xvm
diff --git a/src/core/xvm/switch_plan.cpp b/src/core/xvm/switch_plan.cpp
new file mode 100644
index 00000000..ca4be19b
--- /dev/null
+++ b/src/core/xvm/switch_plan.cpp
@@ -0,0 +1,242 @@
+module xlings.core.xvm.switch_plan;
+
+import std;
+import xlings.core.xvm.types;
+import xlings.core.xvm.bindings;
+import xlings.core.xvm.errors;
+
+namespace xlings::xvm::detail_ {
+
+// Which package a (target, version) belongs to, and at which version of it.
+//
+// Empty when the entry carries no group metadata -- entries written before
+// providers were recorded. Callers must treat that as "unknown", not as "a
+// different package".
+std::pair<std::string, std::string> provider_of_(const VersionDB& db,
+                                                 const std::string& target,
+                                                 const std::string& version) {
+    const auto it = db.find(target);
+    if (it == db.end()) return {};
+    const auto vit = it->second.versions.find(version);
+    if (vit == it->second.versions.end() || !vit->second.bindingGroup) {
+        return {};
+    }
+    return {vit->second.bindingGroup->provider,
+            vit->second.bindingGroup->providerVersion};
+}
+
+}
+
+namespace xlings::xvm {
+
+std::expected<UseSwitchPlan, XvmUserError> plan_use_switch(
+        const VersionDB& db,
+        const Workspace& workspace,
+        const std::string& target,
+        const std::string& resolvedVersion) {
+    auto selection = resolve_binding_selection(db, target, resolvedVersion);
+    if (!selection) {
+        return std::unexpected(describe(selection.error()));
+    }
+
+    UseSwitchPlan plan{.members = selection->members};
+
+    // Preflight every member before emitting any change, so "the third of
+    // five members is missing" is an error rather than a toolchain switched
+    // two fifths of the way.
+    for (const auto& [memberTarget, memberVersion] : plan.members) {
+        auto infoIt = db.find(memberTarget);
+        if (infoIt == db.end()
+            || !infoIt->second.versions.contains(memberVersion)) {
+            return std::unexpected(XvmUserError{
+                .code = "xvm-switch-member-missing",
+                .what = std::format(
+                    "cannot switch to {}@{}: member '{}@{}' has no payload "
+                    "record", target, resolvedVersion, memberTarget,
+                    memberVersion),
+                .target = memberTarget,
+                .version = memberVersion,
+                .hint = "run `xlings self doctor` to see the offending entry",
+            });
+        }
+    }
+
+    // Accumulate the release's header assets while walking the members, then
+    // reconcile the two sets once at the end. Appending to a vector and
+    // deduplicating afterwards keeps the declaration order the recipe wrote,
+    // which decides which copy wins when two assets ship a header of the same
+    // name.
+    std::vector<HeaderAsset> incoming;
+    std::vector<HeaderAsset> outgoing;
+
+    for (const auto& [memberTarget, memberVersion] : plan.members) {
+        const auto activeIt = workspace.find(memberTarget);
+        const std::string previous =
+            activeIt == workspace.end() ? std::string{} : activeIt->second;
+
+        auto currentHeaders =
+            group_header_assets(db, memberTarget, memberVersion);
+        incoming.insert(incoming.end(),
+                        currentHeaders.begin(), currentHeaders.end());
+
+        auto placement = library_placement(db, memberTarget, memberVersion);
+        auto installSource = std::move(placement.source);
+        auto installName = std::move(placement.name);
+        auto file = file_placement(db, memberTarget, memberVersion);
+
+        if (previous == memberVersion) {
+            // Already the active version, but the sysroot may not reflect it:
+            // a removal that fell back to this release takes the removed
+            // release's headers out and puts nothing back. Re-materializing
+            // is idempotent, so `use` doubles as the repair for that -- and
+            // as a no-op when nothing is wrong. Nothing to remove first.
+            if (installSource.empty() && file.empty()) continue;
+            plan.switches.push_back({
+                .target = memberTarget,
+                .version = memberVersion,
+                .previousVersion = previous,
+                .installLibSource = std::move(installSource),
+                .installLibName = std::move(installName),
+                .installFileSource = std::move(file.source),
+                .installFileDest = std::move(file.destination),
+            });
+            continue;
+        }
+
+        MemberSwitch change{
+            .target = memberTarget,
+            .version = memberVersion,
+            .previousVersion = previous,
+            .installLibSource = std::move(installSource),
+            .installLibName = std::move(installName),
+            .installFileSource = std::move(file.source),
+            .installFileDest = std::move(file.destination),
+        };
+        if (!previous.empty()) {
+            auto previousHeaders =
+                group_header_assets(db, memberTarget, previous);
+            outgoing.insert(outgoing.end(),
+                            previousHeaders.begin(), previousHeaders.end());
+            auto previousPlacement =
+                library_placement(db, memberTarget, previous);
+            // Only worth recording when the outgoing version occupied a
+            // *different* name. The common case -- same soname across two
+            // versions -- is a replacement, and unlinking first would open a
+            // window with the library missing.
+            if (!previousPlacement.name.empty()
+                && previousPlacement.name != change.installLibName) {
+                change.removeLibName = std::move(previousPlacement.name);
+            }
+            // Same reasoning for a file asset: only unlink when the outgoing
+            // version occupied a path the incoming one does not reuse.
+            auto previousFile =
+                file_placement(db, memberTarget, previous);
+            if (!previousFile.destination.empty()
+                && previousFile.destination != change.installFileDest) {
+                change.removeFileDest = std::move(previousFile.destination);
+            }
+        }
+        plan.switches.push_back(std::move(change));
+    }
+
+    auto dedup = [](std::vector<HeaderAsset>& assets) {
+        std::set<std::pair<std::string, std::string>> seen;
+        std::erase_if(assets, [&](const HeaderAsset& asset) {
+            return asset.sourceDir.empty()
+                || !seen.emplace(asset.sourceDir,
+                                 asset.destinationPrefix).second;
+        });
+    };
+    dedup(incoming);
+    dedup(outgoing);
+
+    // An asset the incoming release also needs must not be taken out first.
+    // Two releases of the same toolchain can share a header directory, and
+    // `use` re-materializes the active release on every call to repair a
+    // drifted sysroot -- removing and relinking would open a window on every
+    // one of those calls where the header is simply absent, long enough for a
+    // concurrent build to fail on it. install_headers already skips a link
+    // that is correct; this makes sure nothing removes it beforehand.
+    std::set<std::pair<std::string, std::string>> kept;
+    for (const auto& asset : incoming) {
+        kept.emplace(asset.sourceDir, asset.destinationPrefix);
+    }
+    std::erase_if(outgoing, [&](const HeaderAsset& asset) {
+        return kept.contains({asset.sourceDir, asset.destinationPrefix});
+    });
+
+    plan.installHeaders = std::move(incoming);
+    plan.removeHeaders = std::move(outgoing);
+
+    // Which package this switch moves between, for the report line.
+    std::tie(plan.toProvider, plan.toProviderVersion) =
+        detail_::provider_of_(db, target, resolvedVersion);
+
+    // What the release being left had, that this one does not.
+    //
+    // Best effort by construction: an outgoing release that no longer
+    // resolves cannot be enumerated, and failing the switch over that would
+    // block the very command that repairs it. Only a name whose *current*
+    // active version is the outgoing member's is reported -- anything else
+    // was already pointing somewhere of the user's own choosing.
+    if (const auto previousIt = workspace.find(target);
+        previousIt != workspace.end()
+        && !previousIt->second.empty()
+        && previousIt->second != resolvedVersion) {
+        std::tie(plan.fromProvider, plan.fromProviderVersion) =
+            detail_::provider_of_(db, target, previousIt->second);
+
+        // Switching PACKAGES is not a half-finished switch.
+        //
+        // `use java 25.0.4-zulu` hands the name `java` from one JDK to
+        // another: the whole zulu release comes across, and temurin is left
+        // untouched, complete, and still active. Nothing fell behind, so
+        // there is nothing to report -- and reporting it costs real damage.
+        // A group root's name IS the package name, so two packages can never
+        // share one; the root of the package being left therefore lands in
+        // the report on EVERY cross-package switch, and `--strict` refuses
+        // over it, which means `--strict` can never move `java` between two
+        // distributions no matter what the user does first. Measured on a
+        // real home: `gcc` from the gnu package to the musl one produces 18
+        // such lines, and not one of them names something the user can act
+        // on -- the musl package has no version of any of them.
+        //
+        // This is the rule `self doctor` has followed since 2026.8.1.1: a
+        // name held by another provider is ownership, not incoherence
+        // (inspect.cppm's held_by_another_provider_). `use` was the last
+        // place still reading it as a broken toolchain.
+        //
+        // Unknown metadata counts as the same package -- entries written
+        // before providers were recorded keep the older, stricter behaviour
+        // instead of silently losing the check. Same fallback direction as
+        // held_by_another_provider_.
+        const bool samePackage =
+            plan.fromProvider.empty() || plan.toProvider.empty()
+            || plan.fromProvider == plan.toProvider;
+
+        if (auto outgoingSelection =
+                resolve_binding_selection(db, target, previousIt->second)) {
+            for (const auto& [memberTarget, memberVersion] :
+                     outgoingSelection->members) {
+                if (plan.members.contains(memberTarget)) continue;
+                const auto activeIt = workspace.find(memberTarget);
+                if (activeIt == workspace.end()
+                    || activeIt->second != memberVersion) {
+                    continue;
+                }
+                // A member that materializes nothing cannot be left behind.
+                // The shim loop in cmd_use asks the same question of the same
+                // authority before writing a shim; this report was the one
+                // place that never asked.
+                auto kind = effective_kind_of(db, memberTarget, memberVersion);
+                if (!kind_can_strand(kind)) continue;
+                (samePackage ? plan.stranded : plan.retainedByOldPackage)
+                    .push_back({memberTarget, memberVersion, std::move(kind)});
+            }
+        }
+    }
+
+    return plan;
+}
+
+}
diff --git a/src/core/xvm/switch_plan.cppm b/src/core/xvm/switch_plan.cppm
index 4c914f3d..b0f9db0d 100644
--- a/src/core/xvm/switch_plan.cppm
+++ b/src/core/xvm/switch_plan.cppm
@@ -23,24 +23,6 @@ import xlings.core.xvm.errors;
 // nothing inside it was testable before.
 namespace xlings::xvm::detail_ {
 
-// Which package a (target, version) belongs to, and at which version of it.
-//
-// Empty when the entry carries no group metadata -- entries written before
-// providers were recorded. Callers must treat that as "unknown", not as "a
-// different package".
-std::pair<std::string, std::string> provider_of_(const VersionDB& db,
-                                                 const std::string& target,
-                                                 const std::string& version) {
-    const auto it = db.find(target);
-    if (it == db.end()) return {};
-    const auto vit = it->second.versions.find(version);
-    if (vit == it->second.versions.end() || !vit->second.bindingGroup) {
-        return {};
-    }
-    return {vit->second.bindingGroup->provider,
-            vit->second.bindingGroup->providerVersion};
-}
-
 }  // namespace xlings::xvm::detail_
 
 export namespace xlings::xvm {
@@ -169,210 +151,6 @@ std::expected<UseSwitchPlan, XvmUserError> plan_use_switch(
         const VersionDB& db,
         const Workspace& workspace,
         const std::string& target,
-        const std::string& resolvedVersion) {
-    auto selection = resolve_binding_selection(db, target, resolvedVersion);
-    if (!selection) {
-        return std::unexpected(describe(selection.error()));
-    }
-
-    UseSwitchPlan plan{.members = selection->members};
-
-    // Preflight every member before emitting any change, so "the third of
-    // five members is missing" is an error rather than a toolchain switched
-    // two fifths of the way.
-    for (const auto& [memberTarget, memberVersion] : plan.members) {
-        auto infoIt = db.find(memberTarget);
-        if (infoIt == db.end()
-            || !infoIt->second.versions.contains(memberVersion)) {
-            return std::unexpected(XvmUserError{
-                .code = "xvm-switch-member-missing",
-                .what = std::format(
-                    "cannot switch to {}@{}: member '{}@{}' has no payload "
-                    "record", target, resolvedVersion, memberTarget,
-                    memberVersion),
-                .target = memberTarget,
-                .version = memberVersion,
-                .hint = "run `xlings self doctor` to see the offending entry",
-            });
-        }
-    }
-
-    // Accumulate the release's header assets while walking the members, then
-    // reconcile the two sets once at the end. Appending to a vector and
-    // deduplicating afterwards keeps the declaration order the recipe wrote,
-    // which decides which copy wins when two assets ship a header of the same
-    // name.
-    std::vector<HeaderAsset> incoming;
-    std::vector<HeaderAsset> outgoing;
-
-    for (const auto& [memberTarget, memberVersion] : plan.members) {
-        const auto activeIt = workspace.find(memberTarget);
-        const std::string previous =
-            activeIt == workspace.end() ? std::string{} : activeIt->second;
-
-        auto currentHeaders =
-            group_header_assets(db, memberTarget, memberVersion);
-        incoming.insert(incoming.end(),
-                        currentHeaders.begin(), currentHeaders.end());
-
-        auto placement = library_placement(db, memberTarget, memberVersion);
-        auto installSource = std::move(placement.source);
-        auto installName = std::move(placement.name);
-        auto file = file_placement(db, memberTarget, memberVersion);
-
-        if (previous == memberVersion) {
-            // Already the active version, but the sysroot may not reflect it:
-            // a removal that fell back to this release takes the removed
-            // release's headers out and puts nothing back. Re-materializing
-            // is idempotent, so `use` doubles as the repair for that -- and
-            // as a no-op when nothing is wrong. Nothing to remove first.
-            if (installSource.empty() && file.empty()) continue;
-            plan.switches.push_back({
-                .target = memberTarget,
-                .version = memberVersion,
-                .previousVersion = previous,
-                .installLibSource = std::move(installSource),
-                .installLibName = std::move(installName),
-                .installFileSource = std::move(file.source),
-                .installFileDest = std::move(file.destination),
-            });
-            continue;
-        }
-
-        MemberSwitch change{
-            .target = memberTarget,
-            .version = memberVersion,
-            .previousVersion = previous,
-            .installLibSource = std::move(installSource),
-            .installLibName = std::move(installName),
-            .installFileSource = std::move(file.source),
-            .installFileDest = std::move(file.destination),
-        };
-        if (!previous.empty()) {
-            auto previousHeaders =
-                group_header_assets(db, memberTarget, previous);
-            outgoing.insert(outgoing.end(),
-                            previousHeaders.begin(), previousHeaders.end());
-            auto previousPlacement =
-                library_placement(db, memberTarget, previous);
-            // Only worth recording when the outgoing version occupied a
-            // *different* name. The common case -- same soname across two
-            // versions -- is a replacement, and unlinking first would open a
-            // window with the library missing.
-            if (!previousPlacement.name.empty()
-                && previousPlacement.name != change.installLibName) {
-                change.removeLibName = std::move(previousPlacement.name);
-            }
-            // Same reasoning for a file asset: only unlink when the outgoing
-            // version occupied a path the incoming one does not reuse.
-            auto previousFile =
-                file_placement(db, memberTarget, previous);
-            if (!previousFile.destination.empty()
-                && previousFile.destination != change.installFileDest) {
-                change.removeFileDest = std::move(previousFile.destination);
-            }
-        }
-        plan.switches.push_back(std::move(change));
-    }
-
-    auto dedup = [](std::vector<HeaderAsset>& assets) {
-        std::set<std::pair<std::string, std::string>> seen;
-        std::erase_if(assets, [&](const HeaderAsset& asset) {
-            return asset.sourceDir.empty()
-                || !seen.emplace(asset.sourceDir,
-                                 asset.destinationPrefix).second;
-        });
-    };
-    dedup(incoming);
-    dedup(outgoing);
-
-    // An asset the incoming release also needs must not be taken out first.
-    // Two releases of the same toolchain can share a header directory, and
-    // `use` re-materializes the active release on every call to repair a
-    // drifted sysroot -- removing and relinking would open a window on every
-    // one of those calls where the header is simply absent, long enough for a
-    // concurrent build to fail on it. install_headers already skips a link
-    // that is correct; this makes sure nothing removes it beforehand.
-    std::set<std::pair<std::string, std::string>> kept;
-    for (const auto& asset : incoming) {
-        kept.emplace(asset.sourceDir, asset.destinationPrefix);
-    }
-    std::erase_if(outgoing, [&](const HeaderAsset& asset) {
-        return kept.contains({asset.sourceDir, asset.destinationPrefix});
-    });
-
-    plan.installHeaders = std::move(incoming);
-    plan.removeHeaders = std::move(outgoing);
-
-    // Which package this switch moves between, for the report line.
-    std::tie(plan.toProvider, plan.toProviderVersion) =
-        detail_::provider_of_(db, target, resolvedVersion);
-
-    // What the release being left had, that this one does not.
-    //
-    // Best effort by construction: an outgoing release that no longer
-    // resolves cannot be enumerated, and failing the switch over that would
-    // block the very command that repairs it. Only a name whose *current*
-    // active version is the outgoing member's is reported -- anything else
-    // was already pointing somewhere of the user's own choosing.
-    if (const auto previousIt = workspace.find(target);
-        previousIt != workspace.end()
-        && !previousIt->second.empty()
-        && previousIt->second != resolvedVersion) {
-        std::tie(plan.fromProvider, plan.fromProviderVersion) =
-            detail_::provider_of_(db, target, previousIt->second);
-
-        // Switching PACKAGES is not a half-finished switch.
-        //
-        // `use java 25.0.4-zulu` hands the name `java` from one JDK to
-        // another: the whole zulu release comes across, and temurin is left
-        // untouched, complete, and still active. Nothing fell behind, so
-        // there is nothing to report -- and reporting it costs real damage.
-        // A group root's name IS the package name, so two packages can never
-        // share one; the root of the package being left therefore lands in
-        // the report on EVERY cross-package switch, and `--strict` refuses
-        // over it, which means `--strict` can never move `java` between two
-        // distributions no matter what the user does first. Measured on a
-        // real home: `gcc` from the gnu package to the musl one produces 18
-        // such lines, and not one of them names something the user can act
-        // on -- the musl package has no version of any of them.
-        //
-        // This is the rule `self doctor` has followed since 2026.8.1.1: a
-        // name held by another provider is ownership, not incoherence
-        // (inspect.cppm's held_by_another_provider_). `use` was the last
-        // place still reading it as a broken toolchain.
-        //
-        // Unknown metadata counts as the same package -- entries written
-        // before providers were recorded keep the older, stricter behaviour
-        // instead of silently losing the check. Same fallback direction as
-        // held_by_another_provider_.
-        const bool samePackage =
-            plan.fromProvider.empty() || plan.toProvider.empty()
-            || plan.fromProvider == plan.toProvider;
-
-        if (auto outgoingSelection =
-                resolve_binding_selection(db, target, previousIt->second)) {
-            for (const auto& [memberTarget, memberVersion] :
-                     outgoingSelection->members) {
-                if (plan.members.contains(memberTarget)) continue;
-                const auto activeIt = workspace.find(memberTarget);
-                if (activeIt == workspace.end()
-                    || activeIt->second != memberVersion) {
-                    continue;
-                }
-                // A member that materializes nothing cannot be left behind.
-                // The shim loop in cmd_use asks the same question of the same
-                // authority before writing a shim; this report was the one
-                // place that never asked.
-                auto kind = effective_kind_of(db, memberTarget, memberVersion);
-                if (!kind_can_strand(kind)) continue;
-                (samePackage ? plan.stranded : plan.retainedByOldPackage)
-                    .push_back({memberTarget, memberVersion, std::move(kind)});
-            }
-        }
-    }
-
-    return plan;
-}
+        const std::string& resolvedVersion);
 
 }  // namespace xlings::xvm
diff --git a/src/core/xvm/types.cpp b/src/core/xvm/types.cpp
new file mode 100644
index 00000000..07bdc445
--- /dev/null
+++ b/src/core/xvm/types.cpp
@@ -0,0 +1,59 @@
+module xlings.core.xvm.types;
+
+import std;
+
+namespace xlings::xvm {
+
+std::string effective_kind(const VInfo& info, const VData& data) {
+    return data.kind.empty() ? info.type : data.kind;
+}
+
+std::string effective_source_name(const std::string& target,
+                                  const VInfo& info,
+                                  const VData& data,
+                                  std::string_view kind) {
+    // `group` and `files` name no artifact to dispatch.
+    if (kind == "group" || kind == "files") return {};
+    if (!data.sourceName.empty()) return data.sourceName;
+    return info.filename.empty() ? target : info.filename;
+}
+
+std::string effective_destination_name(const std::string& target,
+                                       const VData& data,
+                                       std::string_view kind,
+                                       std::string_view sourceName) {
+    if (kind == "group" || kind == "files") return {};
+    if (!data.destinationName.empty()) return data.destinationName;
+    if (kind == "program") return target;
+    return std::string(sourceName);
+}
+
+std::string effective_kind_of(const VersionDB& db,
+                              const std::string& target,
+                              const std::string& version) {
+    auto it = db.find(target);
+    if (it == db.end()) return {};
+    auto vit = it->second.versions.find(version);
+    if (vit == it->second.versions.end()) return it->second.type;
+    return effective_kind(it->second, vit->second);
+}
+
+bool kind_can_strand(std::string_view kind) { return kind != "group"; }
+
+bool has_program_kind(const VersionDB& db, const std::string& target) {
+    auto it = db.find(target);
+    if (it == db.end()) return false;
+    if (it->second.versions.empty()) return it->second.type == "program";
+    for (const auto& [version, data] : it->second.versions) {
+        if (effective_kind(it->second, data) == "program") return true;
+    }
+    return false;
+}
+
+}
+
+ // namespace xlings::xvm
+
+#if !defined(_MSC_VER)
+
+#endif
diff --git a/src/core/xvm/types.cppm b/src/core/xvm/types.cppm
index a13b8ca0..544a6eb7 100644
--- a/src/core/xvm/types.cppm
+++ b/src/core/xvm/types.cppm
@@ -150,29 +150,17 @@ struct SubosWorkspace {
 // planner materializes them. They used to exist only inside registration's
 // detail namespace, so the planner could not see them -- which is part of why
 // libraries were registered correctly and then never switched.
-std::string effective_kind(const VInfo& info, const VData& data) {
-    return data.kind.empty() ? info.type : data.kind;
-}
+std::string effective_kind(const VInfo& info, const VData& data);
 
 std::string effective_source_name(const std::string& target,
                                   const VInfo& info,
                                   const VData& data,
-                                  std::string_view kind) {
-    // `group` and `files` name no artifact to dispatch.
-    if (kind == "group" || kind == "files") return {};
-    if (!data.sourceName.empty()) return data.sourceName;
-    return info.filename.empty() ? target : info.filename;
-}
+                                  std::string_view kind);
 
 std::string effective_destination_name(const std::string& target,
                                        const VData& data,
                                        std::string_view kind,
-                                       std::string_view sourceName) {
-    if (kind == "group" || kind == "files") return {};
-    if (!data.destinationName.empty()) return data.destinationName;
-    if (kind == "program") return target;
-    return std::string(sourceName);
-}
+                                       std::string_view sourceName);
 
 // effective_kind for a (target, version) resolved out of the database.
 //
@@ -185,13 +173,7 @@ std::string effective_destination_name(const std::string& target,
 // can never dispatch, and a `program` could be denied one.
 std::string effective_kind_of(const VersionDB& db,
                               const std::string& target,
-                              const std::string& version) {
-    auto it = db.find(target);
-    if (it == db.end()) return {};
-    auto vit = it->second.versions.find(version);
-    if (vit == it->second.versions.end()) return it->second.type;
-    return effective_kind(it->second, vit->second);
-}
+                              const std::string& version);
 
 // Can a member of this kind be "left behind" in a way the user can observe?
 //
@@ -210,7 +192,7 @@ std::string effective_kind_of(const VersionDB& db,
 // 0.4.70 fall back to VInfo::type, which a damaged home can leave empty) is
 // treated as "counts". Missing a real program is the failure this whole report
 // exists to end; naming one unknown kind too many is only noise.
-bool kind_can_strand(std::string_view kind) { return kind != "group"; }
+bool kind_can_strand(std::string_view kind);
 
 // Whether ANY version of this target materializes as a program.
 //
@@ -218,15 +200,7 @@ bool kind_can_strand(std::string_view kind) { return kind != "group"; }
 // shim belongs to whichever version is active, and widening to "any version"
 // is the conservative direction here: it can only make a check report fewer
 // orphans, never fabricate one.
-bool has_program_kind(const VersionDB& db, const std::string& target) {
-    auto it = db.find(target);
-    if (it == db.end()) return false;
-    if (it->second.versions.empty()) return it->second.type == "program";
-    for (const auto& [version, data] : it->second.versions) {
-        if (effective_kind(it->second, data) == "program") return true;
-    }
-    return false;
-}
+bool has_program_kind(const VersionDB& db, const std::string& target);
 
 } // namespace xlings::xvm
 
diff --git a/src/interface.cpp b/src/interface.cpp
new file mode 100644
index 00000000..74ec1bd7
--- /dev/null
+++ b/src/interface.cpp
@@ -0,0 +1,303 @@
+// xlings.interface — programmatic JSON API (NDJSON over stdio).
+//
+// Spec: docs/plans/2026-04-25-interface-api-v1.md
+//
+// This module is intentionally self-contained and depends only on the
+// runtime + capabilities layers, not on any TUI / cli-internal helpers.
+// It provides a single entry point (`interface::run`) that the cli layer
+// hooks up to its `interface` subcommand action.
+
+module;
+
+#ifdef __unix__
+#include <poll.h>
+#endif
+
+module xlings.interface;
+
+import std;
+import mcpplibs.cmdline;
+import xlings.libs.json;
+import xlings.platform;
+import xlings.runtime;
+
+namespace xlings::interface {
+
+std::string event_to_ndjson_line_(const Event& e) {
+    nlohmann::json line;
+    if (auto* p = std::get_if<ProgressEvent>(&e)) {
+        line = {{"kind", "progress"}, {"phase", p->phase},
+                {"percent", p->percent}, {"message", p->message}};
+    } else if (auto* l = std::get_if<LogEvent>(&e)) {
+        const char* lvl = l->level == LogLevel::debug ? "debug"
+                        : l->level == LogLevel::info  ? "info"
+                        : l->level == LogLevel::warn  ? "warn" : "error";
+        line = {{"kind", "log"}, {"level", lvl}, {"message", l->message}};
+    } else if (auto* d = std::get_if<DataEvent>(&e)) {
+        auto payload = nlohmann::json::parse(d->json, nullptr, false);
+        line = {{"kind", "data"}, {"dataKind", d->kind},
+                {"payload", payload.is_discarded() ? nlohmann::json(d->json) : payload}};
+    } else if (auto* pr = std::get_if<PromptEvent>(&e)) {
+        line = {{"kind", "prompt"}, {"id", pr->id},
+                {"question", pr->question}, {"options", pr->options},
+                {"defaultValue", pr->defaultValue}};
+    } else if (auto* er = std::get_if<ErrorEvent>(&e)) {
+        line = {{"kind", "error"},
+                {"code", std::string(to_wire_string(er->code))},
+                {"message", er->message},
+                {"recoverable", er->recoverable}};
+        if (!er->hint.empty()) line["hint"] = er->hint;
+    } else if (std::get_if<CompletedEvent>(&e)) {
+        return "";
+    } else {
+        return "";
+    }
+    return line.dump();
+}
+
+int run(const mcpplibs::cmdline::ParsedArgs& args,
+               EventStream& stream, int tui_listener,
+               capability::Registry& registry) {
+    stream.set_enabled(tui_listener, false);
+    platform::set_tui_mode(true);
+
+    if (args.is_flag_set("version")) {
+        std::cout << nlohmann::json({{"protocol_version", kProtocolVersion}}).dump()
+                  << "\n" << std::flush;
+        return 0;
+    }
+
+    if (args.is_flag_set("list")) {
+        auto specs = registry.list_all();
+        nlohmann::json arr = nlohmann::json::array();
+        for (auto& s : specs) {
+            auto inputSchema = nlohmann::json::parse(s.inputSchema, nullptr, false);
+            auto outputSchema = nlohmann::json::parse(s.outputSchema, nullptr, false);
+            arr.push_back({
+                {"name", s.name},
+                {"description", s.description},
+                {"destructive", s.destructive},
+                {"inputSchema", inputSchema.is_discarded() ? nlohmann::json(s.inputSchema) : inputSchema},
+                {"outputSchema", outputSchema.is_discarded() ? nlohmann::json(s.outputSchema) : outputSchema},
+            });
+        }
+        nlohmann::json out = {{"protocol_version", kProtocolVersion},
+                              {"capabilities", arr}};
+        std::cout << out.dump() << "\n" << std::flush;
+        return 0;
+    }
+
+    if (args.positional_count() == 0) {
+        std::cout << R"({"kind":"result","exitCode":1,"error":"capability name required. Use --list to see available capabilities."})"
+                  << "\n" << std::flush;
+        return 1;
+    }
+
+    auto cap_name = std::string(args.positional(0));
+    std::string cap_args = "{}";
+    if (auto a = args.value("args")) cap_args = std::string(*a);
+    // --args-file <path> reads the JSON args from a file instead of the
+    // command line. Useful for clients on Windows where cmd.exe + MSVC
+    // CRT quoting makes embedded `"` characters in JSON args unreliable.
+    if (auto a = args.value("args-file")) {
+        try {
+            cap_args = platform::read_file_to_string(std::string(*a));
+        } catch (const std::exception& e) {
+            nlohmann::json err = {
+                {"kind", "error"},
+                {"code", std::string(to_wire_string(ErrorCode::InvalidInput))},
+                {"message", std::string("failed to read --args-file: ") + e.what()},
+                {"recoverable", false},
+            };
+            std::cout << err.dump() << "\n";
+            std::cout << R"({"kind":"result","exitCode":1})" << "\n" << std::flush;
+            return 1;
+        }
+    }
+
+    auto* cap = registry.get(cap_name);
+    if (!cap) {
+        nlohmann::json err = {
+            {"kind", "error"},
+            {"code", std::string(to_wire_string(ErrorCode::NotFound))},
+            {"message", "unknown capability: " + cap_name},
+            {"recoverable", false},
+            {"hint", "run `xlings interface --list` to see available capabilities"}
+        };
+        std::cout << err.dump() << "\n";
+        nlohmann::json done = {{"kind", "result"}, {"exitCode", 1}};
+        std::cout << done.dump() << "\n" << std::flush;
+        return 1;
+    }
+
+    CancellationToken token;
+    InterfaceSession session(stream, token);
+    int listener_id = stream.on_event([&session](const Event& e) {
+        session.emit_event(e);
+    });
+
+    capability::Result result;
+    int exit_code = 0;
+    try {
+        result = cap->execute(cap_args, stream, &token);
+    } catch (const CancelledException&) {
+        // #374: a client-initiated cancel is a normal, expected control-plane
+        // action — emit the dedicated E_CANCELLED (recoverable) so it reaches
+        // the wire with the CORRECT code. Emitting it also marks saw_error(),
+        // so the generic non-zero-exit backstop below does not fire and
+        // mislabel the cancellation as an internal xlings bug.
+        session.emit_event(Event{ErrorEvent{
+            .code = ErrorCode::Cancelled,
+            .message = "operation cancelled",
+            .recoverable = true,
+        }});
+        result = nlohmann::json({{"exitCode", 130}}).dump();
+        exit_code = 130;
+    } catch (const std::exception& e) {
+        // #374: route through the session (marks saw_error()) instead of a
+        // raw std::cout write — otherwise the backstop below would fire and
+        // emit a SECOND, generic error line on top of this specific one.
+        session.emit_event(Event{ErrorEvent{
+            .code = ErrorCode::Internal,
+            .message = std::string("internal: ") + e.what(),
+            .recoverable = false,
+        }});
+        result = nlohmann::json({{"exitCode", 1}}).dump();
+        exit_code = 1;
+    }
+    stream.remove_listener(listener_id);
+
+    if (exit_code == 0) {
+        auto parsed = nlohmann::json::parse(result, nullptr, false);
+        if (!parsed.is_discarded() && parsed.contains("exitCode")) {
+            exit_code = parsed["exitCode"].is_number_integer()
+                ? parsed["exitCode"].get<int>() : 0;
+        }
+    }
+
+    // #374: guarantee the interface invariant "non-zero exit ⇒ at least one
+    // error event on the wire". Any capability that exits non-zero without
+    // having emitted an ErrorEvent (e.g. a cmd_* path still routing failures
+    // through log::error, which interface mode suppresses) would otherwise
+    // produce a bare {"exitCode":N,"kind":"result"} with no diagnostics —
+    // exactly the issue #374 silent failure. Synthesize a generic error as a
+    // backstop so consumers always get a reason.
+    if (exit_code != 0 && !session.saw_error()) {
+        session.emit_event(Event{ErrorEvent{
+            .code = ErrorCode::Internal,
+            .message = cap_name + " failed (exit " + std::to_string(exit_code)
+                + ") with no error detail on the stream",
+            .recoverable = false,
+            .hint = "re-run with the xlings CLI (non-interface) for full diagnostics",
+        }});
+    }
+
+    session.emit_result(exit_code, result);
+    return exit_code;
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::interface {
+
+InterfaceSession::InterfaceSession(EventStream& stream, CancellationToken& token) : stream_(stream), token_(token),
+      last_emit_(std::chrono::steady_clock::now()) {
+    heartbeat_thread_ = std::jthread([this](std::stop_token st) { heartbeat_loop_(st); });
+    stdin_thread_     = std::jthread([this](std::stop_token st) { stdin_loop_(st); });
+}
+
+InterfaceSession::~InterfaceSession() {
+    if (heartbeat_thread_.joinable()) heartbeat_thread_.request_stop();
+    if (stdin_thread_.joinable())     stdin_thread_.request_stop();
+}
+
+void InterfaceSession::emit_event(const Event& e) {
+    // #374: track whether any structured error reached the wire so run()
+    // can guarantee "non-zero exit ⇒ at least one error event".
+    if (std::get_if<ErrorEvent>(&e)) saw_error_.store(true, std::memory_order_relaxed);
+    auto line = event_to_ndjson_line_(e);
+    if (!line.empty()) emit_raw_line_(line);
+}
+
+bool InterfaceSession::saw_error() const { return saw_error_.load(std::memory_order_relaxed); }
+
+void InterfaceSession::emit_result(int exitCode, std::string_view raw_content) {
+    nlohmann::json line;
+    line["kind"]     = "result";
+    line["exitCode"] = exitCode;
+    auto parsed = nlohmann::json::parse(raw_content, nullptr, false);
+    if (!parsed.is_discarded() && parsed.is_object()) {
+        nlohmann::json data = nlohmann::json::object();
+        for (auto it = parsed.begin(); it != parsed.end(); ++it) {
+            if (it.key() != "exitCode") data[it.key()] = it.value();
+        }
+        if (!data.empty()) line["data"] = std::move(data);
+    }
+    emit_raw_line_(line.dump());
+}
+
+void InterfaceSession::emit_raw_line_(std::string_view s) {
+    std::lock_guard lock(io_mtx_);
+    std::cout << s << "\n" << std::flush;
+    last_emit_.store(std::chrono::steady_clock::now(),
+                     std::memory_order_release);
+}
+
+void InterfaceSession::heartbeat_loop_(std::stop_token st) {
+    using namespace std::chrono;
+    while (!st.stop_requested()) {
+        std::this_thread::sleep_for(milliseconds(500));
+        if (st.stop_requested()) break;
+        auto now = steady_clock::now();
+        auto last = last_emit_.load(std::memory_order_acquire);
+        if (now - last >= seconds(5)) {
+            auto t = system_clock::to_time_t(system_clock::now());
+            std::string ts(32, '\0');
+            auto n = std::strftime(ts.data(), ts.size(), "%FT%TZ", std::gmtime(&t));
+            ts.resize(n);
+            nlohmann::json line = {{"kind", "heartbeat"}, {"ts", ts}};
+            emit_raw_line_(line.dump());
+        }
+    }
+}
+
+void InterfaceSession::stdin_loop_(std::stop_token st) {
+#ifdef __unix__
+    while (!st.stop_requested()) {
+        ::pollfd pfd{0, POLLIN, 0};
+        int rc = ::poll(&pfd, 1, 100);
+        if (rc <= 0) continue;
+        if (pfd.revents & (POLLHUP | POLLERR)) return;
+        if (!(pfd.revents & POLLIN)) continue;
+        std::string line;
+        if (!std::getline(std::cin, line)) return;
+        handle_stdin_line_(line);
+    }
+#else
+    std::string line;
+    while (!st.stop_requested() && std::getline(std::cin, line)) {
+        handle_stdin_line_(line);
+    }
+#endif
+}
+
+void InterfaceSession::handle_stdin_line_(std::string_view line) {
+    if (line.empty()) return;
+    auto j = nlohmann::json::parse(line, nullptr, false);
+    if (j.is_discarded() || !j.is_object() || !j.contains("action")) return;
+    auto action = j["action"].is_string() ? j["action"].get<std::string>() : "";
+    if (action == "cancel")        token_.cancel();
+    else if (action == "pause")    token_.pause();
+    else if (action == "resume")   token_.resume();
+    else if (action == "prompt-reply") {
+        stream_.respond(j.value("id", ""), j.value("value", ""));
+    } else {
+        emit_event(Event{LogEvent{LogLevel::warn,
+            "interface: unknown stdin action: " + action}});
+    }
+}
+
+} // namespace xlings::interface
diff --git a/src/interface.cppm b/src/interface.cppm
index fc77dc72..4686efc4 100644
--- a/src/interface.cppm
+++ b/src/interface.cppm
@@ -18,8 +18,6 @@ export module xlings.interface;
 import std;
 
 import mcpplibs.cmdline;
-import xlings.libs.json;
-import xlings.platform;
 import xlings.runtime;
 
 namespace xlings::interface {
@@ -29,144 +27,34 @@ export constexpr const char* kProtocolVersion = "1.0";
 // Convert any Event variant to one NDJSON line (no trailing newline).
 // Returns "" for events not surfaced to wire (e.g. CompletedEvent — the
 // terminal `result` line is emitted by InterfaceSession::emit_result).
-std::string event_to_ndjson_line_(const Event& e) {
-    nlohmann::json line;
-    if (auto* p = std::get_if<ProgressEvent>(&e)) {
-        line = {{"kind", "progress"}, {"phase", p->phase},
-                {"percent", p->percent}, {"message", p->message}};
-    } else if (auto* l = std::get_if<LogEvent>(&e)) {
-        const char* lvl = l->level == LogLevel::debug ? "debug"
-                        : l->level == LogLevel::info  ? "info"
-                        : l->level == LogLevel::warn  ? "warn" : "error";
-        line = {{"kind", "log"}, {"level", lvl}, {"message", l->message}};
-    } else if (auto* d = std::get_if<DataEvent>(&e)) {
-        auto payload = nlohmann::json::parse(d->json, nullptr, false);
-        line = {{"kind", "data"}, {"dataKind", d->kind},
-                {"payload", payload.is_discarded() ? nlohmann::json(d->json) : payload}};
-    } else if (auto* pr = std::get_if<PromptEvent>(&e)) {
-        line = {{"kind", "prompt"}, {"id", pr->id},
-                {"question", pr->question}, {"options", pr->options},
-                {"defaultValue", pr->defaultValue}};
-    } else if (auto* er = std::get_if<ErrorEvent>(&e)) {
-        line = {{"kind", "error"},
-                {"code", std::string(to_wire_string(er->code))},
-                {"message", er->message},
-                {"recoverable", er->recoverable}};
-        if (!er->hint.empty()) line["hint"] = er->hint;
-    } else if (std::get_if<CompletedEvent>(&e)) {
-        return "";
-    } else {
-        return "";
-    }
-    return line.dump();
-}
+std::string event_to_ndjson_line_(const Event& e);
 
 // Coordinator for one `xlings interface <cap>` invocation.
 // Owns: stdout writer mutex, heartbeat timer thread, stdin control reader
 // thread, CancellationToken driving capability execution.
 class InterfaceSession {
 public:
-    InterfaceSession(EventStream& stream, CancellationToken& token)
-        : stream_(stream), token_(token),
-          last_emit_(std::chrono::steady_clock::now()) {
-        heartbeat_thread_ = std::jthread([this](std::stop_token st) { heartbeat_loop_(st); });
-        stdin_thread_     = std::jthread([this](std::stop_token st) { stdin_loop_(st); });
-    }
+    InterfaceSession(EventStream& stream, CancellationToken& token);
 
-    ~InterfaceSession() {
-        if (heartbeat_thread_.joinable()) heartbeat_thread_.request_stop();
-        if (stdin_thread_.joinable())     stdin_thread_.request_stop();
-    }
+    ~InterfaceSession();
 
     InterfaceSession(const InterfaceSession&) = delete;
     InterfaceSession& operator=(const InterfaceSession&) = delete;
 
-    void emit_event(const Event& e) {
-        // #374: track whether any structured error reached the wire so run()
-        // can guarantee "non-zero exit ⇒ at least one error event".
-        if (std::get_if<ErrorEvent>(&e)) saw_error_.store(true, std::memory_order_relaxed);
-        auto line = event_to_ndjson_line_(e);
-        if (!line.empty()) emit_raw_line_(line);
-    }
+    void emit_event(const Event& e);
 
-    bool saw_error() const { return saw_error_.load(std::memory_order_relaxed); }
+    bool saw_error() const;
 
-    void emit_result(int exitCode, std::string_view raw_content) {
-        nlohmann::json line;
-        line["kind"]     = "result";
-        line["exitCode"] = exitCode;
-        auto parsed = nlohmann::json::parse(raw_content, nullptr, false);
-        if (!parsed.is_discarded() && parsed.is_object()) {
-            nlohmann::json data = nlohmann::json::object();
-            for (auto it = parsed.begin(); it != parsed.end(); ++it) {
-                if (it.key() != "exitCode") data[it.key()] = it.value();
-            }
-            if (!data.empty()) line["data"] = std::move(data);
-        }
-        emit_raw_line_(line.dump());
-    }
+    void emit_result(int exitCode, std::string_view raw_content);
 
 private:
-    void emit_raw_line_(std::string_view s) {
-        std::lock_guard lock(io_mtx_);
-        std::cout << s << "\n" << std::flush;
-        last_emit_.store(std::chrono::steady_clock::now(),
-                         std::memory_order_release);
-    }
+    void emit_raw_line_(std::string_view s);
 
-    void heartbeat_loop_(std::stop_token st) {
-        using namespace std::chrono;
-        while (!st.stop_requested()) {
-            std::this_thread::sleep_for(milliseconds(500));
-            if (st.stop_requested()) break;
-            auto now = steady_clock::now();
-            auto last = last_emit_.load(std::memory_order_acquire);
-            if (now - last >= seconds(5)) {
-                auto t = system_clock::to_time_t(system_clock::now());
-                std::string ts(32, '\0');
-                auto n = std::strftime(ts.data(), ts.size(), "%FT%TZ", std::gmtime(&t));
-                ts.resize(n);
-                nlohmann::json line = {{"kind", "heartbeat"}, {"ts", ts}};
-                emit_raw_line_(line.dump());
-            }
-        }
-    }
+    void heartbeat_loop_(std::stop_token st);
 
-    void stdin_loop_(std::stop_token st) {
-#ifdef __unix__
-        while (!st.stop_requested()) {
-            ::pollfd pfd{0, POLLIN, 0};
-            int rc = ::poll(&pfd, 1, 100);
-            if (rc <= 0) continue;
-            if (pfd.revents & (POLLHUP | POLLERR)) return;
-            if (!(pfd.revents & POLLIN)) continue;
-            std::string line;
-            if (!std::getline(std::cin, line)) return;
-            handle_stdin_line_(line);
-        }
-#else
-        std::string line;
-        while (!st.stop_requested() && std::getline(std::cin, line)) {
-            handle_stdin_line_(line);
-        }
-#endif
-    }
+    void stdin_loop_(std::stop_token st);
 
-    void handle_stdin_line_(std::string_view line) {
-        if (line.empty()) return;
-        auto j = nlohmann::json::parse(line, nullptr, false);
-        if (j.is_discarded() || !j.is_object() || !j.contains("action")) return;
-        auto action = j["action"].is_string() ? j["action"].get<std::string>() : "";
-        if (action == "cancel")        token_.cancel();
-        else if (action == "pause")    token_.pause();
-        else if (action == "resume")   token_.resume();
-        else if (action == "prompt-reply") {
-            stream_.respond(j.value("id", ""), j.value("value", ""));
-        } else {
-            emit_event(Event{LogEvent{LogLevel::warn,
-                "interface: unknown stdin action: " + action}});
-        }
-    }
+    void handle_stdin_line_(std::string_view line);
 
     EventStream& stream_;
     CancellationToken& token_;
@@ -186,143 +74,6 @@ private:
 //   registry       — capability registry built once per process
 export int run(const mcpplibs::cmdline::ParsedArgs& args,
                EventStream& stream, int tui_listener,
-               capability::Registry& registry) {
-    stream.set_enabled(tui_listener, false);
-    platform::set_tui_mode(true);
-
-    if (args.is_flag_set("version")) {
-        std::cout << nlohmann::json({{"protocol_version", kProtocolVersion}}).dump()
-                  << "\n" << std::flush;
-        return 0;
-    }
-
-    if (args.is_flag_set("list")) {
-        auto specs = registry.list_all();
-        nlohmann::json arr = nlohmann::json::array();
-        for (auto& s : specs) {
-            auto inputSchema = nlohmann::json::parse(s.inputSchema, nullptr, false);
-            auto outputSchema = nlohmann::json::parse(s.outputSchema, nullptr, false);
-            arr.push_back({
-                {"name", s.name},
-                {"description", s.description},
-                {"destructive", s.destructive},
-                {"inputSchema", inputSchema.is_discarded() ? nlohmann::json(s.inputSchema) : inputSchema},
-                {"outputSchema", outputSchema.is_discarded() ? nlohmann::json(s.outputSchema) : outputSchema},
-            });
-        }
-        nlohmann::json out = {{"protocol_version", kProtocolVersion},
-                              {"capabilities", arr}};
-        std::cout << out.dump() << "\n" << std::flush;
-        return 0;
-    }
-
-    if (args.positional_count() == 0) {
-        std::cout << R"({"kind":"result","exitCode":1,"error":"capability name required. Use --list to see available capabilities."})"
-                  << "\n" << std::flush;
-        return 1;
-    }
-
-    auto cap_name = std::string(args.positional(0));
-    std::string cap_args = "{}";
-    if (auto a = args.value("args")) cap_args = std::string(*a);
-    // --args-file <path> reads the JSON args from a file instead of the
-    // command line. Useful for clients on Windows where cmd.exe + MSVC
-    // CRT quoting makes embedded `"` characters in JSON args unreliable.
-    if (auto a = args.value("args-file")) {
-        try {
-            cap_args = platform::read_file_to_string(std::string(*a));
-        } catch (const std::exception& e) {
-            nlohmann::json err = {
-                {"kind", "error"},
-                {"code", std::string(to_wire_string(ErrorCode::InvalidInput))},
-                {"message", std::string("failed to read --args-file: ") + e.what()},
-                {"recoverable", false},
-            };
-            std::cout << err.dump() << "\n";
-            std::cout << R"({"kind":"result","exitCode":1})" << "\n" << std::flush;
-            return 1;
-        }
-    }
-
-    auto* cap = registry.get(cap_name);
-    if (!cap) {
-        nlohmann::json err = {
-            {"kind", "error"},
-            {"code", std::string(to_wire_string(ErrorCode::NotFound))},
-            {"message", "unknown capability: " + cap_name},
-            {"recoverable", false},
-            {"hint", "run `xlings interface --list` to see available capabilities"}
-        };
-        std::cout << err.dump() << "\n";
-        nlohmann::json done = {{"kind", "result"}, {"exitCode", 1}};
-        std::cout << done.dump() << "\n" << std::flush;
-        return 1;
-    }
-
-    CancellationToken token;
-    InterfaceSession session(stream, token);
-    int listener_id = stream.on_event([&session](const Event& e) {
-        session.emit_event(e);
-    });
-
-    capability::Result result;
-    int exit_code = 0;
-    try {
-        result = cap->execute(cap_args, stream, &token);
-    } catch (const CancelledException&) {
-        // #374: a client-initiated cancel is a normal, expected control-plane
-        // action — emit the dedicated E_CANCELLED (recoverable) so it reaches
-        // the wire with the CORRECT code. Emitting it also marks saw_error(),
-        // so the generic non-zero-exit backstop below does not fire and
-        // mislabel the cancellation as an internal xlings bug.
-        session.emit_event(Event{ErrorEvent{
-            .code = ErrorCode::Cancelled,
-            .message = "operation cancelled",
-            .recoverable = true,
-        }});
-        result = nlohmann::json({{"exitCode", 130}}).dump();
-        exit_code = 130;
-    } catch (const std::exception& e) {
-        // #374: route through the session (marks saw_error()) instead of a
-        // raw std::cout write — otherwise the backstop below would fire and
-        // emit a SECOND, generic error line on top of this specific one.
-        session.emit_event(Event{ErrorEvent{
-            .code = ErrorCode::Internal,
-            .message = std::string("internal: ") + e.what(),
-            .recoverable = false,
-        }});
-        result = nlohmann::json({{"exitCode", 1}}).dump();
-        exit_code = 1;
-    }
-    stream.remove_listener(listener_id);
-
-    if (exit_code == 0) {
-        auto parsed = nlohmann::json::parse(result, nullptr, false);
-        if (!parsed.is_discarded() && parsed.contains("exitCode")) {
-            exit_code = parsed["exitCode"].is_number_integer()
-                ? parsed["exitCode"].get<int>() : 0;
-        }
-    }
-
-    // #374: guarantee the interface invariant "non-zero exit ⇒ at least one
-    // error event on the wire". Any capability that exits non-zero without
-    // having emitted an ErrorEvent (e.g. a cmd_* path still routing failures
-    // through log::error, which interface mode suppresses) would otherwise
-    // produce a bare {"exitCode":N,"kind":"result"} with no diagnostics —
-    // exactly the issue #374 silent failure. Synthesize a generic error as a
-    // backstop so consumers always get a reason.
-    if (exit_code != 0 && !session.saw_error()) {
-        session.emit_event(Event{ErrorEvent{
-            .code = ErrorCode::Internal,
-            .message = cap_name + " failed (exit " + std::to_string(exit_code)
-                + ") with no error detail on the stream",
-            .recoverable = false,
-            .hint = "re-run with the xlings CLI (non-interface) for full diagnostics",
-        }});
-    }
-
-    session.emit_result(exit_code, result);
-    return exit_code;
-}
+               capability::Registry& registry);
 
 }  // namespace xlings::interface
diff --git a/src/libs/sha256.cpp b/src/libs/sha256.cpp
new file mode 100644
index 00000000..665b6bca
--- /dev/null
+++ b/src/libs/sha256.cpp
@@ -0,0 +1,129 @@
+// xlings.libs.sha256 — in-process SHA-256 (FIPS 180-4).
+//
+// Exists because the downloader used to shell out to `sha256sum`, which
+// is a GNU coreutils tool: absent on stock macOS (which only ships
+// `shasum`), so every sha256-pinned download "mismatched" on hosts
+// without coreutils regardless of payload integrity (mcpp issue #120's
+// fresh-install lane caught this on the macos-14 runner image).
+// Hashing in-process removes the host-tool dependency on every platform.
+
+module xlings.libs.sha256;
+
+import std;
+
+namespace xlings::sha256 {
+
+std::string hex(std::string_view data) {
+    Hasher h;
+    h.update(data.data(), data.size());
+    return h.hex_digest();
+}
+
+std::optional<std::string> hex_file(const std::filesystem::path& path) {
+    std::ifstream in(path, std::ios::binary);
+    if (!in) return std::nullopt;
+    Hasher h;
+    char buf[64 * 1024];
+    while (in.read(buf, sizeof(buf)) || in.gcount() > 0)
+        h.update(buf, static_cast<std::size_t>(in.gcount()));
+    if (in.bad()) return std::nullopt;
+    return h.hex_digest();
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::sha256 {
+
+Hasher::Hasher() { reset(); }
+
+void Hasher::reset() {
+    h_ = {0x6a09e667u, 0xbb67ae85u, 0x3c6ef372u, 0xa54ff53au,
+          0x510e527fu, 0x9b05688cu, 0x1f83d9abu, 0x5be0cd19u};
+    buflen_ = 0;
+    total_  = 0;
+}
+
+void Hasher::update(const void* data, std::size_t len) {
+    auto p = static_cast<const unsigned char*>(data);
+    total_ += len;
+    while (len > 0) {
+        std::size_t take = std::min(len, sizeof(buf_) - buflen_);
+        std::memcpy(buf_ + buflen_, p, take);
+        buflen_ += take;
+        p += take;
+        len -= take;
+        if (buflen_ == sizeof(buf_)) {
+            compress_(buf_);
+            buflen_ = 0;
+        }
+    }
+}
+
+std::string Hasher::hex_digest() {
+    unsigned char pad[72]{};
+    pad[0] = 0x80;
+    std::uint64_t bits = total_ * 8;
+    // Pad to 56 mod 64, then the 64-bit big-endian length.
+    std::size_t padlen = (buflen_ < 56) ? (56 - buflen_) : (120 - buflen_);
+    update(pad, padlen);
+    unsigned char lenbe[8];
+    for (int i = 0; i < 8; ++i)
+        lenbe[i] = static_cast<unsigned char>(bits >> (56 - 8 * i));
+    total_ -= padlen;  // length bytes are not message bytes
+    update(lenbe, 8);
+
+    std::string out;
+    out.reserve(64);
+    constexpr char hexd[] = "0123456789abcdef";
+    for (std::uint32_t w : h_) {
+        for (int s = 28; s >= 0; s -= 4)
+            out.push_back(hexd[(w >> s) & 0xF]);
+    }
+    return out;
+}
+
+std::uint32_t Hasher::rotr_(std::uint32_t x, int n) {
+    return (x >> n) | (x << (32 - n));
+}
+
+void Hasher::compress_(const unsigned char* block) {
+    static constexpr std::uint32_t K[64] = {
+        0x428a2f98u,0x71374491u,0xb5c0fbcfu,0xe9b5dba5u,0x3956c25bu,0x59f111f1u,0x923f82a4u,0xab1c5ed5u,
+        0xd807aa98u,0x12835b01u,0x243185beu,0x550c7dc3u,0x72be5d74u,0x80deb1feu,0x9bdc06a7u,0xc19bf174u,
+        0xe49b69c1u,0xefbe4786u,0x0fc19dc6u,0x240ca1ccu,0x2de92c6fu,0x4a7484aau,0x5cb0a9dcu,0x76f988dau,
+        0x983e5152u,0xa831c66du,0xb00327c8u,0xbf597fc7u,0xc6e00bf3u,0xd5a79147u,0x06ca6351u,0x14292967u,
+        0x27b70a85u,0x2e1b2138u,0x4d2c6dfcu,0x53380d13u,0x650a7354u,0x766a0abbu,0x81c2c92eu,0x92722c85u,
+        0xa2bfe8a1u,0xa81a664bu,0xc24b8b70u,0xc76c51a3u,0xd192e819u,0xd6990624u,0xf40e3585u,0x106aa070u,
+        0x19a4c116u,0x1e376c08u,0x2748774cu,0x34b0bcb5u,0x391c0cb3u,0x4ed8aa4au,0x5b9cca4fu,0x682e6ff3u,
+        0x748f82eeu,0x78a5636fu,0x84c87814u,0x8cc70208u,0x90befffau,0xa4506cebu,0xbef9a3f7u,0xc67178f2u,
+    };
+    std::uint32_t w[64];
+    for (int i = 0; i < 16; ++i) {
+        w[i] = (std::uint32_t(block[i*4]) << 24) | (std::uint32_t(block[i*4+1]) << 16)
+             | (std::uint32_t(block[i*4+2]) << 8) | std::uint32_t(block[i*4+3]);
+    }
+    for (int i = 16; i < 64; ++i) {
+        std::uint32_t s0 = rotr_(w[i-15], 7) ^ rotr_(w[i-15], 18) ^ (w[i-15] >> 3);
+        std::uint32_t s1 = rotr_(w[i-2], 17) ^ rotr_(w[i-2], 19) ^ (w[i-2] >> 10);
+        w[i] = w[i-16] + s0 + w[i-7] + s1;
+    }
+    auto a = h_[0], b = h_[1], c = h_[2], d = h_[3];
+    auto e = h_[4], f = h_[5], g = h_[6], h = h_[7];
+    for (int i = 0; i < 64; ++i) {
+        std::uint32_t S1 = rotr_(e, 6) ^ rotr_(e, 11) ^ rotr_(e, 25);
+        std::uint32_t ch = (e & f) ^ (~e & g);
+        std::uint32_t t1 = h + S1 + ch + K[i] + w[i];
+        std::uint32_t S0 = rotr_(a, 2) ^ rotr_(a, 13) ^ rotr_(a, 22);
+        std::uint32_t mj = (a & b) ^ (a & c) ^ (b & c);
+        std::uint32_t t2 = S0 + mj;
+        h = g; g = f; f = e; e = d + t1;
+        d = c; c = b; b = a; a = t1 + t2;
+    }
+    h_[0] += a; h_[1] += b; h_[2] += c; h_[3] += d;
+    h_[4] += e; h_[5] += f; h_[6] += g; h_[7] += h;
+}
+
+} // namespace xlings::sha256
diff --git a/src/libs/sha256.cppm b/src/libs/sha256.cppm
index 9a83c219..1ccff9ac 100644
--- a/src/libs/sha256.cppm
+++ b/src/libs/sha256.cppm
@@ -16,97 +16,20 @@ export namespace xlings::sha256 {
 // Streaming SHA-256 context.
 class Hasher {
 public:
-    Hasher() { reset(); }
+    Hasher();
 
-    void reset() {
-        h_ = {0x6a09e667u, 0xbb67ae85u, 0x3c6ef372u, 0xa54ff53au,
-              0x510e527fu, 0x9b05688cu, 0x1f83d9abu, 0x5be0cd19u};
-        buflen_ = 0;
-        total_  = 0;
-    }
+    void reset();
 
-    void update(const void* data, std::size_t len) {
-        auto p = static_cast<const unsigned char*>(data);
-        total_ += len;
-        while (len > 0) {
-            std::size_t take = std::min(len, sizeof(buf_) - buflen_);
-            std::memcpy(buf_ + buflen_, p, take);
-            buflen_ += take;
-            p += take;
-            len -= take;
-            if (buflen_ == sizeof(buf_)) {
-                compress_(buf_);
-                buflen_ = 0;
-            }
-        }
-    }
+    void update(const void* data, std::size_t len);
 
     // Finalize and return the lowercase hex digest. The context is
     // consumed; call reset() to reuse.
-    std::string hex_digest() {
-        unsigned char pad[72]{};
-        pad[0] = 0x80;
-        std::uint64_t bits = total_ * 8;
-        // Pad to 56 mod 64, then the 64-bit big-endian length.
-        std::size_t padlen = (buflen_ < 56) ? (56 - buflen_) : (120 - buflen_);
-        update(pad, padlen);
-        unsigned char lenbe[8];
-        for (int i = 0; i < 8; ++i)
-            lenbe[i] = static_cast<unsigned char>(bits >> (56 - 8 * i));
-        total_ -= padlen;  // length bytes are not message bytes
-        update(lenbe, 8);
-
-        std::string out;
-        out.reserve(64);
-        constexpr char hexd[] = "0123456789abcdef";
-        for (std::uint32_t w : h_) {
-            for (int s = 28; s >= 0; s -= 4)
-                out.push_back(hexd[(w >> s) & 0xF]);
-        }
-        return out;
-    }
+    std::string hex_digest();
 
 private:
-    static std::uint32_t rotr_(std::uint32_t x, int n) {
-        return (x >> n) | (x << (32 - n));
-    }
+    static std::uint32_t rotr_(std::uint32_t x, int n);
 
-    void compress_(const unsigned char* block) {
-        static constexpr std::uint32_t K[64] = {
-            0x428a2f98u,0x71374491u,0xb5c0fbcfu,0xe9b5dba5u,0x3956c25bu,0x59f111f1u,0x923f82a4u,0xab1c5ed5u,
-            0xd807aa98u,0x12835b01u,0x243185beu,0x550c7dc3u,0x72be5d74u,0x80deb1feu,0x9bdc06a7u,0xc19bf174u,
-            0xe49b69c1u,0xefbe4786u,0x0fc19dc6u,0x240ca1ccu,0x2de92c6fu,0x4a7484aau,0x5cb0a9dcu,0x76f988dau,
-            0x983e5152u,0xa831c66du,0xb00327c8u,0xbf597fc7u,0xc6e00bf3u,0xd5a79147u,0x06ca6351u,0x14292967u,
-            0x27b70a85u,0x2e1b2138u,0x4d2c6dfcu,0x53380d13u,0x650a7354u,0x766a0abbu,0x81c2c92eu,0x92722c85u,
-            0xa2bfe8a1u,0xa81a664bu,0xc24b8b70u,0xc76c51a3u,0xd192e819u,0xd6990624u,0xf40e3585u,0x106aa070u,
-            0x19a4c116u,0x1e376c08u,0x2748774cu,0x34b0bcb5u,0x391c0cb3u,0x4ed8aa4au,0x5b9cca4fu,0x682e6ff3u,
-            0x748f82eeu,0x78a5636fu,0x84c87814u,0x8cc70208u,0x90befffau,0xa4506cebu,0xbef9a3f7u,0xc67178f2u,
-        };
-        std::uint32_t w[64];
-        for (int i = 0; i < 16; ++i) {
-            w[i] = (std::uint32_t(block[i*4]) << 24) | (std::uint32_t(block[i*4+1]) << 16)
-                 | (std::uint32_t(block[i*4+2]) << 8) | std::uint32_t(block[i*4+3]);
-        }
-        for (int i = 16; i < 64; ++i) {
-            std::uint32_t s0 = rotr_(w[i-15], 7) ^ rotr_(w[i-15], 18) ^ (w[i-15] >> 3);
-            std::uint32_t s1 = rotr_(w[i-2], 17) ^ rotr_(w[i-2], 19) ^ (w[i-2] >> 10);
-            w[i] = w[i-16] + s0 + w[i-7] + s1;
-        }
-        auto a = h_[0], b = h_[1], c = h_[2], d = h_[3];
-        auto e = h_[4], f = h_[5], g = h_[6], h = h_[7];
-        for (int i = 0; i < 64; ++i) {
-            std::uint32_t S1 = rotr_(e, 6) ^ rotr_(e, 11) ^ rotr_(e, 25);
-            std::uint32_t ch = (e & f) ^ (~e & g);
-            std::uint32_t t1 = h + S1 + ch + K[i] + w[i];
-            std::uint32_t S0 = rotr_(a, 2) ^ rotr_(a, 13) ^ rotr_(a, 22);
-            std::uint32_t mj = (a & b) ^ (a & c) ^ (b & c);
-            std::uint32_t t2 = S0 + mj;
-            h = g; g = f; f = e; e = d + t1;
-            d = c; c = b; b = a; a = t1 + t2;
-        }
-        h_[0] += a; h_[1] += b; h_[2] += c; h_[3] += d;
-        h_[4] += e; h_[5] += f; h_[6] += g; h_[7] += h;
-    }
+    void compress_(const unsigned char* block);
 
     std::array<std::uint32_t, 8> h_{};
     unsigned char buf_[64]{};
@@ -115,22 +38,9 @@ private:
 };
 
 // Hex digest of a memory buffer.
-std::string hex(std::string_view data) {
-    Hasher h;
-    h.update(data.data(), data.size());
-    return h.hex_digest();
-}
+std::string hex(std::string_view data);
 
 // Hex digest of a file's contents (streaming; empty optional on I/O error).
-std::optional<std::string> hex_file(const std::filesystem::path& path) {
-    std::ifstream in(path, std::ios::binary);
-    if (!in) return std::nullopt;
-    Hasher h;
-    char buf[64 * 1024];
-    while (in.read(buf, sizeof(buf)) || in.gcount() > 0)
-        h.update(buf, static_cast<std::size_t>(in.gcount()));
-    if (in.bad()) return std::nullopt;
-    return h.hex_digest();
-}
+std::optional<std::string> hex_file(const std::filesystem::path& path);
 
 } // namespace xlings::sha256
diff --git a/src/libs/tinyhttps.cpp b/src/libs/tinyhttps.cpp
new file mode 100644
index 00000000..4bb47076
--- /dev/null
+++ b/src/libs/tinyhttps.cpp
@@ -0,0 +1,371 @@
+module xlings.libs.tinyhttps;
+
+import std;
+import mcpplibs.tinyhttps;
+import xlings.core.log;
+
+namespace xlings::tinyhttps {
+
+namespace detail_ {
+
+std::string url_host_(std::string_view url) {
+    auto s = std::string{url};
+    if (auto p = s.find("://"); p != std::string::npos) s = s.substr(p + 3);
+    if (auto p = s.find('/'); p != std::string::npos) s = s.substr(0, p);
+    if (auto p = s.rfind(':'); p != std::string::npos) {
+        // Don't lop off a colon that's actually IPv6 part — but proxy-via-env
+        // for IPv6 is enough of an edge case to ignore here.
+        s = s.substr(0, p);
+    }
+    return s;
+}
+
+bool host_in_no_proxy_(std::string_view host, std::string_view np) {
+    std::size_t i = 0;
+    while (i < np.size()) {
+        auto end = np.find(',', i);
+        auto entry = np.substr(i, end == std::string_view::npos ? std::string_view::npos : end - i);
+        i = (end == std::string_view::npos) ? np.size() : end + 1;
+        // trim spaces
+        while (!entry.empty() && (entry.front() == ' ' || entry.front() == '\t')) entry.remove_prefix(1);
+        while (!entry.empty() && (entry.back()  == ' ' || entry.back()  == '\t')) entry.remove_suffix(1);
+        if (entry.empty()) continue;
+        if (entry == "*") return true;
+        if (entry.front() == '.') entry.remove_prefix(1);
+        if (host == entry) return true;
+        if (host.size() > entry.size()
+            && host[host.size() - entry.size() - 1] == '.'
+            && host.substr(host.size() - entry.size()) == entry) {
+            return true;
+        }
+    }
+    return false;
+}
+
+std::string env_proxy_for_(std::string_view url) {
+    // Two-name lookup: try uppercase first, then lowercase. Avoids the
+    // GNU `?:` binary-conditional extension (MSVC rejects it).
+    auto get_either = [](const char* a, const char* b) -> const char* {
+        if (auto v = std::getenv(a); v && *v) return v;
+        if (auto v = std::getenv(b); v && *v) return v;
+        return nullptr;
+    };
+
+    // NO_PROXY exemption first.
+    if (auto np = get_either("NO_PROXY", "no_proxy")) {
+        if (host_in_no_proxy_(url_host_(url), np)) return {};
+    }
+
+    bool isHttps = url.starts_with("https://");
+    if (isHttps) {
+        if (auto p = get_either("HTTPS_PROXY", "https_proxy")) return p;
+    } else {
+        if (auto p = get_either("HTTP_PROXY", "http_proxy")) return p;
+    }
+    if (auto p = get_either("ALL_PROXY", "all_proxy")) return p;
+    return {};
+}
+
+auto make_client(int connectTimeoutSec, int readTimeoutSec, std::string_view url)
+    -> mcpplibs::tinyhttps::HttpClient {
+    mcpplibs::tinyhttps::HttpClientConfig cfg;
+    cfg.connectTimeoutMs = connectTimeoutSec * 1000;
+    cfg.readTimeoutMs = readTimeoutSec * 1000;
+    cfg.verifySsl = true;
+    cfg.keepAlive = false;
+    cfg.maxRedirects = 10;
+    if (auto proxy = env_proxy_for_(url); !proxy.empty()) {
+        log::debug("tinyhttps: using proxy {} for {}", proxy, url);
+        cfg.proxy = std::move(proxy);
+    }
+    return mcpplibs::tinyhttps::HttpClient(std::move(cfg));
+}
+
+std::pair<int, int> effective_low_speed_(int limitBytes, int windowSec) {
+    const char* env = std::getenv("XLINGS_DOWNLOAD_LOW_SPEED");
+    if (!env || !*env) return {limitBytes, windowSec};
+    std::string v = env;
+    if (v == "off" || v == "0") return {0, 0};
+    auto colon = v.find(':');
+    if (colon != std::string::npos) {
+        try {
+            int b = std::stoi(v.substr(0, colon));
+            int s = std::stoi(v.substr(colon + 1));
+            if (b >= 0 && s >= 0) return {b, s};
+        } catch (...) {}
+    }
+    return {limitBytes, windowSec};
+}
+
+DownloadFileResult download_once(const std::string& url, const std::filesystem::path& dest, int connectSec, int maxSec, int lowSpeedLimitBytes, int lowSpeedTimeSec, std::function<void(double, double)> onProgress, std::function<bool()> isCancelled) {
+    StallDetector detector(lowSpeedLimitBytes, lowSpeedTimeSec);
+
+    // With the watchdog enabled, lower the per-read socket timeout so a
+    // connection that sends NOTHING (progress never fires) also fails
+    // quickly instead of sitting on the full maxTime budget.
+    int readSec = maxSec;
+    if (detector.enabled()) {
+        readSec = std::min(maxSec, std::max(30, 2 * lowSpeedTimeSec));
+    }
+    auto client = make_client(connectSec, readSec, url);
+
+    bool stalled = false;
+    auto t0 = std::chrono::steady_clock::now();
+
+    mcpplibs::tinyhttps::DownloadProgressFn progress;
+    if (onProgress || detector.enabled()) {
+        progress = [&](std::int64_t total, std::int64_t downloaded) {
+            if (onProgress) {
+                onProgress(static_cast<double>(total),
+                           static_cast<double>(downloaded));
+            }
+            if (!stalled && detector.enabled()) {
+                auto elapsed = std::chrono::duration<double>(
+                    std::chrono::steady_clock::now() - t0).count();
+                if (detector.update(elapsed, static_cast<double>(downloaded))) {
+                    stalled = true;
+                }
+            }
+        };
+    }
+
+    std::function<bool()> cancel;
+    if (isCancelled || detector.enabled()) {
+        cancel = [&]() -> bool {
+            if (stalled) return true;
+            return isCancelled && isCancelled();
+        };
+    }
+
+    auto result = client.download_to_file(url, dest, progress, cancel);
+
+    if (result.ok() && !stalled) {
+        return {
+            .success = true,
+            .bytesWritten = result.bytesWritten,
+            .expectedBytes = result.expectedBytes,
+            .finalUrl = result.finalUrl,
+            .etag = result.etag,
+            .lastModified = result.lastModified,
+        };
+    }
+    if (stalled) {
+        return {false, std::format(
+            "stalled: average speed below {} B/s over {} s "
+            "(set XLINGS_DOWNLOAD_LOW_SPEED=off to disable the watchdog)",
+            lowSpeedLimitBytes, lowSpeedTimeSec)};
+    }
+    return {
+        .success = false,
+        .error = result.error.empty()
+            ? "HTTP " + std::to_string(result.statusCode) : result.error,
+        .bytesWritten = result.bytesWritten,
+        .expectedBytes = result.expectedBytes,
+        .finalUrl = result.finalUrl,
+        .etag = result.etag,
+        .lastModified = result.lastModified,
+    };
+}
+
+}
+
+std::string resolve_proxy(std::string_view url) {
+    return detail_::env_proxy_for_(url);
+}
+
+void global_init() {
+    mcpplibs::tinyhttps::Socket::platform_init();
+}
+
+void global_cleanup() {
+    mcpplibs::tinyhttps::Socket::platform_cleanup();
+}
+
+DownloadFileResult download_file(const DownloadOptions& opts) {
+    global_init();
+    if (opts.urls.empty()) return {false, "no URLs provided"};
+
+    std::error_code ec;
+    std::filesystem::create_directories(opts.destFile.parent_path(), ec);
+
+    auto [lowSpeedBytes, lowSpeedSecs] = detail_::effective_low_speed_(
+        opts.lowSpeedLimitBytes, opts.lowSpeedTimeSec);
+
+    // Breadth first: every candidate gets its first attempt before any
+    // candidate gets its second.
+    //
+    // This used to be the other way round -- `for url { for attempt { } }` --
+    // which meant one bad host could consume the entire download before the
+    // next URL was ever contacted. With the shipped settings that is
+    // `retryCount` 3 + 1 attempts x `maxTimeSec` 600 = **40 minutes on the
+    // first candidate**, while a healthy mirror sat untried. The stall
+    // watchdog does not help: it only fires below ~10 KB/s, and the measured
+    // case was a source holding a steady ~105 KB/s -- slow enough to take
+    // half an hour for a 36 MB package, fast enough to never look stalled.
+    //
+    // The per-candidate attempt budget is unchanged, and so is every
+    // give-up-on-this-host rule; only the order changes. A host that failed
+    // for a transient reason is still worth a second try, just not before the
+    // alternatives have had a first one.
+    std::string lastErr;
+    std::vector<bool> exhausted(opts.urls.size(), false);
+    for (int round = 0; round <= opts.retryCount; ++round) {
+        bool anyLive = false;
+        for (std::size_t i = 0; i < opts.urls.size(); ++i) {
+            if (exhausted[i]) continue;
+            const auto& url = opts.urls[i];
+            if (opts.isCancelled && opts.isCancelled()) return {false, "cancelled"};
+            anyLive = true;
+            auto r = opts.transferOverride
+                ? opts.transferOverride(url, opts.destFile)
+                : detail_::download_once(url, opts.destFile,
+                      opts.connectTimeoutSec, opts.maxTimeSec,
+                      lowSpeedBytes, lowSpeedSecs,
+                      opts.onProgress, opts.isCancelled);
+            if (r.success) {
+                // Candidate acceptance: integrity failures are a property
+                // of the SOURCE, not the transfer — reject and move to
+                // the next URL rather than failing the whole download.
+                std::string verdict =
+                    opts.onVerify ? opts.onVerify(url) : std::string{};
+                if (verdict.empty()) {
+                    r.sourceUrl = url;
+                    return r;
+                }
+                lastErr = verdict;
+                if (opts.onUrlAttemptFailed) opts.onUrlAttemptFailed(url, verdict);
+                std::filesystem::remove(opts.destFile, ec);
+                // The same bytes would fail again: this source is out for
+                // good, not just for this round.
+                exhausted[i] = true;
+                continue;
+            }
+            lastErr = r.error;
+            if (opts.onUrlAttemptFailed) opts.onUrlAttemptFailed(url, r.error);
+            std::filesystem::remove(opts.destFile, ec);
+            // A stalled attempt means this host is throttled for us right
+            // now — retrying it would burn another full window.
+            if (r.error.rfind("stalled:", 0) == 0) exhausted[i] = true;
+        }
+        if (!anyLive) break;
+        if (round < opts.retryCount) {
+            std::this_thread::sleep_for(
+                std::chrono::milliseconds(500 * (round + 1)));
+        }
+    }
+    return {false, lastErr};
+}
+
+double probe_latency(const std::string& url, int timeoutMs) {
+    global_init();
+    mcpplibs::tinyhttps::Socket sock;
+    // Extract host and port from URL
+    std::string rest = url;
+    auto sep = rest.find("://");
+    if (sep != std::string::npos) rest = rest.substr(sep + 3);
+    auto slash = rest.find('/');
+    if (slash != std::string::npos) rest = rest.substr(0, slash);
+
+    int port = url.find("https") != std::string::npos ? 443 : 80;
+    std::string host = rest;
+    auto colon = rest.rfind(':');
+    if (colon != std::string::npos) {
+        host = rest.substr(0, colon);
+        try { port = std::stoi(rest.substr(colon + 1)); } catch (...) {}
+    }
+
+    auto t0 = std::chrono::steady_clock::now();
+    if (!sock.connect(host.c_str(), port, timeoutMs)) {
+        return std::numeric_limits<double>::infinity();
+    }
+    sock.close();
+    auto t1 = std::chrono::steady_clock::now();
+    return std::chrono::duration<double>(t1 - t0).count();
+}
+
+bool fetch_to_file(const std::string& url, const std::filesystem::path& dest) {
+    DownloadOptions o;
+    o.destFile = dest;
+    o.urls = {url};
+    o.retryCount = 3;
+    o.connectTimeoutSec = 30;
+    o.maxTimeSec = 120;
+    return download_file(o).success;
+}
+
+RemoteFileMeta query_remote_meta(const std::string& url, int connectTimeoutSec) {
+    RemoteFileMeta meta;
+    global_init();
+    auto client = detail_::make_client(connectTimeoutSec, /*readTimeoutSec=*/60, url);
+
+    mcpplibs::tinyhttps::HttpRequest req;
+    req.method = mcpplibs::tinyhttps::Method::HEAD;
+    req.url = url;
+    req.headers["User-Agent"] = "xlings/1.0";
+
+    auto resp = client.send(req);
+    meta.statusCode = resp.statusCode;
+
+    if (!resp.ok()) {
+        meta.error = resp.statusText.empty()
+            ? std::format("HTTP {}", resp.statusCode)
+            : std::format("HTTP {} {}", resp.statusCode, resp.statusText);
+        return meta;
+    }
+
+    // Case-insensitive header lookup
+    for (auto& [k, v] : resp.headers) {
+        std::string lower = k;
+        for (auto& c : lower) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+        if (lower == "content-length") {
+            try { meta.contentLength = std::stoll(v); } catch (...) { meta.contentLength = -1; }
+        } else if (lower == "last-modified") {
+            meta.lastModified = v;
+        } else if (lower == "etag") {
+            meta.etag = v;
+        }
+    }
+    meta.ok = true;
+    return meta;
+}
+
+std::int64_t query_content_length(const std::string& url, int connectTimeoutSec) {
+    auto meta = query_remote_meta(url, connectTimeoutSec);
+    return meta.ok ? meta.contentLength : -1;
+}
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::tinyhttps {
+
+StallDetector::StallDetector(int limitBytes, int windowSec) : limit_(limitBytes), window_(windowSec) {}
+
+bool StallDetector::enabled() const { return limit_ > 0 && window_ > 0; }
+
+bool StallDetector::update(double elapsedSec, double downloadedBytes) {
+    if (!enabled()) return false;
+    if (!started_) {
+        started_ = true;
+        winT_ = elapsedSec;
+        winB_ = downloadedBytes;
+        return false;
+    }
+    if (downloadedBytes < winB_) {
+        // Counter went backwards (redirect restart) — restart the window.
+        winT_ = elapsedSec;
+        winB_ = downloadedBytes;
+        return false;
+    }
+    if (elapsedSec - winT_ < static_cast<double>(window_)) return false;
+    double avg = (downloadedBytes - winB_) / (elapsedSec - winT_);
+    if (avg < static_cast<double>(limit_)) return true;
+    // Healthy window — slide forward.
+    winT_ = elapsedSec;
+    winB_ = downloadedBytes;
+    return false;
+}
+
+} // namespace xlings::tinyhttps
diff --git a/src/libs/tinyhttps.cppm b/src/libs/tinyhttps.cppm
index 338d3806..76170951 100644
--- a/src/libs/tinyhttps.cppm
+++ b/src/libs/tinyhttps.cppm
@@ -66,35 +66,13 @@ struct DownloadOptions {
 // progress callback. Exported for unit tests.
 class StallDetector {
 public:
-    StallDetector(int limitBytes, int windowSec)
-        : limit_(limitBytes), window_(windowSec) {}
+    StallDetector(int limitBytes, int windowSec);
 
-    bool enabled() const { return limit_ > 0 && window_ > 0; }
+    bool enabled() const;
 
     // Feed one sample. Returns true when the windowed average speed over a
     // full window fell below the limit (= stalled).
-    bool update(double elapsedSec, double downloadedBytes) {
-        if (!enabled()) return false;
-        if (!started_) {
-            started_ = true;
-            winT_ = elapsedSec;
-            winB_ = downloadedBytes;
-            return false;
-        }
-        if (downloadedBytes < winB_) {
-            // Counter went backwards (redirect restart) — restart the window.
-            winT_ = elapsedSec;
-            winB_ = downloadedBytes;
-            return false;
-        }
-        if (elapsedSec - winT_ < static_cast<double>(window_)) return false;
-        double avg = (downloadedBytes - winB_) / (elapsedSec - winT_);
-        if (avg < static_cast<double>(limit_)) return true;
-        // Healthy window — slide forward.
-        winT_ = elapsedSec;
-        winB_ = downloadedBytes;
-        return false;
-    }
+    bool update(double elapsedSec, double downloadedBytes);
 
 private:
     int    limit_;
@@ -139,17 +117,7 @@ namespace detail_ {
 
 // Pull host out of an http(s) URL: "https://example.com:443/foo" → "example.com".
 // Used by NO_PROXY suffix matching.
-std::string url_host_(std::string_view url) {
-    auto s = std::string{url};
-    if (auto p = s.find("://"); p != std::string::npos) s = s.substr(p + 3);
-    if (auto p = s.find('/'); p != std::string::npos) s = s.substr(0, p);
-    if (auto p = s.rfind(':'); p != std::string::npos) {
-        // Don't lop off a colon that's actually IPv6 part — but proxy-via-env
-        // for IPv6 is enough of an edge case to ignore here.
-        s = s.substr(0, p);
-    }
-    return s;
-}
+std::string url_host_(std::string_view url);
 
 // libcurl/curl/Go-net compatible NO_PROXY matcher.
 // `np` is comma-separated entries; an entry matches `host` if:
@@ -157,89 +125,21 @@ std::string url_host_(std::string_view url) {
 //   - leading dot suffix match (`.example.com` matches `foo.example.com` and `example.com`)
 //   - bare suffix (`example.com` matches `foo.example.com` and `example.com`)
 //   - `*` matches everything (rarely used; libcurl rejects it but Go honours it)
-bool host_in_no_proxy_(std::string_view host, std::string_view np) {
-    std::size_t i = 0;
-    while (i < np.size()) {
-        auto end = np.find(',', i);
-        auto entry = np.substr(i, end == std::string_view::npos ? std::string_view::npos : end - i);
-        i = (end == std::string_view::npos) ? np.size() : end + 1;
-        // trim spaces
-        while (!entry.empty() && (entry.front() == ' ' || entry.front() == '\t')) entry.remove_prefix(1);
-        while (!entry.empty() && (entry.back()  == ' ' || entry.back()  == '\t')) entry.remove_suffix(1);
-        if (entry.empty()) continue;
-        if (entry == "*") return true;
-        if (entry.front() == '.') entry.remove_prefix(1);
-        if (host == entry) return true;
-        if (host.size() > entry.size()
-            && host[host.size() - entry.size() - 1] == '.'
-            && host.substr(host.size() - entry.size()) == entry) {
-            return true;
-        }
-    }
-    return false;
-}
+bool host_in_no_proxy_(std::string_view host, std::string_view np);
 
 // Resolve which proxy to use for `url` from env, libcurl-style. Returns empty
 // string when direct connection should be used. Matches libcurl/Go/git
 // behaviour: HTTPS_PROXY for https:// URLs, HTTP_PROXY for http://, ALL_PROXY
 // as fallback, NO_PROXY exemptions, lowercase variants accepted.
-std::string env_proxy_for_(std::string_view url) {
-    // Two-name lookup: try uppercase first, then lowercase. Avoids the
-    // GNU `?:` binary-conditional extension (MSVC rejects it).
-    auto get_either = [](const char* a, const char* b) -> const char* {
-        if (auto v = std::getenv(a); v && *v) return v;
-        if (auto v = std::getenv(b); v && *v) return v;
-        return nullptr;
-    };
-
-    // NO_PROXY exemption first.
-    if (auto np = get_either("NO_PROXY", "no_proxy")) {
-        if (host_in_no_proxy_(url_host_(url), np)) return {};
-    }
-
-    bool isHttps = url.starts_with("https://");
-    if (isHttps) {
-        if (auto p = get_either("HTTPS_PROXY", "https_proxy")) return p;
-    } else {
-        if (auto p = get_either("HTTP_PROXY", "http_proxy")) return p;
-    }
-    if (auto p = get_either("ALL_PROXY", "all_proxy")) return p;
-    return {};
-}
+std::string env_proxy_for_(std::string_view url);
 
 auto make_client(int connectTimeoutSec, int readTimeoutSec, std::string_view url)
-    -> mcpplibs::tinyhttps::HttpClient {
-    mcpplibs::tinyhttps::HttpClientConfig cfg;
-    cfg.connectTimeoutMs = connectTimeoutSec * 1000;
-    cfg.readTimeoutMs = readTimeoutSec * 1000;
-    cfg.verifySsl = true;
-    cfg.keepAlive = false;
-    cfg.maxRedirects = 10;
-    if (auto proxy = env_proxy_for_(url); !proxy.empty()) {
-        log::debug("tinyhttps: using proxy {} for {}", proxy, url);
-        cfg.proxy = std::move(proxy);
-    }
-    return mcpplibs::tinyhttps::HttpClient(std::move(cfg));
-}
+    -> mcpplibs::tinyhttps::HttpClient;
 
 // Resolve the effective stall-watchdog parameters: env override > options.
 //   XLINGS_DOWNLOAD_LOW_SPEED=off|0      → disabled
 //   XLINGS_DOWNLOAD_LOW_SPEED=<b>:<s>    → custom limit bytes / window secs
-std::pair<int, int> effective_low_speed_(int limitBytes, int windowSec) {
-    const char* env = std::getenv("XLINGS_DOWNLOAD_LOW_SPEED");
-    if (!env || !*env) return {limitBytes, windowSec};
-    std::string v = env;
-    if (v == "off" || v == "0") return {0, 0};
-    auto colon = v.find(':');
-    if (colon != std::string::npos) {
-        try {
-            int b = std::stoi(v.substr(0, colon));
-            int s = std::stoi(v.substr(colon + 1));
-            if (b >= 0 && s >= 0) return {b, s};
-        } catch (...) {}
-    }
-    return {limitBytes, windowSec};
-}
+std::pair<int, int> effective_low_speed_(int limitBytes, int windowSec);
 
 // Single download attempt: stream GET url → dest file with progress + cancel
 // + optional stall watchdog.
@@ -252,241 +152,24 @@ DownloadFileResult download_once(
     int lowSpeedTimeSec,
     std::function<void(double, double)> onProgress,
     std::function<bool()> isCancelled = nullptr
-) {
-    StallDetector detector(lowSpeedLimitBytes, lowSpeedTimeSec);
-
-    // With the watchdog enabled, lower the per-read socket timeout so a
-    // connection that sends NOTHING (progress never fires) also fails
-    // quickly instead of sitting on the full maxTime budget.
-    int readSec = maxSec;
-    if (detector.enabled()) {
-        readSec = std::min(maxSec, std::max(30, 2 * lowSpeedTimeSec));
-    }
-    auto client = make_client(connectSec, readSec, url);
-
-    bool stalled = false;
-    auto t0 = std::chrono::steady_clock::now();
-
-    mcpplibs::tinyhttps::DownloadProgressFn progress;
-    if (onProgress || detector.enabled()) {
-        progress = [&](std::int64_t total, std::int64_t downloaded) {
-            if (onProgress) {
-                onProgress(static_cast<double>(total),
-                           static_cast<double>(downloaded));
-            }
-            if (!stalled && detector.enabled()) {
-                auto elapsed = std::chrono::duration<double>(
-                    std::chrono::steady_clock::now() - t0).count();
-                if (detector.update(elapsed, static_cast<double>(downloaded))) {
-                    stalled = true;
-                }
-            }
-        };
-    }
-
-    std::function<bool()> cancel;
-    if (isCancelled || detector.enabled()) {
-        cancel = [&]() -> bool {
-            if (stalled) return true;
-            return isCancelled && isCancelled();
-        };
-    }
-
-    auto result = client.download_to_file(url, dest, progress, cancel);
-
-    if (result.ok() && !stalled) {
-        return {
-            .success = true,
-            .bytesWritten = result.bytesWritten,
-            .expectedBytes = result.expectedBytes,
-            .finalUrl = result.finalUrl,
-            .etag = result.etag,
-            .lastModified = result.lastModified,
-        };
-    }
-    if (stalled) {
-        return {false, std::format(
-            "stalled: average speed below {} B/s over {} s "
-            "(set XLINGS_DOWNLOAD_LOW_SPEED=off to disable the watchdog)",
-            lowSpeedLimitBytes, lowSpeedTimeSec)};
-    }
-    return {
-        .success = false,
-        .error = result.error.empty()
-            ? "HTTP " + std::to_string(result.statusCode) : result.error,
-        .bytesWritten = result.bytesWritten,
-        .expectedBytes = result.expectedBytes,
-        .finalUrl = result.finalUrl,
-        .etag = result.etag,
-        .lastModified = result.lastModified,
-    };
-}
+);
 
 } // namespace detail_
 
-std::string resolve_proxy(std::string_view url) {
-    return detail_::env_proxy_for_(url);
-}
-
-void global_init() {
-    mcpplibs::tinyhttps::Socket::platform_init();
-}
-
-void global_cleanup() {
-    mcpplibs::tinyhttps::Socket::platform_cleanup();
-}
-
-DownloadFileResult download_file(const DownloadOptions& opts) {
-    global_init();
-    if (opts.urls.empty()) return {false, "no URLs provided"};
-
-    std::error_code ec;
-    std::filesystem::create_directories(opts.destFile.parent_path(), ec);
-
-    auto [lowSpeedBytes, lowSpeedSecs] = detail_::effective_low_speed_(
-        opts.lowSpeedLimitBytes, opts.lowSpeedTimeSec);
-
-    // Breadth first: every candidate gets its first attempt before any
-    // candidate gets its second.
-    //
-    // This used to be the other way round -- `for url { for attempt { } }` --
-    // which meant one bad host could consume the entire download before the
-    // next URL was ever contacted. With the shipped settings that is
-    // `retryCount` 3 + 1 attempts x `maxTimeSec` 600 = **40 minutes on the
-    // first candidate**, while a healthy mirror sat untried. The stall
-    // watchdog does not help: it only fires below ~10 KB/s, and the measured
-    // case was a source holding a steady ~105 KB/s -- slow enough to take
-    // half an hour for a 36 MB package, fast enough to never look stalled.
-    //
-    // The per-candidate attempt budget is unchanged, and so is every
-    // give-up-on-this-host rule; only the order changes. A host that failed
-    // for a transient reason is still worth a second try, just not before the
-    // alternatives have had a first one.
-    std::string lastErr;
-    std::vector<bool> exhausted(opts.urls.size(), false);
-    for (int round = 0; round <= opts.retryCount; ++round) {
-        bool anyLive = false;
-        for (std::size_t i = 0; i < opts.urls.size(); ++i) {
-            if (exhausted[i]) continue;
-            const auto& url = opts.urls[i];
-            if (opts.isCancelled && opts.isCancelled()) return {false, "cancelled"};
-            anyLive = true;
-            auto r = opts.transferOverride
-                ? opts.transferOverride(url, opts.destFile)
-                : detail_::download_once(url, opts.destFile,
-                      opts.connectTimeoutSec, opts.maxTimeSec,
-                      lowSpeedBytes, lowSpeedSecs,
-                      opts.onProgress, opts.isCancelled);
-            if (r.success) {
-                // Candidate acceptance: integrity failures are a property
-                // of the SOURCE, not the transfer — reject and move to
-                // the next URL rather than failing the whole download.
-                std::string verdict =
-                    opts.onVerify ? opts.onVerify(url) : std::string{};
-                if (verdict.empty()) {
-                    r.sourceUrl = url;
-                    return r;
-                }
-                lastErr = verdict;
-                if (opts.onUrlAttemptFailed) opts.onUrlAttemptFailed(url, verdict);
-                std::filesystem::remove(opts.destFile, ec);
-                // The same bytes would fail again: this source is out for
-                // good, not just for this round.
-                exhausted[i] = true;
-                continue;
-            }
-            lastErr = r.error;
-            if (opts.onUrlAttemptFailed) opts.onUrlAttemptFailed(url, r.error);
-            std::filesystem::remove(opts.destFile, ec);
-            // A stalled attempt means this host is throttled for us right
-            // now — retrying it would burn another full window.
-            if (r.error.rfind("stalled:", 0) == 0) exhausted[i] = true;
-        }
-        if (!anyLive) break;
-        if (round < opts.retryCount) {
-            std::this_thread::sleep_for(
-                std::chrono::milliseconds(500 * (round + 1)));
-        }
-    }
-    return {false, lastErr};
-}
-
-double probe_latency(const std::string& url, int timeoutMs) {
-    global_init();
-    mcpplibs::tinyhttps::Socket sock;
-    // Extract host and port from URL
-    std::string rest = url;
-    auto sep = rest.find("://");
-    if (sep != std::string::npos) rest = rest.substr(sep + 3);
-    auto slash = rest.find('/');
-    if (slash != std::string::npos) rest = rest.substr(0, slash);
-
-    int port = url.find("https") != std::string::npos ? 443 : 80;
-    std::string host = rest;
-    auto colon = rest.rfind(':');
-    if (colon != std::string::npos) {
-        host = rest.substr(0, colon);
-        try { port = std::stoi(rest.substr(colon + 1)); } catch (...) {}
-    }
-
-    auto t0 = std::chrono::steady_clock::now();
-    if (!sock.connect(host.c_str(), port, timeoutMs)) {
-        return std::numeric_limits<double>::infinity();
-    }
-    sock.close();
-    auto t1 = std::chrono::steady_clock::now();
-    return std::chrono::duration<double>(t1 - t0).count();
-}
+std::string resolve_proxy(std::string_view url);
 
-bool fetch_to_file(const std::string& url, const std::filesystem::path& dest) {
-    DownloadOptions o;
-    o.destFile = dest;
-    o.urls = {url};
-    o.retryCount = 3;
-    o.connectTimeoutSec = 30;
-    o.maxTimeSec = 120;
-    return download_file(o).success;
-}
+void global_init();
 
-RemoteFileMeta query_remote_meta(const std::string& url, int connectTimeoutSec) {
-    RemoteFileMeta meta;
-    global_init();
-    auto client = detail_::make_client(connectTimeoutSec, /*readTimeoutSec=*/60, url);
+void global_cleanup();
 
-    mcpplibs::tinyhttps::HttpRequest req;
-    req.method = mcpplibs::tinyhttps::Method::HEAD;
-    req.url = url;
-    req.headers["User-Agent"] = "xlings/1.0";
+DownloadFileResult download_file(const DownloadOptions& opts);
 
-    auto resp = client.send(req);
-    meta.statusCode = resp.statusCode;
+double probe_latency(const std::string& url, int timeoutMs);
 
-    if (!resp.ok()) {
-        meta.error = resp.statusText.empty()
-            ? std::format("HTTP {}", resp.statusCode)
-            : std::format("HTTP {} {}", resp.statusCode, resp.statusText);
-        return meta;
-    }
+bool fetch_to_file(const std::string& url, const std::filesystem::path& dest);
 
-    // Case-insensitive header lookup
-    for (auto& [k, v] : resp.headers) {
-        std::string lower = k;
-        for (auto& c : lower) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
-        if (lower == "content-length") {
-            try { meta.contentLength = std::stoll(v); } catch (...) { meta.contentLength = -1; }
-        } else if (lower == "last-modified") {
-            meta.lastModified = v;
-        } else if (lower == "etag") {
-            meta.etag = v;
-        }
-    }
-    meta.ok = true;
-    return meta;
-}
+RemoteFileMeta query_remote_meta(const std::string& url, int connectTimeoutSec);
 
-std::int64_t query_content_length(const std::string& url, int connectTimeoutSec) {
-    auto meta = query_remote_meta(url, connectTimeoutSec);
-    return meta.ok ? meta.contentLength : -1;
-}
+std::int64_t query_content_length(const std::string& url, int connectTimeoutSec);
 
 } // namespace xlings::tinyhttps
diff --git a/src/platform.cpp b/src/platform.cpp
new file mode 100644
index 00000000..4a4d9330
--- /dev/null
+++ b/src/platform.cpp
@@ -0,0 +1,414 @@
+module;
+
+#include <cstdio>
+#include <cstdlib>
+#if !defined(_WIN32)
+#include <sys/wait.h>
+#include <unistd.h>
+#include <fcntl.h>
+#else
+#include <io.h>
+#define NOMINMAX
+#include <windows.h>
+#endif
+
+module xlings.platform;
+
+import std;
+
+namespace xlings {
+
+namespace platform {
+
+std::string gRundir = std::filesystem::current_path().string();
+
+#if !defined(_WIN32)
+
+#endif
+
+[[nodiscard]] std::optional<SudoInvoker> parse_sudo_env() {
+        const char* su = std::getenv("SUDO_UID");
+        const char* sg = std::getenv("SUDO_GID");
+        if (!su || !sg || *su == '\0' || *sg == '\0') return std::nullopt;
+        char* end = nullptr;
+        unsigned long uid = std::strtoul(su, &end, 10);
+        if (end == su || *end != '\0') return std::nullopt;
+        end = nullptr;
+        unsigned long gid = std::strtoul(sg, &end, 10);
+        if (end == sg || *end != '\0') return std::nullopt;
+        const char* user = std::getenv("SUDO_USER");
+        return SudoInvoker{ static_cast<unsigned int>(uid),
+                            static_cast<unsigned int>(gid),
+                            user ? std::string{user} : std::string{} };
+    }
+
+[[nodiscard]] std::string priv_prefix() {
+        return platform_impl::is_root() ? std::string{} : std::string{"sudo "};
+    }
+
+[[nodiscard]] std::optional<SudoInvoker> sudo_invoker() {
+        if (!platform_impl::is_root()) return std::nullopt;
+        return parse_sudo_env();
+    }
+
+[[nodiscard]] std::string target_home() {
+        if (auto inv = sudo_invoker()) {
+            if (auto h = platform_impl::home_for_user_(inv->user); !h.empty())
+                return h;
+            if (!inv->user.empty()) return "/home/" + inv->user;
+        }
+        return platform_impl::get_home_dir();
+    }
+
+void chown_to_invoker(const std::filesystem::path& path, bool recursive) {
+        auto inv = sudo_invoker();
+        if (!inv) return;
+        std::error_code ec;
+        if (!std::filesystem::exists(path, ec)) return;
+        platform_impl::lchown_path_(path, inv->uid, inv->gid);
+        if (recursive && std::filesystem::is_directory(path, ec)) {
+            for (auto it = std::filesystem::recursive_directory_iterator(
+                     path,
+                     std::filesystem::directory_options::skip_permission_denied,
+                     ec);
+                 !ec && it != std::default_sentinel; it.increment(ec)) {
+                platform_impl::lchown_path_(it->path(), inv->uid, inv->gid);
+            }
+        }
+    }
+
+[[nodiscard]] std::string get_rundir() {
+        return gRundir;
+    }
+
+void set_rundir(const std::string& dir) {
+        gRundir = dir;
+    }
+
+[[nodiscard]] std::string get_system_language() {
+        try {
+            auto loc = std::locale("");
+            auto name = loc.name();
+
+            if (name.empty() || name == "C" || name == "POSIX") {
+                return "en";
+            }
+
+            if (auto pos = name.find_first_of("_-.@"); pos != std::string::npos) {
+                return name.substr(0, pos);
+            }
+
+            return name;
+        } catch (const std::runtime_error&) {
+            return "en";
+        }
+    }
+
+std::pair<int, std::string> run_command_capture(const std::string& cmd) {
+        return platform_impl::run_command_capture(cmd);
+    }
+
+[[nodiscard]] std::string host_glibc_version() {
+#if defined(__linux__)
+        auto [rc, out] = run_command_capture(
+            "/usr/bin/getconf GNU_LIBC_VERSION 2>/dev/null");
+        if (rc != 0) return {};
+        const auto pos = out.find("glibc ");
+        if (pos == std::string::npos) return {};
+        std::string v = out.substr(pos + 6);
+        while (!v.empty() && (v.back() == '\n' || v.back() == '\r'
+                              || v.back() == ' '))
+            v.pop_back();
+        if (v.empty()
+            || v.find_first_not_of("0123456789.") != std::string::npos)
+            return {};
+        return v;
+#else
+        return {};
+#endif
+    }
+
+void set_tui_mode(bool enabled) {
+        tui_mode_.store(enabled, std::memory_order_relaxed);
+    }
+
+bool is_tui_mode() {
+        return tui_mode_.load(std::memory_order_relaxed);
+    }
+
+int exec(const std::string& cmd) {
+        std::string actual_cmd = cmd;
+        if (tui_mode_.load(std::memory_order_relaxed)) {
+#if defined(_WIN32)
+            actual_cmd += " >NUL 2>&1";
+#else
+            actual_cmd += " >/dev/null 2>&1";
+#endif
+        }
+        int status = std::system(actual_cmd.c_str());
+#if !defined(_WIN32)
+        if (WIFEXITED(status))
+            return WEXITSTATUS(status);
+        if (WIFSIGNALED(status))
+            return 128 + WTERMSIG(status);
+        return status;
+#else
+        return status;
+#endif
+    }
+
+std::vector<std::string> shell_command_argv(
+        std::string_view shell, std::string_view command, bool interactive) {
+        std::vector<std::string> argv{std::string(shell)};
+        if (interactive) {
+#if !defined(_WIN32)
+            argv.push_back("-i");
+#endif
+        } else if (shell.find("powershell") != std::string_view::npos
+                   || shell.find("pwsh") != std::string_view::npos) {
+            argv.insert(argv.end(), {"-NoLogo", "-NonInteractive", "-Command",
+                                     std::string(command)});
+        } else if (shell.find("cmd") != std::string_view::npos) {
+            argv.insert(argv.end(), {"/d", "/s", "/c", std::string(command)});
+        } else {
+            argv.insert(argv.end(), {"-c", std::string(command)});
+        }
+        return argv;
+    }
+
+std::vector<std::string> shell_candidates() {
+        if (const auto* configured = std::getenv("XLINGS_SHELL");
+            configured && *configured) {
+            return {std::string(configured)};
+        }
+#if defined(_WIN32)
+        return {"pwsh.exe", "powershell.exe", "cmd.exe"};
+#elif defined(__APPLE__)
+        const auto* shell = std::getenv("SHELL");
+        return {shell && *shell ? std::string(shell) : std::string("/bin/zsh"),
+                "/bin/zsh", "/bin/sh"};
+#else
+        const auto* shell = std::getenv("SHELL");
+        return {shell && *shell ? std::string(shell) : std::string("/bin/sh"),
+                "/bin/sh"};
+#endif
+    }
+
+std::string resolve_shell() { return shell_candidates().front(); }
+
+    // Replace this process with an interactive shell. POSIX only, and it does
+    // not return on success.
+    //
+    // This is not an optimisation. exec(2) hands the terminal to the shell
+    // outright: it becomes the foreground process group leader, job control
+    // and Ctrl-Z work, Ctrl-C reaches only the shell, and `exit` returns
+    // straight to the parent shell with the original environment. Running the
+    // same shell as a forked child that xlings then waits on leaves xlings in
+    // the foreground process group, so SIGINT is delivered to it as well and
+    // it can die on its default disposition while the child still owns the
+    // tty -- two readers on one terminal.
+    //
+    // Windows has no exec, so `subos use` there really does have to park on
+    // WaitForSingleObject; that is a genuine platform difference and the only
+    // reason the two families diverge here.
+#if !defined(_WIN32)
+
+int exec_replace_interactive_shell() {
+        std::cout.flush();
+        std::cerr.flush();
+        for (const auto& shell : shell_candidates()) {
+            ::execl(shell.c_str(), shell.c_str(), "-i",
+                    static_cast<char*>(nullptr));
+        }
+        return 127;  // only reached when every candidate failed to exec
+    }
+
+#endif
+
+int run_shell_command(std::string_view command, bool interactive) {
+        std::cout.flush();
+        std::cerr.flush();
+#if defined(_WIN32)
+        for (const auto& shell : shell_candidates()) {
+            auto argv = shell_command_argv(shell, command, interactive);
+            std::string commandLine;
+            if (shell.find("cmd") != std::string::npos && !interactive) {
+                // cmd.exe does not use CRT backslash escaping for the source
+                // following /c. /s deliberately strips this one outer quote
+                // pair and leaves quotes/metacharacters inside the command to
+                // cmd's own grammar.
+                commandLine = shell_quote(shell)
+                    + " /d /s /c \"" + std::string(command) + "\"";
+            } else {
+                for (const auto& arg : argv) {
+                    if (!commandLine.empty()) commandLine += ' ';
+                    commandLine += shell_quote(arg);
+                }
+            }
+            STARTUPINFOA startup{};
+            startup.cb = sizeof(startup);
+            PROCESS_INFORMATION process{};
+            if (!::CreateProcessA(nullptr, commandLine.data(), nullptr, nullptr,
+                                  TRUE, 0, nullptr, nullptr,
+                                  &startup, &process)) {
+                continue;
+            }
+            ::WaitForSingleObject(process.hProcess, INFINITE);
+            DWORD exitCode = 127;
+            ::GetExitCodeProcess(process.hProcess, &exitCode);
+            ::CloseHandle(process.hThread);
+            ::CloseHandle(process.hProcess);
+            return static_cast<int>(exitCode);
+        }
+        return 127;
+#else
+        const auto candidates = shell_candidates();
+        const auto pid = ::fork();
+        if (pid < 0) return 127;
+        if (pid == 0) {
+            for (const auto& shell : candidates) {
+                // Built through the same helper the unit test pins, so what is
+                // asserted about the argv is what the child actually execs.
+                const auto argv = shell_command_argv(shell, command, interactive);
+                std::vector<char*> raw;
+                raw.reserve(argv.size() + 1);
+                for (const auto& arg : argv) {
+                    raw.push_back(const_cast<char*>(arg.c_str()));
+                }
+                raw.push_back(nullptr);
+                ::execv(shell.c_str(), raw.data());
+            }
+            ::_exit(127);
+        }
+        int status = 0;
+        if (::waitpid(pid, &status, 0) < 0) return 127;
+        if (WIFEXITED(status)) return WEXITSTATUS(status);
+        if (WIFSIGNALED(status)) return 128 + WTERMSIG(status);
+        return 127;
+#endif
+    }
+
+int run_shell(std::string_view command, bool interactive) {
+#if !defined(_WIN32)
+        if (interactive) return exec_replace_interactive_shell();
+#endif
+        return run_shell_command(command, interactive);
+    }
+
+[[nodiscard]] std::string shell_quote(const std::string& arg) {
+#if defined(_WIN32)
+        if (!arg.empty() && arg.find_first_of(" \t\n\"") == std::string::npos)
+            return arg;
+        // MSVC CRT argv quoting: wrap in double quotes, escape \ before " and trailing \.
+        std::string result = "\"";
+        for (auto it = arg.begin(); ; ++it) {
+            std::size_t num_backslashes = 0;
+            while (it != arg.end() && *it == '\\') {
+                ++it;
+                ++num_backslashes;
+            }
+            if (it == arg.end()) {
+                result.append(num_backslashes * 2, '\\');
+                break;
+            } else if (*it == '"') {
+                result.append(num_backslashes * 2 + 1, '\\');
+                result += '"';
+            } else {
+                result.append(num_backslashes, '\\');
+                result += *it;
+            }
+        }
+        result += '"';
+        return result;
+#else
+        // POSIX sh: single-quote wrapping neutralises all special characters.
+        std::string result = "'";
+        for (char c : arg) {
+            if (c == '\'')
+                result += "'\\''";
+            else
+                result += c;
+        }
+        result += "'";
+        return result;
+#endif
+    }
+
+[[nodiscard]] std::string read_file_to_string(const std::string& filepath) {
+        std::FILE* fp = std::fopen(filepath.c_str(), "rb");
+        if (!fp) {
+            throw std::runtime_error("Failed to open file: " + filepath);
+        }
+        std::fseek(fp, 0, SEEK_END);
+        long sz = std::ftell(fp);
+        std::fseek(fp, 0, SEEK_SET);
+        std::string content(static_cast<std::size_t>(sz), '\0');
+        std::fread(content.data(), 1, content.size(), fp);
+        std::fclose(fp);
+        return content;
+    }
+
+void write_file_atomic(const std::string& filepath, const std::string& content) {
+        namespace fs = std::filesystem;
+        std::error_code ec;
+
+        // Resolve symlinks and write through to the real file. Shell rc files
+        // are commonly symlinks into a dotfiles repo; renaming over the link
+        // would replace it with a regular file and silently detach the user's
+        // dotfiles. The hop limit keeps a symlink cycle from spinning.
+        fs::path target(filepath);
+        for (int hops = 0; hops < 16; ++hops) {
+            ec.clear();
+            if (!fs::is_symlink(target, ec) || ec) break;
+            auto next = fs::read_symlink(target, ec);
+            if (ec) break;
+            target = next.is_absolute() ? next : target.parent_path() / next;
+        }
+
+        auto dir = target.parent_path();
+        if (dir.empty()) dir = fs::path(".");
+
+        auto staging = dir / ("." + target.filename().string() + ".xlings-tmp." +
+                              std::to_string(platform_impl::get_pid()));
+
+        std::FILE* fp = std::fopen(staging.string().c_str(), "wb");
+        if (!fp) {
+            throw std::runtime_error("Failed to write file: " + filepath);
+        }
+        bool ok = std::fwrite(content.data(), 1, content.size(), fp) == content.size();
+        if (ok) ok = std::fflush(fp) == 0;
+        if (ok) ok = sync_file_handle_(fp);
+        std::fclose(fp);
+        if (!ok) {
+            ec.clear();
+            fs::remove(staging, ec);
+            throw std::runtime_error("Failed to write file: " + filepath);
+        }
+
+        // Carry over the destination's mode. A fresh staging file is created
+        // under the current umask, so without this an overwrite would quietly
+        // drop an executable bit or widen the mode of the file it replaces.
+        ec.clear();
+        if (auto st = fs::status(target, ec); !ec && fs::exists(st)) {
+            std::error_code permEc;
+            fs::permissions(staging, st.permissions(),
+                            fs::perm_options::replace, permEc);
+        }
+
+        ec.clear();
+        fs::rename(staging, target, ec);
+        if (ec) {
+            std::error_code rmEc;
+            fs::remove(staging, rmEc);
+            throw std::runtime_error("Failed to write file: " + filepath);
+        }
+        sync_directory_(dir);
+    }
+
+void write_string_to_file(const std::string& filepath, const std::string& content) {
+        write_file_atomic(filepath, content);
+    }
+
+}
+
+}
diff --git a/src/platform.cppm b/src/platform.cppm
index 78bb6591..590fc58e 100644
--- a/src/platform.cppm
+++ b/src/platform.cppm
@@ -25,8 +25,6 @@ export import :unix;
 namespace xlings {
 namespace platform {
 
-    static std::string gRundir = std::filesystem::current_path().string();
-
     export using platform_impl::PATH_SEPARATOR;
     export using platform_impl::OS_NAME;
     export using platform_impl::clear_console;
@@ -82,103 +80,39 @@ namespace platform {
     // Pure parse of SUDO_UID / SUDO_GID / SUDO_USER. Does NOT check euid,
     // so it is directly unit-testable on every platform. Returns nullopt
     // unless both numeric ids are present and well-formed.
-    export [[nodiscard]] std::optional<SudoInvoker> parse_sudo_env() {
-        const char* su = std::getenv("SUDO_UID");
-        const char* sg = std::getenv("SUDO_GID");
-        if (!su || !sg || *su == '\0' || *sg == '\0') return std::nullopt;
-        char* end = nullptr;
-        unsigned long uid = std::strtoul(su, &end, 10);
-        if (end == su || *end != '\0') return std::nullopt;
-        end = nullptr;
-        unsigned long gid = std::strtoul(sg, &end, 10);
-        if (end == sg || *end != '\0') return std::nullopt;
-        const char* user = std::getenv("SUDO_USER");
-        return SudoInvoker{ static_cast<unsigned int>(uid),
-                            static_cast<unsigned int>(gid),
-                            user ? std::string{user} : std::string{} };
-    }
+    export [[nodiscard]] std::optional<SudoInvoker> parse_sudo_env();
 
     // Shell-command prefix for privileged ops (mount/umount/chown):
     // "" when already root (sudo is redundant and often absent in minimal
     // root containers), "sudo " otherwise — identical to the historical
     // hardcoded string for the non-root case.
-    export [[nodiscard]] std::string priv_prefix() {
-        return platform_impl::is_root() ? std::string{} : std::string{"sudo "};
-    }
+    export [[nodiscard]] std::string priv_prefix();
 
     // The invoking user iff launched via sudo (root EUID + SUDO_* set).
     // nullopt for pure root (no demotion target) and unprivileged runs.
-    export [[nodiscard]] std::optional<SudoInvoker> sudo_invoker() {
-        if (!platform_impl::is_root()) return std::nullopt;
-        return parse_sudo_env();
-    }
+    export [[nodiscard]] std::optional<SudoInvoker> sudo_invoker();
 
     // Home directory that user-facing files (rc lines, ~/.xlings) should
     // belong to. Under sudo this is the invoking user's home (from the
     // passwd db, falling back to /home/<user>), NOT root's $HOME — which
     // fixes the "real user never gets PATH" split-brain. Otherwise it's
     // the ordinary $HOME, unchanged.
-    export [[nodiscard]] std::string target_home() {
-        if (auto inv = sudo_invoker()) {
-            if (auto h = platform_impl::home_for_user_(inv->user); !h.empty())
-                return h;
-            if (!inv->user.empty()) return "/home/" + inv->user;
-        }
-        return platform_impl::get_home_dir();
-    }
+    export [[nodiscard]] std::string target_home();
 
     // Restore ownership of files created while running under sudo back to
     // the invoking user, so a later non-sudo run isn't locked out of its
     // own ~/.xlings. No-op unless launched via sudo (pure root / non-root
     // → returns immediately, zero filesystem traversal).
     export void chown_to_invoker(const std::filesystem::path& path,
-                                 bool recursive = true) {
-        auto inv = sudo_invoker();
-        if (!inv) return;
-        std::error_code ec;
-        if (!std::filesystem::exists(path, ec)) return;
-        platform_impl::lchown_path_(path, inv->uid, inv->gid);
-        if (recursive && std::filesystem::is_directory(path, ec)) {
-            for (auto it = std::filesystem::recursive_directory_iterator(
-                     path,
-                     std::filesystem::directory_options::skip_permission_denied,
-                     ec);
-                 !ec && it != std::default_sentinel; it.increment(ec)) {
-                platform_impl::lchown_path_(it->path(), inv->uid, inv->gid);
-            }
-        }
-    }
+                                 bool recursive = true);
 
-    export [[nodiscard]] std::string get_rundir() {
-        return gRundir;
-    }
-
-    export void set_rundir(const std::string& dir) {
-        gRundir = dir;
-    }
+    export [[nodiscard]] std::string get_rundir();
 
-    export [[nodiscard]] std::string get_system_language() {
-        try {
-            auto loc = std::locale("");
-            auto name = loc.name();
+    export void set_rundir(const std::string& dir);
 
-            if (name.empty() || name == "C" || name == "POSIX") {
-                return "en";
-            }
-
-            if (auto pos = name.find_first_of("_-.@"); pos != std::string::npos) {
-                return name.substr(0, pos);
-            }
-
-            return name;
-        } catch (const std::runtime_error&) {
-            return "en";
-        }
-    }
+    export [[nodiscard]] std::string get_system_language();
 
-    export std::pair<int, std::string> run_command_capture(const std::string& cmd) {
-        return platform_impl::run_command_capture(cmd);
-    }
+    export std::pair<int, std::string> run_command_capture(const std::string& cmd);
 
     // The host's C library version ("2.39"), probed at subos creation and
     // recorded in the subos manifest (`subos_info.host_glibc`). Rule A of the
@@ -192,109 +126,36 @@ namespace platform {
     // Empty means "unknown" -- non-glibc hosts, missing getconf, any parse
     // surprise -- and callers must treat unknown as unprovable, never as a
     // number to compare against.
-    export [[nodiscard]] std::string host_glibc_version() {
-#if defined(__linux__)
-        auto [rc, out] = run_command_capture(
-            "/usr/bin/getconf GNU_LIBC_VERSION 2>/dev/null");
-        if (rc != 0) return {};
-        const auto pos = out.find("glibc ");
-        if (pos == std::string::npos) return {};
-        std::string v = out.substr(pos + 6);
-        while (!v.empty() && (v.back() == '\n' || v.back() == '\r'
-                              || v.back() == ' '))
-            v.pop_back();
-        if (v.empty()
-            || v.find_first_not_of("0123456789.") != std::string::npos)
-            return {};
-        return v;
-#else
-        return {};
-#endif
-    }
+    export [[nodiscard]] std::string host_glibc_version();
 
     // When true, a TUI exclusively owns the terminal — suppress all stdout/stderr
     // from child processes, log output, download renderers, etc.
     inline std::atomic<bool> tui_mode_{false};
 
-    export void set_tui_mode(bool enabled) {
-        tui_mode_.store(enabled, std::memory_order_relaxed);
-    }
+    export void set_tui_mode(bool enabled);
 
-    export bool is_tui_mode() {
-        return tui_mode_.load(std::memory_order_relaxed);
-    }
+    export bool is_tui_mode();
 
-    export int exec(const std::string& cmd) {
-        std::string actual_cmd = cmd;
-        if (tui_mode_.load(std::memory_order_relaxed)) {
-#if defined(_WIN32)
-            actual_cmd += " >NUL 2>&1";
-#else
-            actual_cmd += " >/dev/null 2>&1";
-#endif
-        }
-        int status = std::system(actual_cmd.c_str());
-#if !defined(_WIN32)
-        if (WIFEXITED(status))
-            return WEXITSTATUS(status);
-        if (WIFSIGNALED(status))
-            return 128 + WTERMSIG(status);
-        return status;
-#else
-        return status;
-#endif
-    }
+    export int exec(const std::string& cmd);
 
     export [[nodiscard]] std::string shell_quote(const std::string& arg);
 
     export std::vector<std::string> shell_command_argv(
-        std::string_view shell, std::string_view command, bool interactive) {
-        std::vector<std::string> argv{std::string(shell)};
-        if (interactive) {
-#if !defined(_WIN32)
-            argv.push_back("-i");
-#endif
-        } else if (shell.find("powershell") != std::string_view::npos
-                   || shell.find("pwsh") != std::string_view::npos) {
-            argv.insert(argv.end(), {"-NoLogo", "-NonInteractive", "-Command",
-                                     std::string(command)});
-        } else if (shell.find("cmd") != std::string_view::npos) {
-            argv.insert(argv.end(), {"/d", "/s", "/c", std::string(command)});
-        } else {
-            argv.insert(argv.end(), {"-c", std::string(command)});
-        }
-        return argv;
-    }
+        std::string_view shell, std::string_view command, bool interactive);
 
     // The shells to try, most preferred first. One priority chain for both
     // families: `XLINGS_SHELL` wins everywhere, then the platform's own
     // notion of the user's shell, then a guaranteed fallback. Windows used to
     // honour `XLINGS_SHELL` while POSIX read only `SHELL`, which is the kind
     // of split a caller cannot see and cannot work around.
-    export std::vector<std::string> shell_candidates() {
-        if (const auto* configured = std::getenv("XLINGS_SHELL");
-            configured && *configured) {
-            return {std::string(configured)};
-        }
-#if defined(_WIN32)
-        return {"pwsh.exe", "powershell.exe", "cmd.exe"};
-#elif defined(__APPLE__)
-        const auto* shell = std::getenv("SHELL");
-        return {shell && *shell ? std::string(shell) : std::string("/bin/zsh"),
-                "/bin/zsh", "/bin/sh"};
-#else
-        const auto* shell = std::getenv("SHELL");
-        return {shell && *shell ? std::string(shell) : std::string("/bin/sh"),
-                "/bin/sh"};
-#endif
-    }
+    export std::vector<std::string> shell_candidates();
 
     // The shell a caller should name when it reports what it is about to run.
     // Resolving it here rather than at each call site is what keeps an event
     // payload and the process that actually starts from naming different
     // shells -- the macOS sandbox reported `/bin/zsh` while `run_shell` went
     // on to re-read the environment and exec `/bin/sh`.
-    export std::string resolve_shell() { return shell_candidates().front(); }
+    export std::string resolve_shell();
 
     // Replace this process with an interactive shell. POSIX only, and it does
     // not return on success.
@@ -312,144 +173,21 @@ namespace platform {
     // WaitForSingleObject; that is a genuine platform difference and the only
     // reason the two families diverge here.
 #if !defined(_WIN32)
-    export int exec_replace_interactive_shell() {
-        std::cout.flush();
-        std::cerr.flush();
-        for (const auto& shell : shell_candidates()) {
-            ::execl(shell.c_str(), shell.c_str(), "-i",
-                    static_cast<char*>(nullptr));
-        }
-        return 127;  // only reached when every candidate failed to exec
-    }
+    export int exec_replace_interactive_shell();
 #endif
 
     // Run one command through a shell and return its exit code. Used for
     // `--cmd` on every platform, and for interactive entry on Windows.
-    export int run_shell_command(std::string_view command, bool interactive) {
-        std::cout.flush();
-        std::cerr.flush();
-#if defined(_WIN32)
-        for (const auto& shell : shell_candidates()) {
-            auto argv = shell_command_argv(shell, command, interactive);
-            std::string commandLine;
-            if (shell.find("cmd") != std::string::npos && !interactive) {
-                // cmd.exe does not use CRT backslash escaping for the source
-                // following /c. /s deliberately strips this one outer quote
-                // pair and leaves quotes/metacharacters inside the command to
-                // cmd's own grammar.
-                commandLine = shell_quote(shell)
-                    + " /d /s /c \"" + std::string(command) + "\"";
-            } else {
-                for (const auto& arg : argv) {
-                    if (!commandLine.empty()) commandLine += ' ';
-                    commandLine += shell_quote(arg);
-                }
-            }
-            STARTUPINFOA startup{};
-            startup.cb = sizeof(startup);
-            PROCESS_INFORMATION process{};
-            if (!::CreateProcessA(nullptr, commandLine.data(), nullptr, nullptr,
-                                  TRUE, 0, nullptr, nullptr,
-                                  &startup, &process)) {
-                continue;
-            }
-            ::WaitForSingleObject(process.hProcess, INFINITE);
-            DWORD exitCode = 127;
-            ::GetExitCodeProcess(process.hProcess, &exitCode);
-            ::CloseHandle(process.hThread);
-            ::CloseHandle(process.hProcess);
-            return static_cast<int>(exitCode);
-        }
-        return 127;
-#else
-        const auto candidates = shell_candidates();
-        const auto pid = ::fork();
-        if (pid < 0) return 127;
-        if (pid == 0) {
-            for (const auto& shell : candidates) {
-                // Built through the same helper the unit test pins, so what is
-                // asserted about the argv is what the child actually execs.
-                const auto argv = shell_command_argv(shell, command, interactive);
-                std::vector<char*> raw;
-                raw.reserve(argv.size() + 1);
-                for (const auto& arg : argv) {
-                    raw.push_back(const_cast<char*>(arg.c_str()));
-                }
-                raw.push_back(nullptr);
-                ::execv(shell.c_str(), raw.data());
-            }
-            ::_exit(127);
-        }
-        int status = 0;
-        if (::waitpid(pid, &status, 0) < 0) return 127;
-        if (WIFEXITED(status)) return WEXITSTATUS(status);
-        if (WIFSIGNALED(status)) return 128 + WTERMSIG(status);
-        return 127;
-#endif
-    }
+    export int run_shell_command(std::string_view command, bool interactive);
 
     // Entry point for `subos use`: interactive entry replaces this process on
     // POSIX, everything else spawns and waits.
-    export int run_shell(std::string_view command, bool interactive) {
-#if !defined(_WIN32)
-        if (interactive) return exec_replace_interactive_shell();
-#endif
-        return run_shell_command(command, interactive);
-    }
+    export int run_shell(std::string_view command, bool interactive);
 
     // Escape a single argument for safe embedding in a shell command string.
-    export [[nodiscard]] std::string shell_quote(const std::string& arg) {
-#if defined(_WIN32)
-        if (!arg.empty() && arg.find_first_of(" \t\n\"") == std::string::npos)
-            return arg;
-        // MSVC CRT argv quoting: wrap in double quotes, escape \ before " and trailing \.
-        std::string result = "\"";
-        for (auto it = arg.begin(); ; ++it) {
-            std::size_t num_backslashes = 0;
-            while (it != arg.end() && *it == '\\') {
-                ++it;
-                ++num_backslashes;
-            }
-            if (it == arg.end()) {
-                result.append(num_backslashes * 2, '\\');
-                break;
-            } else if (*it == '"') {
-                result.append(num_backslashes * 2 + 1, '\\');
-                result += '"';
-            } else {
-                result.append(num_backslashes, '\\');
-                result += *it;
-            }
-        }
-        result += '"';
-        return result;
-#else
-        // POSIX sh: single-quote wrapping neutralises all special characters.
-        std::string result = "'";
-        for (char c : arg) {
-            if (c == '\'')
-                result += "'\\''";
-            else
-                result += c;
-        }
-        result += "'";
-        return result;
-#endif
-    }
+    export [[nodiscard]] std::string shell_quote(const std::string& arg);
 
-    export [[nodiscard]] std::string read_file_to_string(const std::string& filepath) {
-        std::FILE* fp = std::fopen(filepath.c_str(), "rb");
-        if (!fp) {
-            throw std::runtime_error("Failed to open file: " + filepath);
-        }
-        std::fseek(fp, 0, SEEK_END);
-        long sz = std::ftell(fp);
-        std::fseek(fp, 0, SEEK_SET);
-        std::string content(static_cast<std::size_t>(sz), '\0');
-        std::fread(content.data(), 1, content.size(), fp);
-        std::fclose(fp);
-        return content;
-    }
+    export [[nodiscard]] std::string read_file_to_string(const std::string& filepath);
 
     // ── Atomic state-file replace ────────────────────────────────────
     //
@@ -491,66 +229,9 @@ namespace platform {
 #endif
     }
 
-    export void write_file_atomic(const std::string& filepath, const std::string& content) {
-        namespace fs = std::filesystem;
-        std::error_code ec;
-
-        // Resolve symlinks and write through to the real file. Shell rc files
-        // are commonly symlinks into a dotfiles repo; renaming over the link
-        // would replace it with a regular file and silently detach the user's
-        // dotfiles. The hop limit keeps a symlink cycle from spinning.
-        fs::path target(filepath);
-        for (int hops = 0; hops < 16; ++hops) {
-            ec.clear();
-            if (!fs::is_symlink(target, ec) || ec) break;
-            auto next = fs::read_symlink(target, ec);
-            if (ec) break;
-            target = next.is_absolute() ? next : target.parent_path() / next;
-        }
-
-        auto dir = target.parent_path();
-        if (dir.empty()) dir = fs::path(".");
-
-        auto staging = dir / ("." + target.filename().string() + ".xlings-tmp." +
-                              std::to_string(platform_impl::get_pid()));
-
-        std::FILE* fp = std::fopen(staging.string().c_str(), "wb");
-        if (!fp) {
-            throw std::runtime_error("Failed to write file: " + filepath);
-        }
-        bool ok = std::fwrite(content.data(), 1, content.size(), fp) == content.size();
-        if (ok) ok = std::fflush(fp) == 0;
-        if (ok) ok = sync_file_handle_(fp);
-        std::fclose(fp);
-        if (!ok) {
-            ec.clear();
-            fs::remove(staging, ec);
-            throw std::runtime_error("Failed to write file: " + filepath);
-        }
-
-        // Carry over the destination's mode. A fresh staging file is created
-        // under the current umask, so without this an overwrite would quietly
-        // drop an executable bit or widen the mode of the file it replaces.
-        ec.clear();
-        if (auto st = fs::status(target, ec); !ec && fs::exists(st)) {
-            std::error_code permEc;
-            fs::permissions(staging, st.permissions(),
-                            fs::perm_options::replace, permEc);
-        }
-
-        ec.clear();
-        fs::rename(staging, target, ec);
-        if (ec) {
-            std::error_code rmEc;
-            fs::remove(staging, rmEc);
-            throw std::runtime_error("Failed to write file: " + filepath);
-        }
-        sync_directory_(dir);
-    }
+    export void write_file_atomic(const std::string& filepath, const std::string& content);
 
-    export void write_string_to_file(const std::string& filepath, const std::string& content) {
-        write_file_atomic(filepath, content);
-    }
+    export void write_string_to_file(const std::string& filepath, const std::string& content);
 
     // Wrap directory_iterator for range-for compatibility across compilers.
     // Clang/libc++ 20 only provides operator==(default_sentinel_t) on directory_iterator,
diff --git a/src/platform/linux.cpp b/src/platform/linux.cpp
new file mode 100644
index 00000000..f6bb4714
--- /dev/null
+++ b/src/platform/linux.cpp
@@ -0,0 +1,216 @@
+module;
+
+#include <cstdio>
+#include <cstdlib>
+#if defined(__linux__)
+#include <unistd.h>
+#include <sys/stat.h>
+#include <sys/wait.h>
+#include <signal.h>
+#include <fcntl.h>
+#endif
+
+module xlings.platform;
+
+import std;
+import xlings.runtime.cancellation;
+
+#if defined(__linux__)
+
+namespace xlings {
+
+namespace platform_impl {
+
+std::filesystem::path get_executable_path() {
+        char buf[4096];
+        ssize_t n = ::readlink("/proc/self/exe", buf, sizeof(buf) - 1);
+        if (n == -1) return {};
+        buf[n] = '\0';
+        return std::filesystem::path(buf);
+    }
+
+std::pair<int, std::string> run_command_capture(const std::string& cmd) {
+        std::string full = cmd + " 2>&1";
+        FILE* pipe = ::popen(full.c_str(), "r");
+        if (!pipe) {
+            return {-1, std::string{}};
+        }
+        std::string output;
+        std::array<char, 256> buffer{};
+        while (fgets(buffer.data(), buffer.size(), pipe) != nullptr) {
+            output += buffer.data();
+        }
+        int status = ::pclose(pipe);
+        return {status, output};
+    }
+
+auto spawn_command(const std::string& cmd) -> ProcessHandle {
+        int pipefd[2];
+        if (::pipe(pipefd) == -1) return {-1, -1};
+
+        pid_t pid = ::fork();
+        if (pid == -1) {
+            ::close(pipefd[0]);
+            ::close(pipefd[1]);
+            return {-1, -1};
+        }
+
+        if (pid == 0) {
+            // Child: new process group so we can kill the whole group
+            ::setpgid(0, 0);
+            ::close(pipefd[0]);
+            ::dup2(pipefd[1], STDOUT_FILENO);
+            ::dup2(pipefd[1], STDERR_FILENO);
+            ::close(pipefd[1]);
+            ::execl("/bin/sh", "sh", "-c", cmd.c_str(), nullptr);
+            ::_exit(127);
+        }
+
+        // Parent
+        ::close(pipefd[1]);
+        // Set read end to non-blocking
+        int flags = ::fcntl(pipefd[0], F_GETFL, 0);
+        if (flags != -1) ::fcntl(pipefd[0], F_SETFL, flags | O_NONBLOCK);
+
+        return {static_cast<int>(pid), pipefd[0]};
+    }
+
+auto wait_or_kill(const ProcessHandle& h,
+                             CancellationToken* cancel,
+                             std::chrono::milliseconds timeout) -> std::pair<int, std::string> {
+        if (h.pid <= 0) return {-1, ""};
+
+        std::string output;
+        std::array<char, 4096> buf{};
+        auto deadline = std::chrono::steady_clock::now() + timeout;
+
+        while (true) {
+            // Read any available output (non-blocking)
+            while (true) {
+                ssize_t n = ::read(h.pipe_fd, buf.data(), buf.size());
+                if (n > 0) {
+                    output.append(buf.data(), static_cast<std::size_t>(n));
+                } else {
+                    break;
+                }
+            }
+
+            // Check if child exited
+            int status = 0;
+            pid_t result = ::waitpid(h.pid, &status, WNOHANG);
+            if (result == h.pid) {
+                // Read remaining output
+                while (true) {
+                    ssize_t n = ::read(h.pipe_fd, buf.data(), buf.size());
+                    if (n > 0) output.append(buf.data(), static_cast<std::size_t>(n));
+                    else break;
+                }
+                ::close(h.pipe_fd);
+                int code = WIFEXITED(status) ? WEXITSTATUS(status) : -1;
+                return {code, output};
+            }
+
+            // Check cancellation
+            if (cancel && cancel->is_cancelled()) {
+                break;
+            }
+
+            // Check timeout
+            if (std::chrono::steady_clock::now() >= deadline) {
+                break;
+            }
+
+            // Sleep briefly before next poll
+            std::this_thread::sleep_for(std::chrono::milliseconds{100});
+        }
+
+        // Kill the process group: SIGTERM first
+        ::kill(-h.pid, SIGTERM);
+
+        // Grace period: 2 seconds
+        auto kill_deadline = std::chrono::steady_clock::now() + std::chrono::seconds{2};
+        while (std::chrono::steady_clock::now() < kill_deadline) {
+            int status = 0;
+            pid_t result = ::waitpid(h.pid, &status, WNOHANG);
+            if (result == h.pid) {
+                ::close(h.pipe_fd);
+                return {-1, output};
+            }
+            std::this_thread::sleep_for(std::chrono::milliseconds{100});
+        }
+
+        // Force kill
+        ::kill(-h.pid, SIGKILL);
+        int status = 0;
+        ::waitpid(h.pid, &status, 0);
+        ::close(h.pipe_fd);
+        return {-1, output};
+    }
+
+void clear_console() {
+        std::system("clear");
+    }
+
+std::string get_home_dir() {
+        if (const char* home = std::getenv("HOME")) return home;
+        return ".";
+    }
+
+void set_env_variable(const std::string& key, const std::string& value) {
+        ::setenv(key.c_str(), value.c_str(), 1);
+    }
+
+void make_files_executable(const std::filesystem::path& dir) {
+        if (!std::filesystem::exists(dir)) return;
+        for (auto it = std::filesystem::directory_iterator(dir); it != std::default_sentinel; ++it) {
+            if (it->is_regular_file())
+                ::chmod(it->path().c_str(), 0755);
+        }
+    }
+
+bool create_directory_link(const std::filesystem::path& link,
+                                      const std::filesystem::path& target) {
+        std::error_code ec;
+        if (std::filesystem::is_symlink(link)) {
+            std::filesystem::remove(link, ec);
+        } else if (std::filesystem::exists(link)) {
+            std::filesystem::remove_all(link, ec);
+        }
+        auto linkTarget = target;
+        auto rel = std::filesystem::relative(target, link.parent_path(), ec);
+        if (!ec && !rel.empty()) linkTarget = rel;
+        ec.clear();
+        std::filesystem::create_directory_symlink(linkTarget, link, ec);
+        return !static_cast<bool>(ec);
+    }
+
+void init_console_output() {}
+
+bool supports_rewrite_output() {
+        return ::isatty(STDOUT_FILENO) != 0;
+    }
+
+bool stderr_is_terminal() {
+        return ::isatty(STDERR_FILENO) != 0;
+    }
+
+bool stdin_is_terminal() {
+        return ::isatty(STDIN_FILENO) != 0;
+    }
+
+int get_pid() {
+        return static_cast<int>(::getpid());
+    }
+
+bool is_process_alive(int pid) {
+        if (pid <= 0) return false;
+        // Check /proc/<pid> existence
+        auto proc_path = std::filesystem::path("/proc") / std::to_string(pid);
+        return std::filesystem::exists(proc_path);
+    }
+
+}
+
+}
+
+#endif // defined(__linux__)
diff --git a/src/platform/linux.cppm b/src/platform/linux.cppm
index 4b361b98..18179897 100644
--- a/src/platform/linux.cppm
+++ b/src/platform/linux.cppm
@@ -23,28 +23,9 @@ namespace platform_impl {
     export constexpr char PATH_SEPARATOR = ':';
     export constexpr std::string_view OS_NAME = "linux";
 
-    export std::filesystem::path get_executable_path() {
-        char buf[4096];
-        ssize_t n = ::readlink("/proc/self/exe", buf, sizeof(buf) - 1);
-        if (n == -1) return {};
-        buf[n] = '\0';
-        return std::filesystem::path(buf);
-    }
+    export std::filesystem::path get_executable_path();
 
-    export std::pair<int, std::string> run_command_capture(const std::string& cmd) {
-        std::string full = cmd + " 2>&1";
-        FILE* pipe = ::popen(full.c_str(), "r");
-        if (!pipe) {
-            return {-1, std::string{}};
-        }
-        std::string output;
-        std::array<char, 256> buffer{};
-        while (fgets(buffer.data(), buffer.size(), pipe) != nullptr) {
-            output += buffer.data();
-        }
-        int status = ::pclose(pipe);
-        return {status, output};
-    }
+    export std::pair<int, std::string> run_command_capture(const std::string& cmd);
 
     // ─── Cancellable process management ───
 
@@ -53,166 +34,37 @@ namespace platform_impl {
         int pipe_fd{-1};
     };
 
-    export auto spawn_command(const std::string& cmd) -> ProcessHandle {
-        int pipefd[2];
-        if (::pipe(pipefd) == -1) return {-1, -1};
-
-        pid_t pid = ::fork();
-        if (pid == -1) {
-            ::close(pipefd[0]);
-            ::close(pipefd[1]);
-            return {-1, -1};
-        }
-
-        if (pid == 0) {
-            // Child: new process group so we can kill the whole group
-            ::setpgid(0, 0);
-            ::close(pipefd[0]);
-            ::dup2(pipefd[1], STDOUT_FILENO);
-            ::dup2(pipefd[1], STDERR_FILENO);
-            ::close(pipefd[1]);
-            ::execl("/bin/sh", "sh", "-c", cmd.c_str(), nullptr);
-            ::_exit(127);
-        }
-
-        // Parent
-        ::close(pipefd[1]);
-        // Set read end to non-blocking
-        int flags = ::fcntl(pipefd[0], F_GETFL, 0);
-        if (flags != -1) ::fcntl(pipefd[0], F_SETFL, flags | O_NONBLOCK);
-
-        return {static_cast<int>(pid), pipefd[0]};
-    }
+    export auto spawn_command(const std::string& cmd) -> ProcessHandle;
 
     export auto wait_or_kill(const ProcessHandle& h,
                              CancellationToken* cancel,
-                             std::chrono::milliseconds timeout) -> std::pair<int, std::string> {
-        if (h.pid <= 0) return {-1, ""};
-
-        std::string output;
-        std::array<char, 4096> buf{};
-        auto deadline = std::chrono::steady_clock::now() + timeout;
-
-        while (true) {
-            // Read any available output (non-blocking)
-            while (true) {
-                ssize_t n = ::read(h.pipe_fd, buf.data(), buf.size());
-                if (n > 0) {
-                    output.append(buf.data(), static_cast<std::size_t>(n));
-                } else {
-                    break;
-                }
-            }
-
-            // Check if child exited
-            int status = 0;
-            pid_t result = ::waitpid(h.pid, &status, WNOHANG);
-            if (result == h.pid) {
-                // Read remaining output
-                while (true) {
-                    ssize_t n = ::read(h.pipe_fd, buf.data(), buf.size());
-                    if (n > 0) output.append(buf.data(), static_cast<std::size_t>(n));
-                    else break;
-                }
-                ::close(h.pipe_fd);
-                int code = WIFEXITED(status) ? WEXITSTATUS(status) : -1;
-                return {code, output};
-            }
-
-            // Check cancellation
-            if (cancel && cancel->is_cancelled()) {
-                break;
-            }
-
-            // Check timeout
-            if (std::chrono::steady_clock::now() >= deadline) {
-                break;
-            }
-
-            // Sleep briefly before next poll
-            std::this_thread::sleep_for(std::chrono::milliseconds{100});
-        }
-
-        // Kill the process group: SIGTERM first
-        ::kill(-h.pid, SIGTERM);
-
-        // Grace period: 2 seconds
-        auto kill_deadline = std::chrono::steady_clock::now() + std::chrono::seconds{2};
-        while (std::chrono::steady_clock::now() < kill_deadline) {
-            int status = 0;
-            pid_t result = ::waitpid(h.pid, &status, WNOHANG);
-            if (result == h.pid) {
-                ::close(h.pipe_fd);
-                return {-1, output};
-            }
-            std::this_thread::sleep_for(std::chrono::milliseconds{100});
-        }
-
-        // Force kill
-        ::kill(-h.pid, SIGKILL);
-        int status = 0;
-        ::waitpid(h.pid, &status, 0);
-        ::close(h.pipe_fd);
-        return {-1, output};
-    }
+                             std::chrono::milliseconds timeout) -> std::pair<int, std::string>;
 
-    export void clear_console() {
-        std::system("clear");
-    }
+    export void clear_console();
 
-    export std::string get_home_dir() {
-        if (const char* home = std::getenv("HOME")) return home;
-        return ".";
-    }
+    export std::string get_home_dir();
 
-    export void set_env_variable(const std::string& key, const std::string& value) {
-        ::setenv(key.c_str(), value.c_str(), 1);
-    }
+    export void set_env_variable(const std::string& key, const std::string& value);
 
-    export void make_files_executable(const std::filesystem::path& dir) {
-        if (!std::filesystem::exists(dir)) return;
-        for (auto it = std::filesystem::directory_iterator(dir); it != std::default_sentinel; ++it) {
-            if (it->is_regular_file())
-                ::chmod(it->path().c_str(), 0755);
-        }
-    }
+    export void make_files_executable(const std::filesystem::path& dir);
 
     export bool create_directory_link(const std::filesystem::path& link,
-                                      const std::filesystem::path& target) {
-        std::error_code ec;
-        if (std::filesystem::is_symlink(link)) {
-            std::filesystem::remove(link, ec);
-        } else if (std::filesystem::exists(link)) {
-            std::filesystem::remove_all(link, ec);
-        }
-        auto linkTarget = target;
-        auto rel = std::filesystem::relative(target, link.parent_path(), ec);
-        if (!ec && !rel.empty()) linkTarget = rel;
-        ec.clear();
-        std::filesystem::create_directory_symlink(linkTarget, link, ec);
-        return !static_cast<bool>(ec);
-    }
+                                      const std::filesystem::path& target);
 
     // No-op on Linux — terminal generally supports ANSI natively.
-    export void init_console_output() {}
+    export void init_console_output();
 
     // Check if stdout is a TTY (supports cursor save/restore).
-    export bool supports_rewrite_output() {
-        return ::isatty(STDOUT_FILENO) != 0;
-    }
+    export bool supports_rewrite_output();
 
     // Check if stderr is a TTY. Separate from stdout because warnings and
     // errors go to stderr: `xlings install > log` still has an interactive
     // stderr, and `2>&1 | cat` has neither.
-    export bool stderr_is_terminal() {
-        return ::isatty(STDERR_FILENO) != 0;
-    }
+    export bool stderr_is_terminal();
 
     // Check if stdin is a TTY — i.e. whether there is someone there to answer
     // an interactive prompt.
-    export bool stdin_is_terminal() {
-        return ::isatty(STDIN_FILENO) != 0;
-    }
+    export bool stdin_is_terminal();
 
     export template<typename... Args>
     void println(std::format_string<Args...> fmt, Args&&... args) {
@@ -220,19 +72,12 @@ namespace platform_impl {
     }
 
     export inline void println(const std::string& msg) {
-        std::println("{}", msg);
+        std::println(stdout, "{}", msg);
     }
 
-    export int get_pid() {
-        return static_cast<int>(::getpid());
-    }
+    export int get_pid();
 
-    export bool is_process_alive(int pid) {
-        if (pid <= 0) return false;
-        // Check /proc/<pid> existence
-        auto proc_path = std::filesystem::path("/proc") / std::to_string(pid);
-        return std::filesystem::exists(proc_path);
-    }
+    export bool is_process_alive(int pid);
 
     // query_terminal_is_light() lives in :unix — shared with macOS.
 
diff --git a/src/platform/macos.cpp b/src/platform/macos.cpp
new file mode 100644
index 00000000..e9a89a58
--- /dev/null
+++ b/src/platform/macos.cpp
@@ -0,0 +1,195 @@
+module;
+
+#include <cstdio>
+#include <cstdlib>
+#if defined(__APPLE__)
+#include <mach-o/dyld.h>
+#include <stdlib.h>
+#include <sys/stat.h>
+#include <sys/wait.h>
+#include <unistd.h>
+#include <signal.h>
+#include <fcntl.h>
+#endif
+
+module xlings.platform;
+
+import std;
+import xlings.runtime.cancellation;
+
+#if defined(__APPLE__)
+
+namespace xlings {
+
+namespace platform_impl {
+
+std::filesystem::path get_executable_path() {
+        char buf[4096];
+        uint32_t size = sizeof(buf);
+        if (::_NSGetExecutablePath(buf, &size) != 0) return {};
+        char real[4096];
+        if (::realpath(buf, real) == nullptr) return std::filesystem::path(buf);
+        return std::filesystem::path(real);
+    }
+
+std::pair<int, std::string> run_command_capture(const std::string& cmd) {
+        std::string full = cmd + " 2>&1";
+        FILE* pipe = ::popen(full.c_str(), "r");
+        if (!pipe) {
+            return {-1, std::string{}};
+        }
+        std::string output;
+        std::array<char, 256> buffer{};
+        while (fgets(buffer.data(), buffer.size(), pipe) != nullptr) {
+            output += buffer.data();
+        }
+        int status = ::pclose(pipe);
+        return {status, output};
+    }
+
+auto spawn_command(const std::string& cmd) -> ProcessHandle {
+        int pipefd[2];
+        if (::pipe(pipefd) == -1) return {-1, -1};
+
+        pid_t pid = ::fork();
+        if (pid == -1) {
+            ::close(pipefd[0]);
+            ::close(pipefd[1]);
+            return {-1, -1};
+        }
+
+        if (pid == 0) {
+            ::setpgid(0, 0);
+            ::close(pipefd[0]);
+            ::dup2(pipefd[1], STDOUT_FILENO);
+            ::dup2(pipefd[1], STDERR_FILENO);
+            ::close(pipefd[1]);
+            ::execl("/bin/sh", "sh", "-c", cmd.c_str(), nullptr);
+            ::_exit(127);
+        }
+
+        ::close(pipefd[1]);
+        int flags = ::fcntl(pipefd[0], F_GETFL, 0);
+        if (flags != -1) ::fcntl(pipefd[0], F_SETFL, flags | O_NONBLOCK);
+
+        return {static_cast<int>(pid), pipefd[0]};
+    }
+
+auto wait_or_kill(const ProcessHandle& h,
+                             CancellationToken* cancel,
+                             std::chrono::milliseconds timeout) -> std::pair<int, std::string> {
+        if (h.pid <= 0) return {-1, ""};
+
+        std::string output;
+        std::array<char, 4096> buf{};
+        auto deadline = std::chrono::steady_clock::now() + timeout;
+
+        while (true) {
+            while (true) {
+                ssize_t n = ::read(h.pipe_fd, buf.data(), buf.size());
+                if (n > 0) output.append(buf.data(), static_cast<std::size_t>(n));
+                else break;
+            }
+
+            int status = 0;
+            pid_t result = ::waitpid(h.pid, &status, WNOHANG);
+            if (result == h.pid) {
+                while (true) {
+                    ssize_t n = ::read(h.pipe_fd, buf.data(), buf.size());
+                    if (n > 0) output.append(buf.data(), static_cast<std::size_t>(n));
+                    else break;
+                }
+                ::close(h.pipe_fd);
+                int code = WIFEXITED(status) ? WEXITSTATUS(status) : -1;
+                return {code, output};
+            }
+
+            if (cancel && cancel->is_cancelled()) break;
+            if (std::chrono::steady_clock::now() >= deadline) break;
+
+            std::this_thread::sleep_for(std::chrono::milliseconds{100});
+        }
+
+        ::kill(-h.pid, SIGTERM);
+        auto kill_deadline = std::chrono::steady_clock::now() + std::chrono::seconds{2};
+        while (std::chrono::steady_clock::now() < kill_deadline) {
+            int status = 0;
+            pid_t result = ::waitpid(h.pid, &status, WNOHANG);
+            if (result == h.pid) { ::close(h.pipe_fd); return {-1, output}; }
+            std::this_thread::sleep_for(std::chrono::milliseconds{100});
+        }
+        ::kill(-h.pid, SIGKILL);
+        int status = 0;
+        ::waitpid(h.pid, &status, 0);
+        ::close(h.pipe_fd);
+        return {-1, output};
+    }
+
+void clear_console() {
+        std::system("clear");
+    }
+
+std::string get_home_dir() {
+        if (const char* home = std::getenv("HOME")) return home;
+        return ".";
+    }
+
+void set_env_variable(const std::string& key, const std::string& value) {
+        ::setenv(key.c_str(), value.c_str(), 1);
+    }
+
+void make_files_executable(const std::filesystem::path& dir) {
+        if (!std::filesystem::exists(dir)) return;
+        for (auto it = std::filesystem::directory_iterator(dir); it != std::default_sentinel; ++it) {
+            if (it->is_regular_file())
+                ::chmod(it->path().c_str(), 0755);
+        }
+        std::string cmd = "xattr -cr \"" + dir.string() + "\" 2>/dev/null";
+        std::system(cmd.c_str());
+    }
+
+bool create_directory_link(const std::filesystem::path& link,
+                                      const std::filesystem::path& target) {
+        std::error_code ec;
+        if (std::filesystem::is_symlink(link)) {
+            std::filesystem::remove(link, ec);
+        } else if (std::filesystem::exists(link)) {
+            std::filesystem::remove_all(link, ec);
+        }
+        auto linkTarget = target;
+        auto rel = std::filesystem::relative(target, link.parent_path(), ec);
+        if (!ec && !rel.empty()) linkTarget = rel;
+        ec.clear();
+        std::filesystem::create_directory_symlink(linkTarget, link, ec);
+        return !static_cast<bool>(ec);
+    }
+
+void init_console_output() {}
+
+bool supports_rewrite_output() {
+        return ::isatty(STDOUT_FILENO) != 0;
+    }
+
+bool stderr_is_terminal() {
+        return ::isatty(STDERR_FILENO) != 0;
+    }
+
+bool stdin_is_terminal() {
+        return ::isatty(STDIN_FILENO) != 0;
+    }
+
+int get_pid() {
+        return static_cast<int>(::getpid());
+    }
+
+bool is_process_alive(int pid) {
+        if (pid <= 0) return false;
+        // kill(pid, 0) checks process existence without sending a signal
+        return ::kill(pid, 0) == 0;
+    }
+
+}
+
+}
+
+#endif // defined(__APPLE__)
diff --git a/src/platform/macos.cppm b/src/platform/macos.cppm
index 70802cb0..0207b44e 100644
--- a/src/platform/macos.cppm
+++ b/src/platform/macos.cppm
@@ -25,29 +25,9 @@ namespace platform_impl {
     export constexpr char PATH_SEPARATOR = ':';
     export constexpr std::string_view OS_NAME = "macosx";
 
-    export std::filesystem::path get_executable_path() {
-        char buf[4096];
-        uint32_t size = sizeof(buf);
-        if (::_NSGetExecutablePath(buf, &size) != 0) return {};
-        char real[4096];
-        if (::realpath(buf, real) == nullptr) return std::filesystem::path(buf);
-        return std::filesystem::path(real);
-    }
+    export std::filesystem::path get_executable_path();
 
-    export std::pair<int, std::string> run_command_capture(const std::string& cmd) {
-        std::string full = cmd + " 2>&1";
-        FILE* pipe = ::popen(full.c_str(), "r");
-        if (!pipe) {
-            return {-1, std::string{}};
-        }
-        std::string output;
-        std::array<char, 256> buffer{};
-        while (fgets(buffer.data(), buffer.size(), pipe) != nullptr) {
-            output += buffer.data();
-        }
-        int status = ::pclose(pipe);
-        return {status, output};
-    }
+    export std::pair<int, std::string> run_command_capture(const std::string& cmd);
 
     // ─── Cancellable process management ───
 
@@ -56,143 +36,37 @@ namespace platform_impl {
         int pipe_fd{-1};
     };
 
-    export auto spawn_command(const std::string& cmd) -> ProcessHandle {
-        int pipefd[2];
-        if (::pipe(pipefd) == -1) return {-1, -1};
-
-        pid_t pid = ::fork();
-        if (pid == -1) {
-            ::close(pipefd[0]);
-            ::close(pipefd[1]);
-            return {-1, -1};
-        }
-
-        if (pid == 0) {
-            ::setpgid(0, 0);
-            ::close(pipefd[0]);
-            ::dup2(pipefd[1], STDOUT_FILENO);
-            ::dup2(pipefd[1], STDERR_FILENO);
-            ::close(pipefd[1]);
-            ::execl("/bin/sh", "sh", "-c", cmd.c_str(), nullptr);
-            ::_exit(127);
-        }
-
-        ::close(pipefd[1]);
-        int flags = ::fcntl(pipefd[0], F_GETFL, 0);
-        if (flags != -1) ::fcntl(pipefd[0], F_SETFL, flags | O_NONBLOCK);
-
-        return {static_cast<int>(pid), pipefd[0]};
-    }
+    export auto spawn_command(const std::string& cmd) -> ProcessHandle;
 
     export auto wait_or_kill(const ProcessHandle& h,
                              CancellationToken* cancel,
-                             std::chrono::milliseconds timeout) -> std::pair<int, std::string> {
-        if (h.pid <= 0) return {-1, ""};
-
-        std::string output;
-        std::array<char, 4096> buf{};
-        auto deadline = std::chrono::steady_clock::now() + timeout;
-
-        while (true) {
-            while (true) {
-                ssize_t n = ::read(h.pipe_fd, buf.data(), buf.size());
-                if (n > 0) output.append(buf.data(), static_cast<std::size_t>(n));
-                else break;
-            }
-
-            int status = 0;
-            pid_t result = ::waitpid(h.pid, &status, WNOHANG);
-            if (result == h.pid) {
-                while (true) {
-                    ssize_t n = ::read(h.pipe_fd, buf.data(), buf.size());
-                    if (n > 0) output.append(buf.data(), static_cast<std::size_t>(n));
-                    else break;
-                }
-                ::close(h.pipe_fd);
-                int code = WIFEXITED(status) ? WEXITSTATUS(status) : -1;
-                return {code, output};
-            }
-
-            if (cancel && cancel->is_cancelled()) break;
-            if (std::chrono::steady_clock::now() >= deadline) break;
-
-            std::this_thread::sleep_for(std::chrono::milliseconds{100});
-        }
-
-        ::kill(-h.pid, SIGTERM);
-        auto kill_deadline = std::chrono::steady_clock::now() + std::chrono::seconds{2};
-        while (std::chrono::steady_clock::now() < kill_deadline) {
-            int status = 0;
-            pid_t result = ::waitpid(h.pid, &status, WNOHANG);
-            if (result == h.pid) { ::close(h.pipe_fd); return {-1, output}; }
-            std::this_thread::sleep_for(std::chrono::milliseconds{100});
-        }
-        ::kill(-h.pid, SIGKILL);
-        int status = 0;
-        ::waitpid(h.pid, &status, 0);
-        ::close(h.pipe_fd);
-        return {-1, output};
-    }
+                             std::chrono::milliseconds timeout) -> std::pair<int, std::string>;
 
-    export void clear_console() {
-        std::system("clear");
-    }
+    export void clear_console();
 
-    export std::string get_home_dir() {
-        if (const char* home = std::getenv("HOME")) return home;
-        return ".";
-    }
+    export std::string get_home_dir();
 
-    export void set_env_variable(const std::string& key, const std::string& value) {
-        ::setenv(key.c_str(), value.c_str(), 1);
-    }
+    export void set_env_variable(const std::string& key, const std::string& value);
 
-    export void make_files_executable(const std::filesystem::path& dir) {
-        if (!std::filesystem::exists(dir)) return;
-        for (auto it = std::filesystem::directory_iterator(dir); it != std::default_sentinel; ++it) {
-            if (it->is_regular_file())
-                ::chmod(it->path().c_str(), 0755);
-        }
-        std::string cmd = "xattr -cr \"" + dir.string() + "\" 2>/dev/null";
-        std::system(cmd.c_str());
-    }
+    export void make_files_executable(const std::filesystem::path& dir);
 
     export bool create_directory_link(const std::filesystem::path& link,
-                                      const std::filesystem::path& target) {
-        std::error_code ec;
-        if (std::filesystem::is_symlink(link)) {
-            std::filesystem::remove(link, ec);
-        } else if (std::filesystem::exists(link)) {
-            std::filesystem::remove_all(link, ec);
-        }
-        auto linkTarget = target;
-        auto rel = std::filesystem::relative(target, link.parent_path(), ec);
-        if (!ec && !rel.empty()) linkTarget = rel;
-        ec.clear();
-        std::filesystem::create_directory_symlink(linkTarget, link, ec);
-        return !static_cast<bool>(ec);
-    }
+                                      const std::filesystem::path& target);
 
     // No-op on macOS — terminal generally supports ANSI natively.
-    export void init_console_output() {}
+    export void init_console_output();
 
     // Check if stdout is a TTY (supports cursor save/restore).
-    export bool supports_rewrite_output() {
-        return ::isatty(STDOUT_FILENO) != 0;
-    }
+    export bool supports_rewrite_output();
 
     // Check if stderr is a TTY. Separate from stdout because warnings and
     // errors go to stderr: `xlings install > log` still has an interactive
     // stderr, and `2>&1 | cat` has neither.
-    export bool stderr_is_terminal() {
-        return ::isatty(STDERR_FILENO) != 0;
-    }
+    export bool stderr_is_terminal();
 
     // Check if stdin is a TTY — i.e. whether there is someone there to answer
     // an interactive prompt.
-    export bool stdin_is_terminal() {
-        return ::isatty(STDIN_FILENO) != 0;
-    }
+    export bool stdin_is_terminal();
 
     export template<typename... Args>
     void println(std::format_string<Args...> fmt, Args&&... args) {
@@ -200,18 +74,12 @@ namespace platform_impl {
     }
 
     export inline void println(const std::string& msg) {
-        std::println("{}", msg);
+        std::println(stdout, "{}", msg);
     }
 
-    export int get_pid() {
-        return static_cast<int>(::getpid());
-    }
+    export int get_pid();
 
-    export bool is_process_alive(int pid) {
-        if (pid <= 0) return false;
-        // kill(pid, 0) checks process existence without sending a signal
-        return ::kill(pid, 0) == 0;
-    }
+    export bool is_process_alive(int pid);
 
     // query_terminal_is_light() lives in :unix — shared with Linux.
 
diff --git a/src/platform/target.cpp b/src/platform/target.cpp
new file mode 100644
index 00000000..ea487e25
--- /dev/null
+++ b/src/platform/target.cpp
@@ -0,0 +1,62 @@
+module;
+
+#if defined(_WIN32)
+#define NOMINMAX
+#include <windows.h>
+#else
+#include <sys/utsname.h>
+#endif
+
+module xlings.platform.target;
+
+import std;
+
+namespace xlings::platform {
+
+const Target& build() {
+    static const Target value{std::string(build_os()), std::string(build_arch())};
+    return value;
+}
+
+const Target& host() {
+    static const Target value = [] {
+        Target target{std::string(build_os()), std::string(build_arch())};
+#if defined(_WIN32)
+        SYSTEM_INFO info{};
+        ::GetNativeSystemInfo(&info);
+        switch (info.wProcessorArchitecture) {
+            case PROCESSOR_ARCHITECTURE_ARM64: target.arch = "aarch64"; break;
+            case PROCESSOR_ARCHITECTURE_AMD64: target.arch = "x86_64"; break;
+            case PROCESSOR_ARCHITECTURE_INTEL: target.arch = "x86"; break;
+            default: break;
+        }
+#else
+        struct utsname info{};
+        if (::uname(&info) == 0) {
+            const std::string_view machine{info.machine};
+            if (machine == "aarch64" || machine == "arm64") {
+                target.arch = build_os() == "macosx" ? "arm64" : "aarch64";
+            } else if (machine == "x86_64" || machine == "amd64") {
+                target.arch = "x86_64";
+            } else if (machine == "i386" || machine == "i686") {
+                target.arch = "x86";
+            }
+        }
+#endif
+        return target;
+    }();
+    return value;
+}
+
+bool is_emulated() { return build().arch != host().arch; }
+
+}
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::platform {
+
+std::string Target::str() const { return os + "-" + arch; }
+
+} // namespace xlings::platform
diff --git a/src/platform/target.cppm b/src/platform/target.cppm
index 89a02b0a..abcee786 100644
--- a/src/platform/target.cppm
+++ b/src/platform/target.cppm
@@ -41,7 +41,7 @@ struct Target {
     std::string os;    // linux | macosx | windows
     std::string arch;  // x86_64 | aarch64 | arm64 (macOS) | x86 | unknown
 
-    std::string str() const { return os + "-" + arch; }
+    std::string str() const;
 };
 
 // Written out rather than `= default`: a defaulted hidden-friend comparison in
@@ -80,47 +80,16 @@ constexpr std::string_view build_arch() {
 }
 
 // The ABI of this process. Compile-time, and deliberately so.
-const Target& build() {
-    static const Target value{std::string(build_os()), std::string(build_arch())};
-    return value;
-}
+const Target& build();
 
 // What the kernel reports. Falls back to build() when it cannot be read, so a
 // caller never has to handle "unknown machine" separately -- the interesting
 // case is only ever "these two disagree".
-const Target& host() {
-    static const Target value = [] {
-        Target target{std::string(build_os()), std::string(build_arch())};
-#if defined(_WIN32)
-        SYSTEM_INFO info{};
-        ::GetNativeSystemInfo(&info);
-        switch (info.wProcessorArchitecture) {
-            case PROCESSOR_ARCHITECTURE_ARM64: target.arch = "aarch64"; break;
-            case PROCESSOR_ARCHITECTURE_AMD64: target.arch = "x86_64"; break;
-            case PROCESSOR_ARCHITECTURE_INTEL: target.arch = "x86"; break;
-            default: break;
-        }
-#else
-        struct utsname info{};
-        if (::uname(&info) == 0) {
-            const std::string_view machine{info.machine};
-            if (machine == "aarch64" || machine == "arm64") {
-                target.arch = build_os() == "macosx" ? "arm64" : "aarch64";
-            } else if (machine == "x86_64" || machine == "amd64") {
-                target.arch = "x86_64";
-            } else if (machine == "i386" || machine == "i686") {
-                target.arch = "x86";
-            }
-        }
-#endif
-        return target;
-    }();
-    return value;
-}
+const Target& host();
 
 // True when this binary is running on hardware it was not built for -- Rosetta
 // 2, WOW64, qemu-user, box64. Not an error: the emulated build works, and
 // switching to a native one is the user's call.
-bool is_emulated() { return build().arch != host().arch; }
+bool is_emulated();
 
 }  // namespace xlings::platform
diff --git a/src/platform/unix.cpp b/src/platform/unix.cpp
new file mode 100644
index 00000000..35248b59
--- /dev/null
+++ b/src/platform/unix.cpp
@@ -0,0 +1,300 @@
+module;
+
+#include <cstdio>
+#include <cstdlib>
+#include <cerrno>
+#if defined(__linux__) || defined(__APPLE__)
+#include <unistd.h>
+#include <fcntl.h>
+#include <termios.h>
+#include <sys/select.h>
+#include <sys/time.h>
+#include <sys/file.h>
+#include <pwd.h>
+#endif
+#if defined(__linux__)
+#include <sys/syscall.h>
+#ifndef RENAME_EXCHANGE
+#define RENAME_EXCHANGE (1u << 1)   // <linux/fs.h>; defined here to avoid header clashes
+#endif
+#endif
+
+module xlings.platform;
+
+import std;
+
+#if defined(__linux__) || defined(__APPLE__)
+
+namespace xlings {
+
+namespace platform_impl {
+
+std::optional<bool> parse_terminal_bg_is_light(std::string_view s) {
+        auto p = s.find("rgb:");
+        if (p == std::string_view::npos || p + 4 + 14 > s.size()) return std::nullopt;
+        auto hex4 = [&](std::size_t off) -> int {
+            int v = 0;
+            for (int i = 0; i < 4 && off + i < s.size(); ++i) {
+                char c = s[off + i];
+                int d = (c >= '0' && c <= '9') ? c - '0'
+                      : (c >= 'a' && c <= 'f') ? c - 'a' + 10
+                      : (c >= 'A' && c <= 'F') ? c - 'A' + 10 : -1;
+                if (d < 0) return -1;
+                v = v * 16 + d;
+            }
+            return v;  // 16-bit channel, 0..65535
+        };
+        int r = hex4(p + 4), g = hex4(p + 9), b = hex4(p + 14);
+        if (r < 0 || g < 0 || b < 0) return std::nullopt;
+        // Rec. 601 luma; threshold at half-bright.
+        return (0.299 * r + 0.587 * g + 0.114 * b) > 32768.0;
+    }
+
+std::string read_terminal_query_reply(int fd,
+                                                 std::chrono::milliseconds timeout) {
+        std::string acc;
+        acc.reserve(64);
+        constexpr std::size_t kCap = 512;   // bounded buffer
+        const auto deadline = std::chrono::steady_clock::now() + timeout;
+        for (;;) {
+            auto now = std::chrono::steady_clock::now();
+            if (now >= deadline) break;
+            auto us = std::chrono::duration_cast<std::chrono::microseconds>(
+                          deadline - now).count();
+            fd_set rfds; FD_ZERO(&rfds); FD_SET(fd, &rfds);
+            struct timeval tv{
+                static_cast<time_t>(us / 1000000),
+                static_cast<suseconds_t>(us % 1000000)
+            };
+            int rv = ::select(fd + 1, &rfds, nullptr, nullptr, &tv);
+            if (rv < 0) { if (errno == EINTR) continue; break; }
+            if (rv == 0) break;                     // deadline reached
+            char buf[256];
+            auto n = ::read(fd, buf, sizeof(buf));
+            if (n < 0) { if (errno == EINTR) continue; break; }
+            if (n == 0) break;                      // EOF
+            acc.append(buf, static_cast<std::size_t>(n));
+            if (acc.find('R') != std::string::npos) break;   // CPR fence
+            if (acc.size() >= kCap) break;
+        }
+        return acc;
+    }
+
+    // Overall deadline for the terminal background query. Default 500 ms,
+    // overridable via XLINGS_TERM_QUERY_TIMEOUT_MS (clamped to [50, 5000]).
+    // Responsive terminals hit the CPR fence in a few ms and return early;
+    // the deadline only bites on a tty that answers neither OSC-11 nor DSR.
+    
+std::chrono::milliseconds term_query_timeout_() {
+        long ms = 500;
+        if (const char* v = std::getenv("XLINGS_TERM_QUERY_TIMEOUT_MS")) {
+            char* end = nullptr;
+            long parsed = std::strtol(v, &end, 10);
+            if (end != v && parsed > 0) ms = parsed;
+        }
+        if (ms < 50)   ms = 50;
+        if (ms > 5000) ms = 5000;
+        return std::chrono::milliseconds{ms};
+    }
+
+std::optional<bool> query_terminal_is_light() {
+        // If our own stdout AND stderr are not terminals, we're a child whose
+        // output is captured by a parent (e.g. mcpp driving `xlings interface`
+        // over a pipe). Do NOT poke /dev/tty then: the OSC-11 query races with
+        // the parent's rendering and the raw reply (\e]11;rgb:...) leaks into
+        // the visible terminal and desyncs its input on some terminals (Termux),
+        // which is what makes the user have to press Enter. Fall back to
+        // env/default detection in that case.
+        if (!::isatty(STDOUT_FILENO) && !::isatty(STDERR_FILENO)) return std::nullopt;
+
+        int fd = ::open("/dev/tty", O_RDWR | O_NOCTTY);
+        if (fd < 0) return std::nullopt;
+        struct CloseGuard { int fd; ~CloseGuard() { ::close(fd); } } _g{fd};
+
+        struct termios saved{};
+        if (::tcgetattr(fd, &saved) != 0) return std::nullopt;
+        struct termios raw = saved;
+        raw.c_lflag &= ~(static_cast<tcflag_t>(ICANON) | static_cast<tcflag_t>(ECHO));
+        raw.c_cc[VMIN]  = 0;
+        raw.c_cc[VTIME] = 0;
+        if (::tcsetattr(fd, TCSANOW, &raw) != 0) return std::nullopt;
+        struct RestoreGuard {
+            int fd; struct termios s;
+            ~RestoreGuard() { ::tcsetattr(fd, TCSANOW, &s); }
+        } _r{fd, saved};
+
+        // OSC-11 background query, immediately followed by a DSR cursor
+        // position request. The CPR reply to the DSR is our fence (see
+        // read_terminal_query_reply): once it arrives we know the OSC-11
+        // reply, if any, has fully arrived and been consumed — so ECHO is
+        // never restored with terminal bytes still pending in the input.
+        static constexpr char query[] = "\033]11;?\033\\\033[6n";
+        if (::write(fd, query, sizeof(query) - 1) < 0) return std::nullopt;
+
+        std::string reply = read_terminal_query_reply(fd, term_query_timeout_());
+        return parse_terminal_bg_is_light(reply);
+    }
+
+bool displace_locked_file(const std::filesystem::path& path) {
+        namespace fs = std::filesystem;
+        std::error_code ec;
+        if (!fs::exists(path, ec) && !fs::is_symlink(path, ec)) return true;
+        ec.clear();
+        fs::remove(path, ec);
+        ec.clear();
+        return !fs::exists(path, ec) && !fs::is_symlink(path, ec);
+    }
+
+bool atomic_replace_executable(const std::filesystem::path& src,
+                                          const std::filesystem::path& dst) {
+        namespace fs = std::filesystem;
+        std::error_code ec;
+
+        if (!fs::exists(src, ec) || ec) return false;
+
+        fs::create_directories(dst.parent_path(), ec);
+        ec.clear();
+
+        auto tmp = dst;
+        tmp += ".xlings.new";
+
+        // Pre-clean any leftover from a previous interrupted run.
+        if (fs::exists(tmp, ec)) {
+            fs::remove(tmp, ec);
+            ec.clear();
+        }
+
+        fs::copy_file(src, tmp, fs::copy_options::overwrite_existing, ec);
+        if (ec) {
+            std::error_code rmec;
+            fs::remove(tmp, rmec);
+            return false;
+        }
+
+        fs::permissions(tmp,
+            fs::perms::owner_all
+          | fs::perms::group_read | fs::perms::group_exec
+          | fs::perms::others_read | fs::perms::others_exec,
+            fs::perm_options::replace, ec);
+        ec.clear();
+
+        fs::rename(tmp, dst, ec);
+        if (!ec) return true;
+
+        // Cross-filesystem fallback (rare: ec == EXDEV). copy + remove tmp.
+        if (ec == std::errc::cross_device_link) {
+            ec.clear();
+            fs::copy_file(tmp, dst, fs::copy_options::overwrite_existing, ec);
+            std::error_code rmec;
+            fs::remove(tmp, rmec);
+            return !ec;
+        }
+
+        std::error_code rmec;
+        fs::remove(tmp, rmec);
+        return false;
+    }
+
+bool atomic_swap_paths(const std::filesystem::path& a,
+                                  const std::filesystem::path& b) {
+#if defined(__linux__)
+        long rc = ::syscall(SYS_renameat2, AT_FDCWD, a.c_str(),
+                            AT_FDCWD, b.c_str(),
+                            static_cast<unsigned int>(RENAME_EXCHANGE));
+        return rc == 0;
+#else
+        // macOS has renamex_np(.., RENAME_SWAP) but it is not wired up yet;
+        // returning false keeps the portable manual-swap fallback in charge.
+        (void)a; (void)b;
+        return false;
+#endif
+    }
+
+bool is_root() {
+        return ::geteuid() == 0;
+    }
+
+void lchown_path_(const std::filesystem::path& p,
+                             unsigned int uid, unsigned int gid) {
+        ::lchown(p.c_str(), static_cast<uid_t>(uid), static_cast<gid_t>(gid));
+    }
+
+std::string home_for_user_(const std::string& name) {
+        if (name.empty()) return {};
+        if (struct passwd* pw = ::getpwnam(name.c_str()); pw && pw->pw_dir)
+            return std::string{pw->pw_dir};
+        return {};
+    }
+
+}
+
+}
+
+ // namespace xlings
+
+#endif // defined(__linux__) || defined(__APPLE__)
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+#if (defined(__linux__) || defined(__APPLE__))
+
+namespace xlings::platform_impl {
+
+FileLock::FileLock(FileLock&& other) noexcept : fd_(std::exchange(other.fd_, -1)) {}
+
+FileLock& FileLock::operator=(FileLock&& other) noexcept {
+    if (this != &other) {
+        release();
+        fd_ = std::exchange(other.fd_, -1);
+    }
+    return *this;
+}
+
+FileLock::~FileLock() { release(); }
+
+bool FileLock::acquire(const std::filesystem::path& path,
+                     std::chrono::milliseconds timeout,
+                     const std::function<bool()>& cancelled,
+                     std::string& error) {
+    release();
+    fd_ = ::open(path.c_str(), O_CREAT | O_RDWR, 0600);
+    if (fd_ < 0) {
+        error = std::format("failed to open lock {}: {}",
+                            path.string(), std::strerror(errno));
+        return false;
+    }
+    auto deadline = std::chrono::steady_clock::now() + timeout;
+    while (::flock(fd_, LOCK_EX | LOCK_NB) != 0) {
+        if (errno != EWOULDBLOCK && errno != EAGAIN) {
+            error = std::format("failed to lock {}: {}",
+                                path.string(), std::strerror(errno));
+            release();
+            return false;
+        }
+        if (cancelled && cancelled()) {
+            error = "cancelled while waiting for cache lock";
+            release();
+            return false;
+        }
+        if (std::chrono::steady_clock::now() >= deadline) {
+            error = std::format("timed out waiting for cache lock {}",
+                                path.string());
+            release();
+            return false;
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds{50});
+    }
+    return true;
+}
+
+void FileLock::release() {
+    if (fd_ < 0) return;
+    ::flock(fd_, LOCK_UN);
+    ::close(fd_);
+    fd_ = -1;
+}
+
+} // namespace xlings::platform_impl
+
+#endif
diff --git a/src/platform/unix.cppm b/src/platform/unix.cppm
index c1362311..c821a5ce 100644
--- a/src/platform/unix.cppm
+++ b/src/platform/unix.cppm
@@ -33,57 +33,16 @@ namespace platform_impl {
         FileLock() = default;
         FileLock(const FileLock&) = delete;
         FileLock& operator=(const FileLock&) = delete;
-        FileLock(FileLock&& other) noexcept : fd_(std::exchange(other.fd_, -1)) {}
-        FileLock& operator=(FileLock&& other) noexcept {
-            if (this != &other) {
-                release();
-                fd_ = std::exchange(other.fd_, -1);
-            }
-            return *this;
-        }
-        ~FileLock() { release(); }
+        FileLock(FileLock&& other) noexcept;
+        FileLock& operator=(FileLock&& other) noexcept;
+        ~FileLock();
 
         bool acquire(const std::filesystem::path& path,
                      std::chrono::milliseconds timeout,
                      const std::function<bool()>& cancelled,
-                     std::string& error) {
-            release();
-            fd_ = ::open(path.c_str(), O_CREAT | O_RDWR, 0600);
-            if (fd_ < 0) {
-                error = std::format("failed to open lock {}: {}",
-                                    path.string(), std::strerror(errno));
-                return false;
-            }
-            auto deadline = std::chrono::steady_clock::now() + timeout;
-            while (::flock(fd_, LOCK_EX | LOCK_NB) != 0) {
-                if (errno != EWOULDBLOCK && errno != EAGAIN) {
-                    error = std::format("failed to lock {}: {}",
-                                        path.string(), std::strerror(errno));
-                    release();
-                    return false;
-                }
-                if (cancelled && cancelled()) {
-                    error = "cancelled while waiting for cache lock";
-                    release();
-                    return false;
-                }
-                if (std::chrono::steady_clock::now() >= deadline) {
-                    error = std::format("timed out waiting for cache lock {}",
-                                        path.string());
-                    release();
-                    return false;
-                }
-                std::this_thread::sleep_for(std::chrono::milliseconds{50});
-            }
-            return true;
-        }
+                     std::string& error);
 
-        void release() {
-            if (fd_ < 0) return;
-            ::flock(fd_, LOCK_UN);
-            ::close(fd_);
-            fd_ = -1;
-        }
+        void release();
 
     private:
         int fd_ { -1 };
@@ -98,26 +57,7 @@ namespace platform_impl {
     // The buffer may contain unrelated leading bytes (e.g. a CPR fence) and
     // may be terminated by either ST (\e\\) or BEL (\a) — parsing keys off
     // the `rgb:` marker, not the terminator.
-    export std::optional<bool> parse_terminal_bg_is_light(std::string_view s) {
-        auto p = s.find("rgb:");
-        if (p == std::string_view::npos || p + 4 + 14 > s.size()) return std::nullopt;
-        auto hex4 = [&](std::size_t off) -> int {
-            int v = 0;
-            for (int i = 0; i < 4 && off + i < s.size(); ++i) {
-                char c = s[off + i];
-                int d = (c >= '0' && c <= '9') ? c - '0'
-                      : (c >= 'a' && c <= 'f') ? c - 'a' + 10
-                      : (c >= 'A' && c <= 'F') ? c - 'A' + 10 : -1;
-                if (d < 0) return -1;
-                v = v * 16 + d;
-            }
-            return v;  // 16-bit channel, 0..65535
-        };
-        int r = hex4(p + 4), g = hex4(p + 9), b = hex4(p + 14);
-        if (r < 0 || g < 0 || b < 0) return std::nullopt;
-        // Rec. 601 luma; threshold at half-bright.
-        return (0.299 * r + 0.587 * g + 0.114 * b) > 32768.0;
-    }
+    export std::optional<bool> parse_terminal_bg_is_light(std::string_view s);
 
     // Read a terminal query reply from `fd` as a framed byte stream: loop
     // select()+read() against ONE monotonic deadline, accumulating fragments
@@ -133,50 +73,7 @@ namespace platform_impl {
     // let the reply leak into the parent shell. Reading through the CPR
     // consumes the whole reply while ECHO is still disabled, so nothing leaks.
     export std::string read_terminal_query_reply(int fd,
-                                                 std::chrono::milliseconds timeout) {
-        std::string acc;
-        acc.reserve(64);
-        constexpr std::size_t kCap = 512;   // bounded buffer
-        const auto deadline = std::chrono::steady_clock::now() + timeout;
-        for (;;) {
-            auto now = std::chrono::steady_clock::now();
-            if (now >= deadline) break;
-            auto us = std::chrono::duration_cast<std::chrono::microseconds>(
-                          deadline - now).count();
-            fd_set rfds; FD_ZERO(&rfds); FD_SET(fd, &rfds);
-            struct timeval tv{
-                static_cast<time_t>(us / 1000000),
-                static_cast<suseconds_t>(us % 1000000)
-            };
-            int rv = ::select(fd + 1, &rfds, nullptr, nullptr, &tv);
-            if (rv < 0) { if (errno == EINTR) continue; break; }
-            if (rv == 0) break;                     // deadline reached
-            char buf[256];
-            auto n = ::read(fd, buf, sizeof(buf));
-            if (n < 0) { if (errno == EINTR) continue; break; }
-            if (n == 0) break;                      // EOF
-            acc.append(buf, static_cast<std::size_t>(n));
-            if (acc.find('R') != std::string::npos) break;   // CPR fence
-            if (acc.size() >= kCap) break;
-        }
-        return acc;
-    }
-
-    // Overall deadline for the terminal background query. Default 500 ms,
-    // overridable via XLINGS_TERM_QUERY_TIMEOUT_MS (clamped to [50, 5000]).
-    // Responsive terminals hit the CPR fence in a few ms and return early;
-    // the deadline only bites on a tty that answers neither OSC-11 nor DSR.
-    static std::chrono::milliseconds term_query_timeout_() {
-        long ms = 500;
-        if (const char* v = std::getenv("XLINGS_TERM_QUERY_TIMEOUT_MS")) {
-            char* end = nullptr;
-            long parsed = std::strtol(v, &end, 10);
-            if (end != v && parsed > 0) ms = parsed;
-        }
-        if (ms < 50)   ms = 50;
-        if (ms > 5000) ms = 5000;
-        return std::chrono::milliseconds{ms};
-    }
+                                                 std::chrono::milliseconds timeout);
 
     // Query the controlling terminal for its background color via the
     // OSC-11 sequence (xterm spec, supported by xterm / iTerm2 / Alacritty
@@ -189,43 +86,7 @@ namespace platform_impl {
     // is identical across Linux and macOS — both inherit the POSIX terminal
     // API. windows.cppm provides its own stub. Putting it here means
     // linux.cppm and macos.cppm carry no copy of this code.
-    export std::optional<bool> query_terminal_is_light() {
-        // If our own stdout AND stderr are not terminals, we're a child whose
-        // output is captured by a parent (e.g. mcpp driving `xlings interface`
-        // over a pipe). Do NOT poke /dev/tty then: the OSC-11 query races with
-        // the parent's rendering and the raw reply (\e]11;rgb:...) leaks into
-        // the visible terminal and desyncs its input on some terminals (Termux),
-        // which is what makes the user have to press Enter. Fall back to
-        // env/default detection in that case.
-        if (!::isatty(STDOUT_FILENO) && !::isatty(STDERR_FILENO)) return std::nullopt;
-
-        int fd = ::open("/dev/tty", O_RDWR | O_NOCTTY);
-        if (fd < 0) return std::nullopt;
-        struct CloseGuard { int fd; ~CloseGuard() { ::close(fd); } } _g{fd};
-
-        struct termios saved{};
-        if (::tcgetattr(fd, &saved) != 0) return std::nullopt;
-        struct termios raw = saved;
-        raw.c_lflag &= ~(static_cast<tcflag_t>(ICANON) | static_cast<tcflag_t>(ECHO));
-        raw.c_cc[VMIN]  = 0;
-        raw.c_cc[VTIME] = 0;
-        if (::tcsetattr(fd, TCSANOW, &raw) != 0) return std::nullopt;
-        struct RestoreGuard {
-            int fd; struct termios s;
-            ~RestoreGuard() { ::tcsetattr(fd, TCSANOW, &s); }
-        } _r{fd, saved};
-
-        // OSC-11 background query, immediately followed by a DSR cursor
-        // position request. The CPR reply to the DSR is our fence (see
-        // read_terminal_query_reply): once it arrives we know the OSC-11
-        // reply, if any, has fully arrived and been consumed — so ECHO is
-        // never restored with terminal bytes still pending in the input.
-        static constexpr char query[] = "\033]11;?\033\\\033[6n";
-        if (::write(fd, query, sizeof(query) - 1) < 0) return std::nullopt;
-
-        std::string reply = read_terminal_query_reply(fd, term_query_timeout_());
-        return parse_terminal_bg_is_light(reply);
-    }
+    export std::optional<bool> query_terminal_is_light();
 
     // Atomically replace `dst` with the contents of `src`, even when `dst`
     // is the currently running executable.
@@ -247,65 +108,10 @@ namespace platform_impl {
     // name, so a running executable's path is released immediately and the
     // process keeps its inode -- no displacement needed. Present so callers
     // do not have to know which platform they are on.
-    export bool displace_locked_file(const std::filesystem::path& path) {
-        namespace fs = std::filesystem;
-        std::error_code ec;
-        if (!fs::exists(path, ec) && !fs::is_symlink(path, ec)) return true;
-        ec.clear();
-        fs::remove(path, ec);
-        ec.clear();
-        return !fs::exists(path, ec) && !fs::is_symlink(path, ec);
-    }
+    export bool displace_locked_file(const std::filesystem::path& path);
 
     export bool atomic_replace_executable(const std::filesystem::path& src,
-                                          const std::filesystem::path& dst) {
-        namespace fs = std::filesystem;
-        std::error_code ec;
-
-        if (!fs::exists(src, ec) || ec) return false;
-
-        fs::create_directories(dst.parent_path(), ec);
-        ec.clear();
-
-        auto tmp = dst;
-        tmp += ".xlings.new";
-
-        // Pre-clean any leftover from a previous interrupted run.
-        if (fs::exists(tmp, ec)) {
-            fs::remove(tmp, ec);
-            ec.clear();
-        }
-
-        fs::copy_file(src, tmp, fs::copy_options::overwrite_existing, ec);
-        if (ec) {
-            std::error_code rmec;
-            fs::remove(tmp, rmec);
-            return false;
-        }
-
-        fs::permissions(tmp,
-            fs::perms::owner_all
-          | fs::perms::group_read | fs::perms::group_exec
-          | fs::perms::others_read | fs::perms::others_exec,
-            fs::perm_options::replace, ec);
-        ec.clear();
-
-        fs::rename(tmp, dst, ec);
-        if (!ec) return true;
-
-        // Cross-filesystem fallback (rare: ec == EXDEV). copy + remove tmp.
-        if (ec == std::errc::cross_device_link) {
-            ec.clear();
-            fs::copy_file(tmp, dst, fs::copy_options::overwrite_existing, ec);
-            std::error_code rmec;
-            fs::remove(tmp, rmec);
-            return !ec;
-        }
-
-        std::error_code rmec;
-        fs::remove(tmp, rmec);
-        return false;
-    }
+                                          const std::filesystem::path& dst);
 
     // Atomically swap two existing paths in a single, uninterruptible step.
     // Both paths must already exist. Returns true on a real atomic exchange
@@ -319,44 +125,23 @@ namespace platform_impl {
     // official index to a destructive git clone. See
     // .agents/docs/2026-06-30-index-artifact-git-regression-analysis.md.
     export bool atomic_swap_paths(const std::filesystem::path& a,
-                                  const std::filesystem::path& b) {
-#if defined(__linux__)
-        long rc = ::syscall(SYS_renameat2, AT_FDCWD, a.c_str(),
-                            AT_FDCWD, b.c_str(),
-                            static_cast<unsigned int>(RENAME_EXCHANGE));
-        return rc == 0;
-#else
-        // macOS has renamex_np(.., RENAME_SWAP) but it is not wired up yet;
-        // returning false keeps the portable manual-swap fallback in charge.
-        (void)a; (void)b;
-        return false;
-#endif
-    }
+                                  const std::filesystem::path& b);
 
     // ── Execution identity primitives (root / sudo awareness) ───────
     // Only the OS primitives live here; all policy (sudo parsing, priv
     // prefix, chown-back) is cross-platform in platform.cppm. See
     // .agents/docs/2026-06-21-root-privilege-identity-design.md.
 
-    export bool is_root() {
-        return ::geteuid() == 0;
-    }
+    export bool is_root();
 
     // Single-path lchown (don't follow symlinks). Best-effort: ownership
     // restoration must never abort an otherwise-successful operation, so
     // the return value is intentionally ignored.
     export void lchown_path_(const std::filesystem::path& p,
-                             unsigned int uid, unsigned int gid) {
-        ::lchown(p.c_str(), static_cast<uid_t>(uid), static_cast<gid_t>(gid));
-    }
+                             unsigned int uid, unsigned int gid);
 
     // Resolve a user's home dir from the passwd db. Empty on lookup miss.
-    export std::string home_for_user_(const std::string& name) {
-        if (name.empty()) return {};
-        if (struct passwd* pw = ::getpwnam(name.c_str()); pw && pw->pw_dir)
-            return std::string{pw->pw_dir};
-        return {};
-    }
+    export std::string home_for_user_(const std::string& name);
 
 } // namespace platform_impl
 } // namespace xlings
diff --git a/src/platform/windows.cpp b/src/platform/windows.cpp
new file mode 100644
index 00000000..489c3752
--- /dev/null
+++ b/src/platform/windows.cpp
@@ -0,0 +1,407 @@
+module;
+
+#include <cstdio>
+#include <cstdlib>
+#if defined(_WIN32)
+#define NOMINMAX
+#include <windows.h>
+#endif
+
+module xlings.platform;
+
+import std;
+import xlings.runtime.cancellation;
+
+#if defined(_WIN32)
+
+namespace xlings {
+
+namespace platform_impl {
+
+std::filesystem::path get_executable_path() {
+        wchar_t buf[MAX_PATH];
+        DWORD n = ::GetModuleFileNameW(nullptr, buf, MAX_PATH);
+        if (n == 0) return {};
+        return std::filesystem::path(buf);
+    }
+
+std::pair<int, std::string> run_command_capture(const std::string& cmd) {
+        std::string full = cmd + " 2>&1";
+        FILE* pipe = ::_popen(full.c_str(), "r");
+        if (!pipe) {
+            return {-1, std::string{}};
+        }
+        std::string output;
+        std::array<char, 256> buffer{};
+        while (fgets(buffer.data(), buffer.size(), pipe) != nullptr) {
+            output += buffer.data();
+        }
+        int status = ::_pclose(pipe);
+        return {status, output};
+    }
+
+auto spawn_command(const std::string& cmd) -> ProcessHandle {
+        SECURITY_ATTRIBUTES sa;
+        sa.nLength = sizeof(sa);
+        sa.bInheritHandle = TRUE;
+        sa.lpSecurityDescriptor = nullptr;
+
+        HANDLE hReadPipe, hWritePipe;
+        if (!::CreatePipe(&hReadPipe, &hWritePipe, &sa, 0)) {
+            return {};
+        }
+        ::SetHandleInformation(hReadPipe, HANDLE_FLAG_INHERIT, 0);
+
+        STARTUPINFOA si{};
+        si.cb = sizeof(si);
+        si.dwFlags = STARTF_USESTDHANDLES;
+        si.hStdOutput = hWritePipe;
+        si.hStdError = hWritePipe;
+
+        PROCESS_INFORMATION pi{};
+        std::string cmdline = "cmd /c " + cmd;
+
+        BOOL ok = ::CreateProcessA(
+            nullptr, cmdline.data(), nullptr, nullptr, TRUE,
+            CREATE_NEW_PROCESS_GROUP, nullptr, nullptr, &si, &pi);
+
+        ::CloseHandle(hWritePipe);
+
+        if (!ok) {
+            ::CloseHandle(hReadPipe);
+            return {};
+        }
+
+        ::CloseHandle(pi.hThread);
+
+        ProcessHandle h;
+        h.pid = static_cast<int>(pi.dwProcessId);
+        h.hProcess = pi.hProcess;
+        h.hReadPipe = hReadPipe;
+        return h;
+    }
+
+auto wait_or_kill(const ProcessHandle& h,
+                             CancellationToken* cancel,
+                             std::chrono::milliseconds timeout) -> std::pair<int, std::string> {
+        if (!h.hProcess) return {-1, ""};
+
+        std::string output;
+        std::array<char, 4096> buf{};
+        auto deadline = std::chrono::steady_clock::now() + timeout;
+        HANDLE hProc = static_cast<HANDLE>(h.hProcess);
+        HANDLE hPipe = static_cast<HANDLE>(h.hReadPipe);
+
+        while (true) {
+            // Read available output
+            DWORD avail = 0;
+            while (::PeekNamedPipe(hPipe, nullptr, 0, nullptr, &avail, nullptr) && avail > 0) {
+                DWORD bytesRead = 0;
+                DWORD toRead = std::min(avail, static_cast<DWORD>(buf.size()));
+                if (::ReadFile(hPipe, buf.data(), toRead, &bytesRead, nullptr) && bytesRead > 0) {
+                    output.append(buf.data(), bytesRead);
+                } else break;
+            }
+
+            // Check if process exited
+            DWORD exitCode = 0;
+            if (::WaitForSingleObject(hProc, 0) == WAIT_OBJECT_0) {
+                // Read remaining
+                while (::PeekNamedPipe(hPipe, nullptr, 0, nullptr, &avail, nullptr) && avail > 0) {
+                    DWORD bytesRead = 0;
+                    DWORD toRead = std::min(avail, static_cast<DWORD>(buf.size()));
+                    if (::ReadFile(hPipe, buf.data(), toRead, &bytesRead, nullptr) && bytesRead > 0)
+                        output.append(buf.data(), bytesRead);
+                    else break;
+                }
+                ::GetExitCodeProcess(hProc, &exitCode);
+                ::CloseHandle(hPipe);
+                ::CloseHandle(hProc);
+                return {static_cast<int>(exitCode), output};
+            }
+
+            if (cancel && cancel->is_cancelled()) break;
+            if (std::chrono::steady_clock::now() >= deadline) break;
+
+            std::this_thread::sleep_for(std::chrono::milliseconds{100});
+        }
+
+        // Terminate: Ctrl+Break to process group, then hard kill after grace period
+        ::GenerateConsoleCtrlEvent(CTRL_BREAK_EVENT, static_cast<DWORD>(h.pid));
+        if (::WaitForSingleObject(hProc, 2000) != WAIT_OBJECT_0) {
+            ::TerminateProcess(hProc, 1);
+            ::WaitForSingleObject(hProc, 1000);
+        }
+        ::CloseHandle(hPipe);
+        ::CloseHandle(hProc);
+        return {-1, output};
+    }
+
+void clear_console() {
+        std::system("cls");
+    }
+
+std::string get_home_dir() {
+        if (const char* home = std::getenv("USERPROFILE")) return home;
+        return ".";
+    }
+
+void set_env_variable(const std::string& key, const std::string& value) {
+        ::_putenv_s(key.c_str(), value.c_str());
+    }
+
+void make_files_executable(const std::filesystem::path&) {
+        // No-op: Windows does not use Unix file permissions
+    }
+
+bool create_directory_link(const std::filesystem::path& link,
+                                      const std::filesystem::path& target) {
+        std::error_code ec;
+        if (std::filesystem::is_symlink(link)) {
+            std::filesystem::remove(link, ec);
+        } else if (std::filesystem::exists(link)) {
+            std::filesystem::remove_all(link, ec);
+        }
+        auto canonTarget = std::filesystem::canonical(target, ec);
+        if (ec) canonTarget = target;
+        std::string cmd = "cmd /c mklink /J \"" + link.string() +
+                          "\" \"" + canonTarget.string() + "\" >nul 2>&1";
+        return std::system(cmd.c_str()) == 0;
+    }
+
+void init_console_output() {
+        ::SetConsoleOutputCP(CP_UTF8);
+        ::SetConsoleCP(CP_UTF8);
+
+        // Both handles. Only stdout used to be switched into VT mode, but
+        // `log::warn` and `log::error` write to stderr — so on a console
+        // their SGR was emitted to a handle that does not interpret it, and
+        // the user read the escape bytes instead of a colored `[warn]`.
+        for (DWORD which : { STD_OUTPUT_HANDLE, STD_ERROR_HANDLE }) {
+            HANDLE h = ::GetStdHandle(which);
+            if (h == INVALID_HANDLE_VALUE) continue;
+            DWORD mode = 0;
+            if (::GetConsoleMode(h, &mode)) {
+                mode |= ENABLE_VIRTUAL_TERMINAL_PROCESSING;
+                ::SetConsoleMode(h, mode);
+            }
+        }
+    }
+
+bool supports_rewrite_output() {
+        HANDLE hOut = ::GetStdHandle(STD_OUTPUT_HANDLE);
+        if (hOut == INVALID_HANDLE_VALUE) return false;
+        DWORD mode = 0;
+        if (!::GetConsoleMode(hOut, &mode)) return false;
+        return (mode & ENABLE_VIRTUAL_TERMINAL_PROCESSING) != 0;
+    }
+
+bool stderr_is_terminal() {
+        HANDLE hErr = ::GetStdHandle(STD_ERROR_HANDLE);
+        if (hErr == INVALID_HANDLE_VALUE) return false;
+        DWORD mode = 0;
+        if (!::GetConsoleMode(hErr, &mode)) return false;
+        return (mode & ENABLE_VIRTUAL_TERMINAL_PROCESSING) != 0;
+    }
+
+bool stdin_is_terminal() {
+        HANDLE hIn = ::GetStdHandle(STD_INPUT_HANDLE);
+        if (hIn == INVALID_HANDLE_VALUE) return false;
+        DWORD mode = 0;
+        return ::GetConsoleMode(hIn, &mode) != 0;
+    }
+
+int get_pid() {
+        return static_cast<int>(::GetCurrentProcessId());
+    }
+
+bool is_process_alive(int pid) {
+        if (pid <= 0) return false;
+        HANDLE hProcess = ::OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, FALSE, static_cast<DWORD>(pid));
+        if (hProcess == NULL) return false;
+        DWORD exitCode = 0;
+        bool alive = ::GetExitCodeProcess(hProcess, &exitCode) && exitCode == STILL_ACTIVE;
+        ::CloseHandle(hProcess);
+        return alive;
+    }
+
+std::optional<bool> query_terminal_is_light() {
+        return std::nullopt;
+    }
+
+bool is_root() {
+        return false;
+    }
+
+void lchown_path_(const std::filesystem::path&,
+                             unsigned int, unsigned int) {
+    }
+
+std::string home_for_user_(const std::string&) {
+        return {};
+    }
+
+bool atomic_replace_executable(const std::filesystem::path& src,
+                                          const std::filesystem::path& dst) {
+        namespace fs = std::filesystem;
+        std::error_code ec;
+
+        if (!fs::exists(src, ec) || ec) return false;
+
+        fs::create_directories(dst.parent_path(), ec);
+        ec.clear();
+
+        // Easy case: dst doesn't exist yet — just copy.
+        if (!fs::exists(dst, ec)) {
+            fs::copy_file(src, dst, fs::copy_options::overwrite_existing, ec);
+            return !ec;
+        }
+        ec.clear();
+
+        auto old_path = dst;
+        old_path += ".xlings.old";
+
+        // Best-effort cleanup of a leftover .old (may fail if still locked).
+        if (fs::exists(old_path, ec)) {
+            ::DeleteFileW(old_path.wstring().c_str());
+            ec.clear();
+        }
+
+        // Step 1: rename live binary out of the way (works even if running).
+        if (!::MoveFileExW(dst.wstring().c_str(),
+                           old_path.wstring().c_str(),
+                           MOVEFILE_REPLACE_EXISTING)) {
+            return false;
+        }
+
+        // Step 2: copy new binary into the now-free dst path.
+        fs::copy_file(src, dst, fs::copy_options::overwrite_existing, ec);
+        if (ec) {
+            // Try to restore old binary so we don't leave the user broken.
+            ::MoveFileExW(old_path.wstring().c_str(),
+                          dst.wstring().c_str(),
+                          MOVEFILE_REPLACE_EXISTING);
+            return false;
+        }
+
+        // Step 3: best-effort cleanup. If the .old file is still locked
+        // (because the running process is mapping it), schedule for
+        // deletion at next reboot.
+        if (!::DeleteFileW(old_path.wstring().c_str())) {
+            ::MoveFileExW(old_path.wstring().c_str(), nullptr,
+                          MOVEFILE_DELAY_UNTIL_REBOOT);
+        }
+
+        return true;
+    }
+
+bool displace_locked_file(const std::filesystem::path& path) {
+        namespace fs = std::filesystem;
+        std::error_code ec;
+        if (!fs::exists(path, ec) && !fs::is_symlink(path, ec)) return true;
+        ec.clear();
+
+        fs::remove(path, ec);
+        if (!ec && !fs::exists(path, ec)) return true;
+        ec.clear();
+
+        // Still there: it is open somewhere. Rename it aside. A distinct
+        // suffix per attempt so a home that has been updated repeatedly, with
+        // earlier casualties still mapped, does not collide with itself.
+        for (int attempt = 0; attempt < 16; ++attempt) {
+            auto aside = path;
+            aside += attempt == 0
+                ? std::string(".xlings.old")
+                : ".xlings.old" + std::to_string(attempt);
+            if (fs::exists(aside, ec)) {
+                ec.clear();
+                if (!::DeleteFileW(aside.wstring().c_str())) continue;
+            }
+            ec.clear();
+            if (::MoveFileExW(path.wstring().c_str(), aside.wstring().c_str(),
+                              MOVEFILE_REPLACE_EXISTING)) {
+                // The displaced copy is still mapped by the running process,
+                // so it cannot be deleted now. Let the OS drop it at reboot
+                // rather than leaving it to accumulate forever.
+                ::MoveFileExW(aside.wstring().c_str(), nullptr,
+                              MOVEFILE_DELAY_UNTIL_REBOOT);
+                return true;
+            }
+        }
+        return false;
+    }
+
+bool atomic_swap_paths(const std::filesystem::path& a,
+                                  const std::filesystem::path& b) {
+        (void)a; (void)b;
+        return false;
+    }
+
+}
+
+}
+
+#endif // defined(_WIN32)
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+#if (defined(_WIN32))
+
+namespace xlings::platform_impl {
+
+FileLock::FileLock(FileLock&& other) noexcept : handle_(std::exchange(other.handle_, INVALID_HANDLE_VALUE)) {}
+
+FileLock& FileLock::operator=(FileLock&& other) noexcept {
+    if (this != &other) {
+        release();
+        handle_ = std::exchange(other.handle_, INVALID_HANDLE_VALUE);
+    }
+    return *this;
+}
+
+FileLock::~FileLock() { release(); }
+
+bool FileLock::acquire(const std::filesystem::path& path,
+                     std::chrono::milliseconds timeout,
+                     const std::function<bool()>& cancelled,
+                     std::string& error) {
+    release();
+    auto deadline = std::chrono::steady_clock::now() + timeout;
+    while (true) {
+        handle_ = ::CreateFileW(
+            path.wstring().c_str(),
+            GENERIC_READ | GENERIC_WRITE,
+            0, nullptr, OPEN_ALWAYS,
+            FILE_ATTRIBUTE_NORMAL, nullptr);
+        if (handle_ != INVALID_HANDLE_VALUE) return true;
+        auto code = ::GetLastError();
+        if (code != ERROR_SHARING_VIOLATION
+            && code != ERROR_LOCK_VIOLATION) {
+            error = std::format(
+                "failed to lock {}: Windows error {}",
+                path.string(), code);
+            return false;
+        }
+        if (cancelled && cancelled()) {
+            error = "cancelled while waiting for cache lock";
+            return false;
+        }
+        if (std::chrono::steady_clock::now() >= deadline) {
+            error = std::format("timed out waiting for cache lock {}",
+                                path.string());
+            return false;
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds{50});
+    }
+}
+
+void FileLock::release() {
+    if (handle_ == INVALID_HANDLE_VALUE) return;
+    ::CloseHandle(handle_);
+    handle_ = INVALID_HANDLE_VALUE;
+}
+
+} // namespace xlings::platform_impl
+
+#endif
diff --git a/src/platform/windows.cppm b/src/platform/windows.cppm
index 43387d71..029b2f2c 100644
--- a/src/platform/windows.cppm
+++ b/src/platform/windows.cppm
@@ -22,56 +22,16 @@ namespace platform_impl {
         FileLock() = default;
         FileLock(const FileLock&) = delete;
         FileLock& operator=(const FileLock&) = delete;
-        FileLock(FileLock&& other) noexcept
-            : handle_(std::exchange(other.handle_, INVALID_HANDLE_VALUE)) {}
-        FileLock& operator=(FileLock&& other) noexcept {
-            if (this != &other) {
-                release();
-                handle_ = std::exchange(other.handle_, INVALID_HANDLE_VALUE);
-            }
-            return *this;
-        }
-        ~FileLock() { release(); }
+        FileLock(FileLock&& other) noexcept;
+        FileLock& operator=(FileLock&& other) noexcept;
+        ~FileLock();
 
         bool acquire(const std::filesystem::path& path,
                      std::chrono::milliseconds timeout,
                      const std::function<bool()>& cancelled,
-                     std::string& error) {
-            release();
-            auto deadline = std::chrono::steady_clock::now() + timeout;
-            while (true) {
-                handle_ = ::CreateFileW(
-                    path.wstring().c_str(),
-                    GENERIC_READ | GENERIC_WRITE,
-                    0, nullptr, OPEN_ALWAYS,
-                    FILE_ATTRIBUTE_NORMAL, nullptr);
-                if (handle_ != INVALID_HANDLE_VALUE) return true;
-                auto code = ::GetLastError();
-                if (code != ERROR_SHARING_VIOLATION
-                    && code != ERROR_LOCK_VIOLATION) {
-                    error = std::format(
-                        "failed to lock {}: Windows error {}",
-                        path.string(), code);
-                    return false;
-                }
-                if (cancelled && cancelled()) {
-                    error = "cancelled while waiting for cache lock";
-                    return false;
-                }
-                if (std::chrono::steady_clock::now() >= deadline) {
-                    error = std::format("timed out waiting for cache lock {}",
-                                        path.string());
-                    return false;
-                }
-                std::this_thread::sleep_for(std::chrono::milliseconds{50});
-            }
-        }
-
-        void release() {
-            if (handle_ == INVALID_HANDLE_VALUE) return;
-            ::CloseHandle(handle_);
-            handle_ = INVALID_HANDLE_VALUE;
-        }
+                     std::string& error);
+
+        void release();
 
     private:
         HANDLE handle_ { INVALID_HANDLE_VALUE };
@@ -80,27 +40,9 @@ namespace platform_impl {
     export constexpr char PATH_SEPARATOR = ';';
     export constexpr std::string_view OS_NAME = "windows";
 
-    export std::filesystem::path get_executable_path() {
-        wchar_t buf[MAX_PATH];
-        DWORD n = ::GetModuleFileNameW(nullptr, buf, MAX_PATH);
-        if (n == 0) return {};
-        return std::filesystem::path(buf);
-    }
+    export std::filesystem::path get_executable_path();
 
-    export std::pair<int, std::string> run_command_capture(const std::string& cmd) {
-        std::string full = cmd + " 2>&1";
-        FILE* pipe = ::_popen(full.c_str(), "r");
-        if (!pipe) {
-            return {-1, std::string{}};
-        }
-        std::string output;
-        std::array<char, 256> buffer{};
-        while (fgets(buffer.data(), buffer.size(), pipe) != nullptr) {
-            output += buffer.data();
-        }
-        int status = ::_pclose(pipe);
-        return {status, output};
-    }
+    export std::pair<int, std::string> run_command_capture(const std::string& cmd);
 
     // ─── Cancellable process management ───
 
@@ -112,184 +54,38 @@ namespace platform_impl {
         void* hReadPipe{nullptr};
     };
 
-    export auto spawn_command(const std::string& cmd) -> ProcessHandle {
-        SECURITY_ATTRIBUTES sa;
-        sa.nLength = sizeof(sa);
-        sa.bInheritHandle = TRUE;
-        sa.lpSecurityDescriptor = nullptr;
-
-        HANDLE hReadPipe, hWritePipe;
-        if (!::CreatePipe(&hReadPipe, &hWritePipe, &sa, 0)) {
-            return {};
-        }
-        ::SetHandleInformation(hReadPipe, HANDLE_FLAG_INHERIT, 0);
-
-        STARTUPINFOA si{};
-        si.cb = sizeof(si);
-        si.dwFlags = STARTF_USESTDHANDLES;
-        si.hStdOutput = hWritePipe;
-        si.hStdError = hWritePipe;
-
-        PROCESS_INFORMATION pi{};
-        std::string cmdline = "cmd /c " + cmd;
-
-        BOOL ok = ::CreateProcessA(
-            nullptr, cmdline.data(), nullptr, nullptr, TRUE,
-            CREATE_NEW_PROCESS_GROUP, nullptr, nullptr, &si, &pi);
-
-        ::CloseHandle(hWritePipe);
-
-        if (!ok) {
-            ::CloseHandle(hReadPipe);
-            return {};
-        }
-
-        ::CloseHandle(pi.hThread);
-
-        ProcessHandle h;
-        h.pid = static_cast<int>(pi.dwProcessId);
-        h.hProcess = pi.hProcess;
-        h.hReadPipe = hReadPipe;
-        return h;
-    }
+    export auto spawn_command(const std::string& cmd) -> ProcessHandle;
 
     export auto wait_or_kill(const ProcessHandle& h,
                              CancellationToken* cancel,
-                             std::chrono::milliseconds timeout) -> std::pair<int, std::string> {
-        if (!h.hProcess) return {-1, ""};
-
-        std::string output;
-        std::array<char, 4096> buf{};
-        auto deadline = std::chrono::steady_clock::now() + timeout;
-        HANDLE hProc = static_cast<HANDLE>(h.hProcess);
-        HANDLE hPipe = static_cast<HANDLE>(h.hReadPipe);
-
-        while (true) {
-            // Read available output
-            DWORD avail = 0;
-            while (::PeekNamedPipe(hPipe, nullptr, 0, nullptr, &avail, nullptr) && avail > 0) {
-                DWORD bytesRead = 0;
-                DWORD toRead = std::min(avail, static_cast<DWORD>(buf.size()));
-                if (::ReadFile(hPipe, buf.data(), toRead, &bytesRead, nullptr) && bytesRead > 0) {
-                    output.append(buf.data(), bytesRead);
-                } else break;
-            }
-
-            // Check if process exited
-            DWORD exitCode = 0;
-            if (::WaitForSingleObject(hProc, 0) == WAIT_OBJECT_0) {
-                // Read remaining
-                while (::PeekNamedPipe(hPipe, nullptr, 0, nullptr, &avail, nullptr) && avail > 0) {
-                    DWORD bytesRead = 0;
-                    DWORD toRead = std::min(avail, static_cast<DWORD>(buf.size()));
-                    if (::ReadFile(hPipe, buf.data(), toRead, &bytesRead, nullptr) && bytesRead > 0)
-                        output.append(buf.data(), bytesRead);
-                    else break;
-                }
-                ::GetExitCodeProcess(hProc, &exitCode);
-                ::CloseHandle(hPipe);
-                ::CloseHandle(hProc);
-                return {static_cast<int>(exitCode), output};
-            }
-
-            if (cancel && cancel->is_cancelled()) break;
-            if (std::chrono::steady_clock::now() >= deadline) break;
-
-            std::this_thread::sleep_for(std::chrono::milliseconds{100});
-        }
-
-        // Terminate: Ctrl+Break to process group, then hard kill after grace period
-        ::GenerateConsoleCtrlEvent(CTRL_BREAK_EVENT, static_cast<DWORD>(h.pid));
-        if (::WaitForSingleObject(hProc, 2000) != WAIT_OBJECT_0) {
-            ::TerminateProcess(hProc, 1);
-            ::WaitForSingleObject(hProc, 1000);
-        }
-        ::CloseHandle(hPipe);
-        ::CloseHandle(hProc);
-        return {-1, output};
-    }
+                             std::chrono::milliseconds timeout) -> std::pair<int, std::string>;
 
-    export void clear_console() {
-        std::system("cls");
-    }
+    export void clear_console();
 
-    export std::string get_home_dir() {
-        if (const char* home = std::getenv("USERPROFILE")) return home;
-        return ".";
-    }
+    export std::string get_home_dir();
 
-    export void set_env_variable(const std::string& key, const std::string& value) {
-        ::_putenv_s(key.c_str(), value.c_str());
-    }
+    export void set_env_variable(const std::string& key, const std::string& value);
 
-    export void make_files_executable(const std::filesystem::path&) {
-        // No-op: Windows does not use Unix file permissions
-    }
+    export void make_files_executable(const std::filesystem::path&);
 
     export bool create_directory_link(const std::filesystem::path& link,
-                                      const std::filesystem::path& target) {
-        std::error_code ec;
-        if (std::filesystem::is_symlink(link)) {
-            std::filesystem::remove(link, ec);
-        } else if (std::filesystem::exists(link)) {
-            std::filesystem::remove_all(link, ec);
-        }
-        auto canonTarget = std::filesystem::canonical(target, ec);
-        if (ec) canonTarget = target;
-        std::string cmd = "cmd /c mklink /J \"" + link.string() +
-                          "\" \"" + canonTarget.string() + "\" >nul 2>&1";
-        return std::system(cmd.c_str()) == 0;
-    }
+                                      const std::filesystem::path& target);
 
     // Enable UTF-8 code pages and VT processing for ANSI escape sequences.
     // Call once at program startup.
-    export void init_console_output() {
-        ::SetConsoleOutputCP(CP_UTF8);
-        ::SetConsoleCP(CP_UTF8);
-
-        // Both handles. Only stdout used to be switched into VT mode, but
-        // `log::warn` and `log::error` write to stderr — so on a console
-        // their SGR was emitted to a handle that does not interpret it, and
-        // the user read the escape bytes instead of a colored `[warn]`.
-        for (DWORD which : { STD_OUTPUT_HANDLE, STD_ERROR_HANDLE }) {
-            HANDLE h = ::GetStdHandle(which);
-            if (h == INVALID_HANDLE_VALUE) continue;
-            DWORD mode = 0;
-            if (::GetConsoleMode(h, &mode)) {
-                mode |= ENABLE_VIRTUAL_TERMINAL_PROCESSING;
-                ::SetConsoleMode(h, mode);
-            }
-        }
-    }
+    export void init_console_output();
 
     // Check if stdout supports cursor save/restore for in-place rewriting.
-    export bool supports_rewrite_output() {
-        HANDLE hOut = ::GetStdHandle(STD_OUTPUT_HANDLE);
-        if (hOut == INVALID_HANDLE_VALUE) return false;
-        DWORD mode = 0;
-        if (!::GetConsoleMode(hOut, &mode)) return false;
-        return (mode & ENABLE_VIRTUAL_TERMINAL_PROCESSING) != 0;
-    }
+    export bool supports_rewrite_output();
 
     // Check if stderr is a console. Separate from stdout because warnings
     // and errors go to stderr: `xlings install > log` still has an
     // interactive stderr, and `2>&1 | cat` has neither.
-    export bool stderr_is_terminal() {
-        HANDLE hErr = ::GetStdHandle(STD_ERROR_HANDLE);
-        if (hErr == INVALID_HANDLE_VALUE) return false;
-        DWORD mode = 0;
-        if (!::GetConsoleMode(hErr, &mode)) return false;
-        return (mode & ENABLE_VIRTUAL_TERMINAL_PROCESSING) != 0;
-    }
+    export bool stderr_is_terminal();
 
     // Check if stdin is a console — i.e. whether there is someone there to
     // answer an interactive prompt.
-    export bool stdin_is_terminal() {
-        HANDLE hIn = ::GetStdHandle(STD_INPUT_HANDLE);
-        if (hIn == INVALID_HANDLE_VALUE) return false;
-        DWORD mode = 0;
-        return ::GetConsoleMode(hIn, &mode) != 0;
-    }
+    export bool stdin_is_terminal();
 
     export template<typename... Args>
     void println(std::format_string<Args...> fmt, Args&&... args) {
@@ -297,44 +93,27 @@ namespace platform_impl {
     }
 
     export inline void println(const std::string& msg) {
-        std::println("{}", msg);
+        std::println(stdout, "{}", msg);
     }
 
-    export int get_pid() {
-        return static_cast<int>(::GetCurrentProcessId());
-    }
+    export int get_pid();
 
-    export bool is_process_alive(int pid) {
-        if (pid <= 0) return false;
-        HANDLE hProcess = ::OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, FALSE, static_cast<DWORD>(pid));
-        if (hProcess == NULL) return false;
-        DWORD exitCode = 0;
-        bool alive = ::GetExitCodeProcess(hProcess, &exitCode) && exitCode == STILL_ACTIVE;
-        ::CloseHandle(hProcess);
-        return alive;
-    }
+    export bool is_process_alive(int pid);
 
     // OSC-11 background-color query is a POSIX-tty trick (open /dev/tty,
     // termios raw mode, blocking read with timeout). Windows conhost +
     // legacy terminals don't have a clean equivalent, so we don't try.
     // Modern Windows Terminal users can still set XLINGS_THEME explicitly,
     // and the COLORFGBG fallback in ui::theme is platform-agnostic.
-    export std::optional<bool> query_terminal_is_light() {
-        return std::nullopt;
-    }
+    export std::optional<bool> query_terminal_is_light();
 
     // ── Execution identity primitives (no POSIX uid/sudo model) ─────
     // Windows has no euid/sudo concept; these stubs keep the
     // cross-platform identity API in platform.cppm compiling and inert.
-    export bool is_root() {
-        return false;
-    }
+    export bool is_root();
     export void lchown_path_(const std::filesystem::path&,
-                             unsigned int, unsigned int) {
-    }
-    export std::string home_for_user_(const std::string&) {
-        return {};
-    }
+                             unsigned int, unsigned int);
+    export std::string home_for_user_(const std::string&);
 
 
     // Atomically replace `dst` with the contents of `src`, even when `dst`
@@ -354,58 +133,7 @@ namespace platform_impl {
     //
     // Returns true on success.
     export bool atomic_replace_executable(const std::filesystem::path& src,
-                                          const std::filesystem::path& dst) {
-        namespace fs = std::filesystem;
-        std::error_code ec;
-
-        if (!fs::exists(src, ec) || ec) return false;
-
-        fs::create_directories(dst.parent_path(), ec);
-        ec.clear();
-
-        // Easy case: dst doesn't exist yet — just copy.
-        if (!fs::exists(dst, ec)) {
-            fs::copy_file(src, dst, fs::copy_options::overwrite_existing, ec);
-            return !ec;
-        }
-        ec.clear();
-
-        auto old_path = dst;
-        old_path += ".xlings.old";
-
-        // Best-effort cleanup of a leftover .old (may fail if still locked).
-        if (fs::exists(old_path, ec)) {
-            ::DeleteFileW(old_path.wstring().c_str());
-            ec.clear();
-        }
-
-        // Step 1: rename live binary out of the way (works even if running).
-        if (!::MoveFileExW(dst.wstring().c_str(),
-                           old_path.wstring().c_str(),
-                           MOVEFILE_REPLACE_EXISTING)) {
-            return false;
-        }
-
-        // Step 2: copy new binary into the now-free dst path.
-        fs::copy_file(src, dst, fs::copy_options::overwrite_existing, ec);
-        if (ec) {
-            // Try to restore old binary so we don't leave the user broken.
-            ::MoveFileExW(old_path.wstring().c_str(),
-                          dst.wstring().c_str(),
-                          MOVEFILE_REPLACE_EXISTING);
-            return false;
-        }
-
-        // Step 3: best-effort cleanup. If the .old file is still locked
-        // (because the running process is mapping it), schedule for
-        // deletion at next reboot.
-        if (!::DeleteFileW(old_path.wstring().c_str())) {
-            ::MoveFileExW(old_path.wstring().c_str(), nullptr,
-                          MOVEFILE_DELAY_UNTIL_REBOOT);
-        }
-
-        return true;
-    }
+                                          const std::filesystem::path& dst);
 
     // Free a path that another process may be holding open, so something new
     // can be written there.
@@ -419,50 +147,13 @@ namespace platform_impl {
     // process" (issue #473).
     //
     // Returns true when the path is free afterwards.
-    export bool displace_locked_file(const std::filesystem::path& path) {
-        namespace fs = std::filesystem;
-        std::error_code ec;
-        if (!fs::exists(path, ec) && !fs::is_symlink(path, ec)) return true;
-        ec.clear();
-
-        fs::remove(path, ec);
-        if (!ec && !fs::exists(path, ec)) return true;
-        ec.clear();
-
-        // Still there: it is open somewhere. Rename it aside. A distinct
-        // suffix per attempt so a home that has been updated repeatedly, with
-        // earlier casualties still mapped, does not collide with itself.
-        for (int attempt = 0; attempt < 16; ++attempt) {
-            auto aside = path;
-            aside += attempt == 0
-                ? std::string(".xlings.old")
-                : ".xlings.old" + std::to_string(attempt);
-            if (fs::exists(aside, ec)) {
-                ec.clear();
-                if (!::DeleteFileW(aside.wstring().c_str())) continue;
-            }
-            ec.clear();
-            if (::MoveFileExW(path.wstring().c_str(), aside.wstring().c_str(),
-                              MOVEFILE_REPLACE_EXISTING)) {
-                // The displaced copy is still mapped by the running process,
-                // so it cannot be deleted now. Let the OS drop it at reboot
-                // rather than leaving it to accumulate forever.
-                ::MoveFileExW(aside.wstring().c_str(), nullptr,
-                              MOVEFILE_DELAY_UNTIL_REBOOT);
-                return true;
-            }
-        }
-        return false;
-    }
+    export bool displace_locked_file(const std::filesystem::path& path);
 
     // Windows has no single-call directory swap; report unsupported so the
     // caller uses its portable manual-swap fallback. (Symmetry with the POSIX
     // atomic_swap_paths used by the index-artifact installer.)
     export bool atomic_swap_paths(const std::filesystem::path& a,
-                                  const std::filesystem::path& b) {
-        (void)a; (void)b;
-        return false;
-    }
+                                  const std::filesystem::path& b);
 
 } // namespace platform_impl
 }
diff --git a/src/runtime/cancellation.cpp b/src/runtime/cancellation.cpp
new file mode 100644
index 00000000..b93ac28f
--- /dev/null
+++ b/src/runtime/cancellation.cpp
@@ -0,0 +1,51 @@
+module xlings.runtime.cancellation;
+
+import std;
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings {
+
+CancelledException::CancelledException() : std::runtime_error("operation cancelled") {}
+
+PausedException::PausedException() : std::runtime_error("operation paused") {}
+
+void CancellationToken::pause() {
+    state_.store(1, std::memory_order_release);
+    cv_.notify_all();
+}
+
+void CancellationToken::resume() {
+    state_.store(0, std::memory_order_release);
+    cv_.notify_all();
+}
+
+void CancellationToken::cancel() {
+    state_.store(2, std::memory_order_release);
+    cv_.notify_all();
+}
+
+void CancellationToken::reset() {
+    state_.store(0, std::memory_order_release);
+}
+
+bool CancellationToken::is_active() const {
+    return state_.load(std::memory_order_acquire) == 0;
+}
+
+bool CancellationToken::is_paused() const {
+    return state_.load(std::memory_order_acquire) == 1;
+}
+
+bool CancellationToken::is_cancelled() const {
+    return state_.load(std::memory_order_acquire) == 2;
+}
+
+void CancellationToken::throw_if_cancelled() {
+    auto s = state_.load(std::memory_order_acquire);
+    if (s == 2) throw CancelledException{};
+    if (s == 1) throw PausedException{};
+}
+
+} // namespace xlings
diff --git a/src/runtime/cancellation.cppm b/src/runtime/cancellation.cppm
index e5e4a8c3..b57cd70d 100644
--- a/src/runtime/cancellation.cppm
+++ b/src/runtime/cancellation.cppm
@@ -5,11 +5,11 @@ import std;
 namespace xlings {
 
 export struct CancelledException : std::runtime_error {
-    CancelledException() : std::runtime_error("operation cancelled") {}
+    CancelledException();
 };
 
 export struct PausedException : std::runtime_error {
-    PausedException() : std::runtime_error("operation paused") {}
+    PausedException();
 };
 
 // State: 0=Active, 1=Paused, 2=Cancelled
@@ -20,42 +20,21 @@ export class CancellationToken {
     std::condition_variable cv_;
 
 public:
-    void pause() {
-        state_.store(1, std::memory_order_release);
-        cv_.notify_all();
-    }
+    void pause();
 
-    void resume() {
-        state_.store(0, std::memory_order_release);
-        cv_.notify_all();
-    }
+    void resume();
 
-    void cancel() {
-        state_.store(2, std::memory_order_release);
-        cv_.notify_all();
-    }
+    void cancel();
 
-    void reset() {
-        state_.store(0, std::memory_order_release);
-    }
+    void reset();
 
-    bool is_active() const {
-        return state_.load(std::memory_order_acquire) == 0;
-    }
+    bool is_active() const;
 
-    bool is_paused() const {
-        return state_.load(std::memory_order_acquire) == 1;
-    }
+    bool is_paused() const;
 
-    bool is_cancelled() const {
-        return state_.load(std::memory_order_acquire) == 2;
-    }
+    bool is_cancelled() const;
 
-    void throw_if_cancelled() {
-        auto s = state_.load(std::memory_order_acquire);
-        if (s == 2) throw CancelledException{};
-        if (s == 1) throw PausedException{};
-    }
+    void throw_if_cancelled();
 
     // Wait on a condition variable while also checking for cancellation/pause and timeout.
     // Returns true if predicate was satisfied, false if cancelled/paused or timed out.
diff --git a/src/runtime/capability.cpp b/src/runtime/capability.cpp
new file mode 100644
index 00000000..90fe84a3
--- /dev/null
+++ b/src/runtime/capability.cpp
@@ -0,0 +1,36 @@
+module xlings.runtime.capability;
+
+import std;
+import xlings.runtime.event;
+import xlings.runtime.event_stream;
+import xlings.runtime.cancellation;
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::capability {
+
+auto Capability::execute(Params params, EventStream& stream, CancellationToken* cancel) -> Result {
+    return execute(std::move(params), stream);
+}
+
+void Registry::register_capability(std::unique_ptr<Capability> cap) {
+    auto name = cap->spec().name;
+    capabilities_[std::move(name)] = std::move(cap);
+}
+
+auto Registry::get(std::string_view name) -> Capability* {
+    auto it = capabilities_.find(std::string(name));
+    return it != capabilities_.end() ? it->second.get() : nullptr;
+}
+
+auto Registry::list_all() -> std::vector<CapabilitySpec> {
+    std::vector<CapabilitySpec> specs;
+    specs.reserve(capabilities_.size());
+    for (auto& [_, cap] : capabilities_) {
+        specs.push_back(cap->spec());
+    }
+    return specs;
+}
+
+} // namespace xlings::capability
diff --git a/src/runtime/capability.cppm b/src/runtime/capability.cppm
index 4f69bba5..0deb71dc 100644
--- a/src/runtime/capability.cppm
+++ b/src/runtime/capability.cppm
@@ -2,7 +2,6 @@ export module xlings.runtime.capability;
 
 import std;
 
-import xlings.runtime.event;
 import xlings.runtime.event_stream;
 import xlings.runtime.cancellation;
 
@@ -25,9 +24,7 @@ export struct Capability {
     virtual auto spec() const -> CapabilitySpec = 0;
     virtual auto execute(Params params, EventStream& stream) -> Result = 0;
     // Cancellable variant — default delegates to 2-arg version; override for cancel support
-    virtual auto execute(Params params, EventStream& stream, CancellationToken* cancel) -> Result {
-        return execute(std::move(params), stream);
-    }
+    virtual auto execute(Params params, EventStream& stream, CancellationToken* cancel) -> Result;
 };
 
 export class Registry {
@@ -35,24 +32,11 @@ private:
     std::unordered_map<std::string, std::unique_ptr<Capability>> capabilities_;
 
 public:
-    void register_capability(std::unique_ptr<Capability> cap) {
-        auto name = cap->spec().name;
-        capabilities_[std::move(name)] = std::move(cap);
-    }
-
-    auto get(std::string_view name) -> Capability* {
-        auto it = capabilities_.find(std::string(name));
-        return it != capabilities_.end() ? it->second.get() : nullptr;
-    }
-
-    auto list_all() -> std::vector<CapabilitySpec> {
-        std::vector<CapabilitySpec> specs;
-        specs.reserve(capabilities_.size());
-        for (auto& [_, cap] : capabilities_) {
-            specs.push_back(cap->spec());
-        }
-        return specs;
-    }
+    void register_capability(std::unique_ptr<Capability> cap);
+
+    auto get(std::string_view name) -> Capability*;
+
+    auto list_all() -> std::vector<CapabilitySpec>;
 };
 
 }  // namespace xlings::capability
diff --git a/src/runtime/event_stream.cpp b/src/runtime/event_stream.cpp
new file mode 100644
index 00000000..44b0fb0d
--- /dev/null
+++ b/src/runtime/event_stream.cpp
@@ -0,0 +1,92 @@
+module xlings.runtime.event_stream;
+
+import std;
+import xlings.runtime.event;
+import xlings.runtime.cancellation;
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings {
+
+auto EventStream::on_event(EventConsumer consumer) -> int {
+    int id = next_id_++;
+    consumers_.push_back({id, std::move(consumer), true});
+    return id;
+}
+
+void EventStream::remove_listener(int id) {
+    std::erase_if(consumers_, [id](const ListenerEntry& e) { return e.id == id; });
+}
+
+void EventStream::set_enabled(int id, bool enabled) {
+    for (auto& entry : consumers_) {
+        if (entry.id == id) {
+            entry.enabled = enabled;
+            return;
+        }
+    }
+}
+
+void EventStream::emit(Event event) {
+    for (auto& entry : consumers_) {
+        if (entry.enabled) entry.consumer(event);
+    }
+}
+
+void EventStream::register_auto_responder(std::string prompt_id_prefix, AutoResponder fn) {
+    auto_responders_.emplace_back(std::move(prompt_id_prefix), std::move(fn));
+}
+
+void EventStream::clear_auto_responders() {
+    auto_responders_.clear();
+}
+
+auto EventStream::prompt(PromptEvent req, CancellationToken* cancel, std::chrono::milliseconds timeout) -> std::string {
+    auto id = req.id;
+
+    // Check auto-responders first (by prefix match)
+    for (auto& [prefix, responder] : auto_responders_) {
+        if (id.starts_with(prefix)) {
+            return responder(req);
+        }
+    }
+
+    emit(Event{std::move(req)});
+
+    std::unique_lock lock(promptMutex_);
+
+    if (cancel) {
+        bool satisfied = cancel->wait_or_cancel(lock, promptCv_,
+            [&] { return promptResponses_.contains(id); }, timeout);
+        if (!satisfied) {
+            // Cancelled or timed out — clean up any stale entry
+            promptResponses_.erase(id);
+            return "";
+        }
+    } else {
+        promptCv_.wait(lock, [&] {
+            return promptResponses_.contains(id);
+        });
+    }
+
+    auto response = std::move(promptResponses_[id]);
+    promptResponses_.erase(id);
+    return response;
+}
+
+void EventStream::respond(std::string_view promptId, std::string_view response) {
+    {
+        std::lock_guard lock(promptMutex_);
+        promptResponses_[std::string(promptId)] = std::string(response);
+    }
+    promptCv_.notify_all();
+}
+
+void EventStream::cancel_all_prompts() {
+    std::lock_guard lock(promptMutex_);
+    promptResponses_.clear();
+    promptCv_.notify_all();
+}
+
+} // namespace xlings
diff --git a/src/runtime/event_stream.cppm b/src/runtime/event_stream.cppm
index 59ad195b..e6153f76 100644
--- a/src/runtime/event_stream.cppm
+++ b/src/runtime/event_stream.cppm
@@ -39,92 +39,30 @@ public:
 
     // Thread safety: register all consumers before emitting from other threads.
     // on_event() and emit() are not synchronized — call on_event() during setup only.
-    auto on_event(EventConsumer consumer) -> int {
-        int id = next_id_++;
-        consumers_.push_back({id, std::move(consumer), true});
-        return id;
-    }
-
-    void remove_listener(int id) {
-        std::erase_if(consumers_, [id](const ListenerEntry& e) { return e.id == id; });
-    }
-
-    void set_enabled(int id, bool enabled) {
-        for (auto& entry : consumers_) {
-            if (entry.id == id) {
-                entry.enabled = enabled;
-                return;
-            }
-        }
-    }
-
-    void emit(Event event) {
-        for (auto& entry : consumers_) {
-            if (entry.enabled) entry.consumer(event);
-        }
-    }
+    auto on_event(EventConsumer consumer) -> int;
+
+    void remove_listener(int id);
+
+    void set_enabled(int id, bool enabled);
+
+    void emit(Event event);
 
     // Register an auto-responder for prompts whose id starts with the given prefix.
     // In agent mode, this allows automatic responses to install confirmations, etc.
-    void register_auto_responder(std::string prompt_id_prefix, AutoResponder fn) {
-        auto_responders_.emplace_back(std::move(prompt_id_prefix), std::move(fn));
-    }
+    void register_auto_responder(std::string prompt_id_prefix, AutoResponder fn);
 
-    void clear_auto_responders() {
-        auto_responders_.clear();
-    }
+    void clear_auto_responders();
 
     // Prompt with optional cancellation and timeout support.
     // Returns empty string on cancel/timeout.
     auto prompt(PromptEvent req,
                 CancellationToken* cancel = nullptr,
-                std::chrono::milliseconds timeout = std::chrono::milliseconds{30000}) -> std::string {
-        auto id = req.id;
-
-        // Check auto-responders first (by prefix match)
-        for (auto& [prefix, responder] : auto_responders_) {
-            if (id.starts_with(prefix)) {
-                return responder(req);
-            }
-        }
-
-        emit(Event{std::move(req)});
-
-        std::unique_lock lock(promptMutex_);
-
-        if (cancel) {
-            bool satisfied = cancel->wait_or_cancel(lock, promptCv_,
-                [&] { return promptResponses_.contains(id); }, timeout);
-            if (!satisfied) {
-                // Cancelled or timed out — clean up any stale entry
-                promptResponses_.erase(id);
-                return "";
-            }
-        } else {
-            promptCv_.wait(lock, [&] {
-                return promptResponses_.contains(id);
-            });
-        }
-
-        auto response = std::move(promptResponses_[id]);
-        promptResponses_.erase(id);
-        return response;
-    }
-
-    void respond(std::string_view promptId, std::string_view response) {
-        {
-            std::lock_guard lock(promptMutex_);
-            promptResponses_[std::string(promptId)] = std::string(response);
-        }
-        promptCv_.notify_all();
-    }
+                std::chrono::milliseconds timeout = std::chrono::milliseconds{30000}) -> std::string;
+
+    void respond(std::string_view promptId, std::string_view response);
 
     // Cancel all pending prompts (call from ESC handler)
-    void cancel_all_prompts() {
-        std::lock_guard lock(promptMutex_);
-        promptResponses_.clear();
-        promptCv_.notify_all();
-    }
+    void cancel_all_prompts();
 };
 
 }  // namespace xlings
diff --git a/src/runtime/task.cpp b/src/runtime/task.cpp
new file mode 100644
index 00000000..02a9179c
--- /dev/null
+++ b/src/runtime/task.cpp
@@ -0,0 +1,159 @@
+module xlings.runtime.task;
+
+import std;
+import xlings.runtime.event;
+import xlings.runtime.event_stream;
+import xlings.runtime.capability;
+
+
+// ── out-of-line class members ──────────────────────────────────
+
+namespace xlings::task {
+
+auto TaskManager::generate_id_() -> TaskId {
+    return "task_" + std::to_string(nextId_.fetch_add(1));
+}
+
+TaskManager::TaskManager(capability::Registry& registry) : registry_ { registry } {}
+
+TaskManager::~TaskManager() {
+    for (auto& [_, state] : tasks_) {
+        if (state->thread.joinable()) {
+            state->thread.join();
+        }
+    }
+}
+
+auto TaskManager::submit(std::string_view capabilityName, capability::Params params) -> TaskId {
+    auto* cap = registry_.get(capabilityName);
+    if (!cap) return "";
+
+    auto id = generate_id_();
+    auto state = std::make_shared<TaskState>();
+    state->id = id;
+    state->capabilityName = std::string(capabilityName);
+    state->status.store(TaskStatus::pending);
+
+    // Register event consumer: buffer events + track state
+    state->stream.on_event([s = state.get()](const Event& e) {
+        {
+            std::lock_guard lock(s->bufferMutex);
+            s->eventBuffer.push_back(EventRecord{
+                .index = s->eventBuffer.size(),
+                .event = e
+            });
+        }
+
+        if (auto* p = std::get_if<ProgressEvent>(&e)) {
+            s->progressPct.store(p->percent);
+            std::lock_guard phaseLock(s->bufferMutex);
+            s->currentPhase = p->message;
+        }
+        if (std::holds_alternative<PromptEvent>(e)) {
+            std::lock_guard lock(s->bufferMutex);
+            s->pendingPromptCount++;
+            s->status.store(TaskStatus::waiting_prompt);
+        }
+    });
+
+    auto paramsCopy = std::string(params);
+    state->thread = std::thread([cap, paramsCopy, s = state]() {
+        s->status.store(TaskStatus::running);
+        try {
+            cap->execute(paramsCopy, s->stream);
+            s->status.store(TaskStatus::completed);
+        } catch (...) {
+            s->status.store(TaskStatus::failed);
+        }
+    });
+
+    std::lock_guard lock(tasksMutex_);
+    tasks_[id] = std::move(state);
+    return id;
+}
+
+void TaskManager::cancel(TaskId id) {
+    std::lock_guard lock(tasksMutex_);
+    auto it = tasks_.find(id);
+    if (it != tasks_.end()) {
+        it->second->status.store(TaskStatus::cancelled);
+    }
+}
+
+auto TaskManager::info(TaskId id) -> TaskInfo {
+    std::lock_guard lock(tasksMutex_);
+    auto it = tasks_.find(id);
+    if (it == tasks_.end()) return {};
+    auto& s = it->second;
+    std::lock_guard bufLock(s->bufferMutex);
+    return TaskInfo {
+        .id = s->id,
+        .capabilityName = s->capabilityName,
+        .status = s->status.load(),
+        .progressPct = s->progressPct.load(),
+        .currentPhase = s->currentPhase,
+        .eventCount = s->eventBuffer.size(),
+        .pendingPromptCount = s->pendingPromptCount
+    };
+}
+
+auto TaskManager::info_all() -> std::vector<TaskInfo> {
+    std::vector<TaskInfo> result;
+    std::lock_guard lock(tasksMutex_);
+    for (auto& [id, s] : tasks_) {
+        std::lock_guard bufLock(s->bufferMutex);
+        result.push_back(TaskInfo {
+            .id = s->id,
+            .capabilityName = s->capabilityName,
+            .status = s->status.load(),
+            .progressPct = s->progressPct.load(),
+            .currentPhase = s->currentPhase,
+            .eventCount = s->eventBuffer.size(),
+            .pendingPromptCount = s->pendingPromptCount
+        });
+    }
+    return result;
+}
+
+bool TaskManager::has_active_tasks() const {
+    std::lock_guard lock(tasksMutex_);
+    for (auto& [_, s] : tasks_) {
+        auto st = s->status.load();
+        if (st == TaskStatus::pending || st == TaskStatus::running
+            || st == TaskStatus::waiting_prompt) {
+            return true;
+        }
+    }
+    return false;
+}
+
+auto TaskManager::events(TaskId id, std::size_t sinceIndex) -> std::vector<EventRecord> {
+    std::lock_guard lock(tasksMutex_);
+    auto it = tasks_.find(id);
+    if (it == tasks_.end()) return {};
+    auto& s = it->second;
+    std::lock_guard bufLock(s->bufferMutex);
+    if (sinceIndex >= s->eventBuffer.size()) return {};
+    return {s->eventBuffer.begin() + sinceIndex, s->eventBuffer.end()};
+}
+
+void TaskManager::respond(TaskId taskId, std::string_view promptId, std::string_view response) {
+    std::lock_guard lock(tasksMutex_);
+    auto it = tasks_.find(taskId);
+    if (it == tasks_.end()) return;
+    auto& s = it->second;
+    {
+        std::lock_guard bufLock(s->bufferMutex);
+        if (s->pendingPromptCount > 0) s->pendingPromptCount--;
+    }
+    s->stream.respond(promptId, response);
+    {
+        std::lock_guard bufLock(s->bufferMutex);
+        if (s->pendingPromptCount == 0
+            && s->status.load() == TaskStatus::waiting_prompt) {
+            s->status.store(TaskStatus::running);
+        }
+    }
+}
+
+} // namespace xlings::task
diff --git a/src/runtime/task.cppm b/src/runtime/task.cppm
index a538b6b6..2fd50441 100644
--- a/src/runtime/task.cppm
+++ b/src/runtime/task.cppm
@@ -56,153 +56,26 @@ private:
     mutable std::mutex tasksMutex_;
     std::atomic<int> nextId_ { 1 };
 
-    auto generate_id_() -> TaskId {
-        return "task_" + std::to_string(nextId_.fetch_add(1));
-    }
+    auto generate_id_() -> TaskId;
 
 public:
-    explicit TaskManager(capability::Registry& registry)
-        : registry_ { registry } {}
-
-    ~TaskManager() {
-        for (auto& [_, state] : tasks_) {
-            if (state->thread.joinable()) {
-                state->thread.join();
-            }
-        }
-    }
-
-    auto submit(std::string_view capabilityName, capability::Params params) -> TaskId {
-        auto* cap = registry_.get(capabilityName);
-        if (!cap) return "";
-
-        auto id = generate_id_();
-        auto state = std::make_shared<TaskState>();
-        state->id = id;
-        state->capabilityName = std::string(capabilityName);
-        state->status.store(TaskStatus::pending);
-
-        // Register event consumer: buffer events + track state
-        state->stream.on_event([s = state.get()](const Event& e) {
-            {
-                std::lock_guard lock(s->bufferMutex);
-                s->eventBuffer.push_back(EventRecord{
-                    .index = s->eventBuffer.size(),
-                    .event = e
-                });
-            }
-
-            if (auto* p = std::get_if<ProgressEvent>(&e)) {
-                s->progressPct.store(p->percent);
-                std::lock_guard phaseLock(s->bufferMutex);
-                s->currentPhase = p->message;
-            }
-            if (std::holds_alternative<PromptEvent>(e)) {
-                std::lock_guard lock(s->bufferMutex);
-                s->pendingPromptCount++;
-                s->status.store(TaskStatus::waiting_prompt);
-            }
-        });
-
-        auto paramsCopy = std::string(params);
-        state->thread = std::thread([cap, paramsCopy, s = state]() {
-            s->status.store(TaskStatus::running);
-            try {
-                cap->execute(paramsCopy, s->stream);
-                s->status.store(TaskStatus::completed);
-            } catch (...) {
-                s->status.store(TaskStatus::failed);
-            }
-        });
-
-        std::lock_guard lock(tasksMutex_);
-        tasks_[id] = std::move(state);
-        return id;
-    }
-
-    void cancel(TaskId id) {
-        std::lock_guard lock(tasksMutex_);
-        auto it = tasks_.find(id);
-        if (it != tasks_.end()) {
-            it->second->status.store(TaskStatus::cancelled);
-        }
-    }
-
-    auto info(TaskId id) -> TaskInfo {
-        std::lock_guard lock(tasksMutex_);
-        auto it = tasks_.find(id);
-        if (it == tasks_.end()) return {};
-        auto& s = it->second;
-        std::lock_guard bufLock(s->bufferMutex);
-        return TaskInfo {
-            .id = s->id,
-            .capabilityName = s->capabilityName,
-            .status = s->status.load(),
-            .progressPct = s->progressPct.load(),
-            .currentPhase = s->currentPhase,
-            .eventCount = s->eventBuffer.size(),
-            .pendingPromptCount = s->pendingPromptCount
-        };
-    }
-
-    auto info_all() -> std::vector<TaskInfo> {
-        std::vector<TaskInfo> result;
-        std::lock_guard lock(tasksMutex_);
-        for (auto& [id, s] : tasks_) {
-            std::lock_guard bufLock(s->bufferMutex);
-            result.push_back(TaskInfo {
-                .id = s->id,
-                .capabilityName = s->capabilityName,
-                .status = s->status.load(),
-                .progressPct = s->progressPct.load(),
-                .currentPhase = s->currentPhase,
-                .eventCount = s->eventBuffer.size(),
-                .pendingPromptCount = s->pendingPromptCount
-            });
-        }
-        return result;
-    }
-
-    bool has_active_tasks() const {
-        std::lock_guard lock(tasksMutex_);
-        for (auto& [_, s] : tasks_) {
-            auto st = s->status.load();
-            if (st == TaskStatus::pending || st == TaskStatus::running
-                || st == TaskStatus::waiting_prompt) {
-                return true;
-            }
-        }
-        return false;
-    }
-
-    auto events(TaskId id, std::size_t sinceIndex = 0) -> std::vector<EventRecord> {
-        std::lock_guard lock(tasksMutex_);
-        auto it = tasks_.find(id);
-        if (it == tasks_.end()) return {};
-        auto& s = it->second;
-        std::lock_guard bufLock(s->bufferMutex);
-        if (sinceIndex >= s->eventBuffer.size()) return {};
-        return {s->eventBuffer.begin() + sinceIndex, s->eventBuffer.end()};
-    }
-
-    void respond(TaskId taskId, std::string_view promptId, std::string_view response) {
-        std::lock_guard lock(tasksMutex_);
-        auto it = tasks_.find(taskId);
-        if (it == tasks_.end()) return;
-        auto& s = it->second;
-        {
-            std::lock_guard bufLock(s->bufferMutex);
-            if (s->pendingPromptCount > 0) s->pendingPromptCount--;
-        }
-        s->stream.respond(promptId, response);
-        {
-            std::lock_guard bufLock(s->bufferMutex);
-            if (s->pendingPromptCount == 0
-                && s->status.load() == TaskStatus::waiting_prompt) {
-                s->status.store(TaskStatus::running);
-            }
-        }
-    }
+    explicit TaskManager(capability::Registry& registry);
+
+    ~TaskManager();
+
+    auto submit(std::string_view capabilityName, capability::Params params) -> TaskId;
+
+    void cancel(TaskId id);
+
+    auto info(TaskId id) -> TaskInfo;
+
+    auto info_all() -> std::vector<TaskInfo>;
+
+    bool has_active_tasks() const;
+
+    auto events(TaskId id, std::size_t sinceIndex = 0) -> std::vector<EventRecord>;
+
+    void respond(TaskId taskId, std::string_view promptId, std::string_view response);
 };
 
 }  // namespace xlings::task
diff --git a/src/ui/banner.cpp b/src/ui/banner.cpp
new file mode 100644
index 00000000..dd32628a
--- /dev/null
+++ b/src/ui/banner.cpp
@@ -0,0 +1,235 @@
+module;
+
+#include "ftxui/dom/elements.hpp"
+#include "ftxui/screen/screen.hpp"
+#include "ftxui/screen/color.hpp"
+
+module xlings.ui;
+
+import std;
+
+namespace xlings::ui {
+
+void help_section_(ftxui::Elements& rows, std::string_view heading,
+                   std::span<const std::pair<std::string, std::string>> entries,
+                   const layout::ColumnPlan& P, ftxui::Decorator nameStyle) {
+    using namespace ftxui;
+    if (entries.empty()) return;
+
+    rows.push_back(text("  " + std::string(heading)) | bold | color(theme::text_color()));
+    for (auto& [name, desc] : entries) {
+        if (P.stacked) {
+            for (auto& part : layout::wrap_to_width(
+                     name, std::max(1, P.width - kHelpIndent))) {
+                rows.push_back(text(std::string(kHelpIndent, ' ') + part) | nameStyle);
+            }
+            if (P.descW > 0 && !desc.empty()) {
+                rows.push_back(text(std::string(kHelpIndent + kHelpGap, ' ')
+                                    + layout::truncate_to_width(desc, P.descW))
+                               | color(theme::text_color()));
+            }
+            continue;
+        }
+        Elements cells;
+        cells.push_back(text(std::string(kHelpIndent, ' ')));
+        cells.push_back(text(layout::pad_to_width(name, P.nameW)) | nameStyle);
+        if (P.descW > 0 && !desc.empty()) {
+            cells.push_back(text(std::string(kHelpGap, ' ')));
+            cells.push_back(text(layout::truncate_to_width(desc, P.descW))
+                            | color(theme::text_color()));
+        }
+        rows.push_back(hbox(std::move(cells)));
+    }
+    rows.push_back(text(""));
+}
+
+layout::ColumnPlan plan_help_(
+        std::span<const std::span<const std::pair<std::string, std::string>>> sections,
+        int titleW) {
+    int nameMax = 0, descMax = 0;
+    for (auto& sec : sections) {
+        for (auto& [name, desc] : sec) {
+            nameMax = std::max(nameMax, layout::display_width(name));
+            descMax = std::max(descMax, layout::display_width(desc));
+        }
+    }
+    return layout::plan_two_column(kHelpIndent, kHelpGap, nameMax, descMax, titleW);
+}
+
+void print_subcommand_help(std::string_view name, std::string_view description, std::span<const HelpArg> args, std::span<const HelpOpt> opts, std::span<const HelpOpt> subcmds) {
+    using namespace ftxui;
+
+    using Pair = std::pair<std::string, std::string>;
+
+    std::vector<Pair> subEntries;
+    for (auto& s : subcmds) subEntries.emplace_back(s.flag, s.desc);
+
+    std::vector<Pair> argEntries;
+    for (auto& a : args) {
+        if (a.desc.empty()) continue;
+        argEntries.emplace_back("<" + a.name + ">", a.desc);
+    }
+
+    std::vector<Pair> optEntries;
+    for (auto& o : opts) optEntries.emplace_back(o.flag, o.desc);
+
+    std::string usage = "    xlings " + std::string(name);
+    if (!subcmds.empty()) usage += " [SUBCOMMAND]";
+    if (!opts.empty()) usage += " [OPTIONS]";
+    for (auto& a : args) {
+        usage += a.required ? " <" + a.name + ">" : " [" + a.name + "]";
+    }
+
+    std::span<const Pair> sections[] = { subEntries, argEntries, optEntries };
+    auto P = plan_help_(sections,
+                        std::max({ layout::display_width(usage) + 2,
+                                   layout::display_width(description) + 4,
+                                   40 }));
+
+    Elements rows;
+    rows.push_back(text(""));
+
+    // Title
+    rows.push_back(hbox({
+        text("  xlings ") | color(theme::dim_color()),
+        text(std::string(name)) | theme::title(),
+    }));
+    rows.push_back(text(""));
+
+    // Description
+    if (!description.empty()) {
+        for (auto& line : layout::wrap_to_width(description, std::max(1, P.width - 2))) {
+            rows.push_back(text("  " + line) | color(theme::text_color()));
+        }
+        rows.push_back(text(""));
+    }
+
+    // USAGE
+    rows.push_back(text("  USAGE") | bold | color(theme::text_color()));
+    rows.push_back(text(usage) | color(theme::dim_color()));
+    rows.push_back(text(""));
+
+    help_section_(rows, "SUBCOMMANDS", subEntries, P,
+                  bold | color(theme::magenta()));
+    help_section_(rows, "ARGS", argEntries, P,
+                  bold | color(theme::magenta()));
+    help_section_(rows, "OPTIONS", optEntries, P,
+                  color(theme::dim_color()));
+
+    layout::print_rows(std::move(rows), P.width);
+}
+
+void print_help(std::string_view version) {
+    using namespace ftxui;
+
+    using Pair = std::pair<std::string, std::string>;
+
+    struct CmdEntry { std::string name; std::string desc; };
+    CmdEntry cmds[] = {
+        {"install",  "Install packages (e.g. xlings install gcc@15 node)"},
+        {"remove",   "Remove a package"},
+        {"update",   "Update package index or a specific package"},
+        {"search",   "Search for packages"},
+        {"list",     "List installed packages"},
+        {"info",     "Show package information"},
+        {"use",      "Switch tool version"},
+        {"config",   "Show or modify configuration"},
+        {"subos",    "Manage sub-OS environments"},
+        {"self",     "Manage xlings itself (install, update, clean)"},
+        {"script",   "Run xlings scripts"},
+        {"agent",    "Built-in skills and plain-text mode for LLM agents"},
+    };
+    struct OptEntry { std::string flag; std::string desc; };
+    OptEntry opts[] = {
+        {"-y, --yes",       "Skip confirmation prompts"},
+        {"-v, --verbose",   "Enable verbose output"},
+        {"-q, --quiet",     "Suppress non-essential output"},
+        {"    --agent",     "Plain-text output for LLM agents (no TUI/ANSI)"},
+    };
+
+    std::vector<Pair> cmdEntries;
+    for (auto& c : cmds) cmdEntries.emplace_back(c.name, c.desc);
+    std::vector<Pair> optEntries;
+    for (auto& o : opts) optEntries.emplace_back(o.flag, o.desc);
+
+    constexpr std::string_view kTagline =
+        "A modern package manager and development environment tool";
+    constexpr std::string_view kAgentLine1 =
+        "If you are an LLM/AI agent, run `xlings agent` FIRST.";
+    constexpr std::string_view kAgentLine2 =
+        "It contains usage instructions designed specifically for you.";
+
+    std::span<const Pair> sections[] = { cmdEntries, optEntries };
+    auto P = plan_help_(sections,
+                        std::max({ layout::display_width(kTagline) + 4,
+                                   layout::display_width(kAgentLine2) + 6,
+                                   40 }));
+
+    Elements rows;
+    rows.push_back(text(""));
+    rows.push_back(hbox({
+        text("  xlings") | theme::title(),
+        text(" " + std::string(version)) | color(theme::dim_color()),
+    }));
+    rows.push_back(text(""));
+    for (auto& line : layout::wrap_to_width(kTagline, std::max(1, P.width - 2))) {
+        rows.push_back(text("  " + line) | color(theme::text_color()));
+    }
+    rows.push_back(text(""));
+
+    // USAGE
+    rows.push_back(text("  USAGE") | bold | color(theme::text_color()));
+    rows.push_back(
+        text("    xlings [OPTIONS] [SUBCOMMAND]") | color(theme::dim_color()));
+    rows.push_back(text(""));
+
+    help_section_(rows, "SUBCOMMANDS", cmdEntries, P, bold | color(theme::magenta()));
+    help_section_(rows, "OPTIONS", optEntries, P, color(theme::dim_color()));
+
+    // AGENT hint — strong signal for LLM agents
+    rows.push_back(text("  FOR AI AGENTS") | bold | color(theme::text_color()));
+    for (auto& line : layout::wrap_to_width(kAgentLine1, std::max(1, P.width - 4))) {
+        rows.push_back(text("    " + line) | color(theme::text_color()));
+    }
+    for (auto& line : layout::wrap_to_width(kAgentLine2, std::max(1, P.width - 4))) {
+        rows.push_back(text("    " + line) | color(theme::dim_color()));
+    }
+    rows.push_back(text(""));
+
+    layout::print_rows(std::move(rows), P.width);
+}
+
+void print_tip(std::string_view message) {
+    using namespace ftxui;
+    int width = layout::fit_width(layout::display_width(message) + 6);
+    Elements rows;
+    auto lines = layout::wrap_to_width(message, std::max(1, width - 4));
+    for (std::size_t i = 0; i < lines.size(); ++i) {
+        rows.push_back(hbox({
+            i == 0 ? (text("  " + std::string(theme::icon::info) + " ")
+                      | color(theme::cyan()))
+                   : text("    "),
+            text(lines[i]) | color(theme::dim_color()),
+        }));
+    }
+    layout::print_rows(std::move(rows), width);
+}
+
+void print_usage(std::string_view usage) {
+    using namespace ftxui;
+    constexpr std::string_view kPrefix = "  Usage: ";
+    int lead = static_cast<int>(kPrefix.size());
+    int width = layout::fit_width(lead + layout::display_width(usage));
+    Elements rows;
+    auto lines = layout::wrap_to_width(usage, std::max(1, width - lead));
+    for (std::size_t i = 0; i < lines.size(); ++i) {
+        rows.push_back(hbox({
+            i == 0 ? (text(std::string(kPrefix)) | color(theme::dim_color()))
+                   : text(std::string(static_cast<std::size_t>(lead), ' ')),
+            text(lines[i]) | color(theme::text_color()),
+        }));
+    }
+    layout::print_rows(std::move(rows), width);
+}
+
+}
diff --git a/src/ui/banner.cppm b/src/ui/banner.cppm
index 3b4941c4..a80b8a50 100644
--- a/src/ui/banner.cppm
+++ b/src/ui/banner.cppm
@@ -37,232 +37,26 @@ constexpr int kHelpGap = 2;
 // Build a help section: heading plus name/description rows sharing `P`.
 void help_section_(ftxui::Elements& rows, std::string_view heading,
                    std::span<const std::pair<std::string, std::string>> entries,
-                   const layout::ColumnPlan& P, ftxui::Decorator nameStyle) {
-    using namespace ftxui;
-    if (entries.empty()) return;
-
-    rows.push_back(text("  " + std::string(heading)) | bold | color(theme::text_color()));
-    for (auto& [name, desc] : entries) {
-        if (P.stacked) {
-            for (auto& part : layout::wrap_to_width(
-                     name, std::max(1, P.width - kHelpIndent))) {
-                rows.push_back(text(std::string(kHelpIndent, ' ') + part) | nameStyle);
-            }
-            if (P.descW > 0 && !desc.empty()) {
-                rows.push_back(text(std::string(kHelpIndent + kHelpGap, ' ')
-                                    + layout::truncate_to_width(desc, P.descW))
-                               | color(theme::text_color()));
-            }
-            continue;
-        }
-        Elements cells;
-        cells.push_back(text(std::string(kHelpIndent, ' ')));
-        cells.push_back(text(layout::pad_to_width(name, P.nameW)) | nameStyle);
-        if (P.descW > 0 && !desc.empty()) {
-            cells.push_back(text(std::string(kHelpGap, ' ')));
-            cells.push_back(text(layout::truncate_to_width(desc, P.descW))
-                            | color(theme::text_color()));
-        }
-        rows.push_back(hbox(std::move(cells)));
-    }
-    rows.push_back(text(""));
-}
+                   const layout::ColumnPlan& P, ftxui::Decorator nameStyle);
 
 layout::ColumnPlan plan_help_(
         std::span<const std::span<const std::pair<std::string, std::string>>> sections,
-        int titleW) {
-    int nameMax = 0, descMax = 0;
-    for (auto& sec : sections) {
-        for (auto& [name, desc] : sec) {
-            nameMax = std::max(nameMax, layout::display_width(name));
-            descMax = std::max(descMax, layout::display_width(desc));
-        }
-    }
-    return layout::plan_two_column(kHelpIndent, kHelpGap, nameMax, descMax, titleW);
-}
+        int titleW);
 
 // Print TUI-styled subcommand help
 void print_subcommand_help(std::string_view name,
                            std::string_view description,
                            std::span<const HelpArg> args,
                            std::span<const HelpOpt> opts,
-                           std::span<const HelpOpt> subcmds = {}) {
-    using namespace ftxui;
-
-    using Pair = std::pair<std::string, std::string>;
-
-    std::vector<Pair> subEntries;
-    for (auto& s : subcmds) subEntries.emplace_back(s.flag, s.desc);
-
-    std::vector<Pair> argEntries;
-    for (auto& a : args) {
-        if (a.desc.empty()) continue;
-        argEntries.emplace_back("<" + a.name + ">", a.desc);
-    }
-
-    std::vector<Pair> optEntries;
-    for (auto& o : opts) optEntries.emplace_back(o.flag, o.desc);
-
-    std::string usage = "    xlings " + std::string(name);
-    if (!subcmds.empty()) usage += " [SUBCOMMAND]";
-    if (!opts.empty()) usage += " [OPTIONS]";
-    for (auto& a : args) {
-        usage += a.required ? " <" + a.name + ">" : " [" + a.name + "]";
-    }
-
-    std::span<const Pair> sections[] = { subEntries, argEntries, optEntries };
-    auto P = plan_help_(sections,
-                        std::max({ layout::display_width(usage) + 2,
-                                   layout::display_width(description) + 4,
-                                   40 }));
-
-    Elements rows;
-    rows.push_back(text(""));
-
-    // Title
-    rows.push_back(hbox({
-        text("  xlings ") | color(theme::dim_color()),
-        text(std::string(name)) | theme::title(),
-    }));
-    rows.push_back(text(""));
-
-    // Description
-    if (!description.empty()) {
-        for (auto& line : layout::wrap_to_width(description, std::max(1, P.width - 2))) {
-            rows.push_back(text("  " + line) | color(theme::text_color()));
-        }
-        rows.push_back(text(""));
-    }
-
-    // USAGE
-    rows.push_back(text("  USAGE") | bold | color(theme::text_color()));
-    rows.push_back(text(usage) | color(theme::dim_color()));
-    rows.push_back(text(""));
-
-    help_section_(rows, "SUBCOMMANDS", subEntries, P,
-                  bold | color(theme::magenta()));
-    help_section_(rows, "ARGS", argEntries, P,
-                  bold | color(theme::magenta()));
-    help_section_(rows, "OPTIONS", optEntries, P,
-                  color(theme::dim_color()));
-
-    layout::print_rows(std::move(rows), P.width);
-}
+                           std::span<const HelpOpt> subcmds = {});
 
 // Print styled top-level help text
-void print_help(std::string_view version) {
-    using namespace ftxui;
-
-    using Pair = std::pair<std::string, std::string>;
-
-    struct CmdEntry { std::string name; std::string desc; };
-    CmdEntry cmds[] = {
-        {"install",  "Install packages (e.g. xlings install gcc@15 node)"},
-        {"remove",   "Remove a package"},
-        {"update",   "Update package index or a specific package"},
-        {"search",   "Search for packages"},
-        {"list",     "List installed packages"},
-        {"info",     "Show package information"},
-        {"use",      "Switch tool version"},
-        {"config",   "Show or modify configuration"},
-        {"subos",    "Manage sub-OS environments"},
-        {"self",     "Manage xlings itself (install, update, clean)"},
-        {"script",   "Run xlings scripts"},
-        {"agent",    "Built-in skills and plain-text mode for LLM agents"},
-    };
-    struct OptEntry { std::string flag; std::string desc; };
-    OptEntry opts[] = {
-        {"-y, --yes",       "Skip confirmation prompts"},
-        {"-v, --verbose",   "Enable verbose output"},
-        {"-q, --quiet",     "Suppress non-essential output"},
-        {"    --agent",     "Plain-text output for LLM agents (no TUI/ANSI)"},
-    };
-
-    std::vector<Pair> cmdEntries;
-    for (auto& c : cmds) cmdEntries.emplace_back(c.name, c.desc);
-    std::vector<Pair> optEntries;
-    for (auto& o : opts) optEntries.emplace_back(o.flag, o.desc);
-
-    constexpr std::string_view kTagline =
-        "A modern package manager and development environment tool";
-    constexpr std::string_view kAgentLine1 =
-        "If you are an LLM/AI agent, run `xlings agent` FIRST.";
-    constexpr std::string_view kAgentLine2 =
-        "It contains usage instructions designed specifically for you.";
-
-    std::span<const Pair> sections[] = { cmdEntries, optEntries };
-    auto P = plan_help_(sections,
-                        std::max({ layout::display_width(kTagline) + 4,
-                                   layout::display_width(kAgentLine2) + 6,
-                                   40 }));
-
-    Elements rows;
-    rows.push_back(text(""));
-    rows.push_back(hbox({
-        text("  xlings") | theme::title(),
-        text(" " + std::string(version)) | color(theme::dim_color()),
-    }));
-    rows.push_back(text(""));
-    for (auto& line : layout::wrap_to_width(kTagline, std::max(1, P.width - 2))) {
-        rows.push_back(text("  " + line) | color(theme::text_color()));
-    }
-    rows.push_back(text(""));
-
-    // USAGE
-    rows.push_back(text("  USAGE") | bold | color(theme::text_color()));
-    rows.push_back(
-        text("    xlings [OPTIONS] [SUBCOMMAND]") | color(theme::dim_color()));
-    rows.push_back(text(""));
-
-    help_section_(rows, "SUBCOMMANDS", cmdEntries, P, bold | color(theme::magenta()));
-    help_section_(rows, "OPTIONS", optEntries, P, color(theme::dim_color()));
-
-    // AGENT hint — strong signal for LLM agents
-    rows.push_back(text("  FOR AI AGENTS") | bold | color(theme::text_color()));
-    for (auto& line : layout::wrap_to_width(kAgentLine1, std::max(1, P.width - 4))) {
-        rows.push_back(text("    " + line) | color(theme::text_color()));
-    }
-    for (auto& line : layout::wrap_to_width(kAgentLine2, std::max(1, P.width - 4))) {
-        rows.push_back(text("    " + line) | color(theme::dim_color()));
-    }
-    rows.push_back(text(""));
-
-    layout::print_rows(std::move(rows), P.width);
-}
+void print_help(std::string_view version);
 
 // Print a styled tip message
-void print_tip(std::string_view message) {
-    using namespace ftxui;
-    int width = layout::fit_width(layout::display_width(message) + 6);
-    Elements rows;
-    auto lines = layout::wrap_to_width(message, std::max(1, width - 4));
-    for (std::size_t i = 0; i < lines.size(); ++i) {
-        rows.push_back(hbox({
-            i == 0 ? (text("  " + std::string(theme::icon::info) + " ")
-                      | color(theme::cyan()))
-                   : text("    "),
-            text(lines[i]) | color(theme::dim_color()),
-        }));
-    }
-    layout::print_rows(std::move(rows), width);
-}
+void print_tip(std::string_view message);
 
 // Print a styled usage message
-void print_usage(std::string_view usage) {
-    using namespace ftxui;
-    constexpr std::string_view kPrefix = "  Usage: ";
-    int lead = static_cast<int>(kPrefix.size());
-    int width = layout::fit_width(lead + layout::display_width(usage));
-    Elements rows;
-    auto lines = layout::wrap_to_width(usage, std::max(1, width - lead));
-    for (std::size_t i = 0; i < lines.size(); ++i) {
-        rows.push_back(hbox({
-            i == 0 ? (text(std::string(kPrefix)) | color(theme::dim_color()))
-                   : text(std::string(static_cast<std::size_t>(lead), ' ')),
-            text(lines[i]) | color(theme::text_color()),
-        }));
-    }
-    layout::print_rows(std::move(rows), width);
-}
+void print_usage(std::string_view usage);
 
 } // namespace xlings::ui
diff --git a/src/ui/info_panel.cpp b/src/ui/info_panel.cpp
new file mode 100644
index 00000000..8fcb36e1
--- /dev/null
+++ b/src/ui/info_panel.cpp
@@ -0,0 +1,496 @@
+module;
+
+#include "ftxui/dom/elements.hpp"
+#include "ftxui/screen/screen.hpp"
+#include "ftxui/screen/color.hpp"
+
+module xlings.ui;
+
+import std;
+import xlings.core.palette;
+
+namespace xlings::ui {
+
+PanelLayout measure_panel_(std::string_view title,
+                           std::span<const InfoField> fields,
+                           std::span<const InfoField> extra) {
+    PanelLayout L;
+
+    auto scan = [&](std::span<const InfoField> fs) {
+        for (auto& f : fs) {
+            L.labelW = std::max(L.labelW, layout::display_width(f.label));
+            if (f.is_highlight || f.is_alert) L.markerW = 2;
+        }
+    };
+    scan(fields);
+    scan(extra);
+    L.labelW = std::max(L.labelW, 12);  // keeps short panels looking like a column
+
+    int valueMax = 0;
+    auto widest = [&](std::span<const InfoField> fs) {
+        for (auto& f : fs) valueMax = std::max(valueMax, field_value_width_(f));
+    };
+    widest(fields);
+    widest(extra);
+
+    L.lead = 2 + L.markerW + L.labelW + 2;
+    int titleW = 2 + 2 + layout::display_width(title);
+    int natural = std::max({ L.lead + valueMax, titleW, 42 });
+
+    L.width = layout::fit_width(natural);
+    L.valueW = L.width - L.lead;
+    L.stacked = (L.valueW < kMinValueW) || (L.labelW > L.width / 2);
+    if (L.stacked) L.valueW = std::max(1, L.width - kStackIndent);
+    return L;
+}
+
+void render_fields_(ftxui::Elements& rows, std::span<const InfoField> fields,
+                    const PanelLayout& L) {
+    using namespace ftxui;
+
+    for (auto& f : fields) {
+        // The active/notable marker is a glyph, not a color. `xlings use`
+        // used to say "this version is the active one" in green and nothing
+        // else, so NO_COLOR, a pipe, or a colorblind reader lost the one
+        // fact the command exists to report.
+        auto marker = L.markerW == 0
+            ? text("")
+            : (f.is_alert
+                   ? (text(std::string(theme::icon::warn) + " ") | color(theme::amber()))
+                   : f.is_highlight
+                       ? (text(std::string(theme::icon::active) + " ") | color(theme::green()))
+                       : text("  "));
+
+        auto value_style = [&](Element e) {
+            if (f.is_alert)     return e | color(theme::amber()) | bold;
+            if (f.is_highlight) return e | color(theme::green()) | bold;
+            return e | color(theme::text_color());
+        };
+
+        auto lines = layout::wrap_to_width(f.value, L.valueW);
+
+        if (L.stacked) {
+            rows.push_back(hbox({
+                text("  "),
+                marker,
+                text(f.label) | color(theme::dim_color()),
+            }));
+            for (auto& line : lines) {
+                if (line.empty()) continue;
+                rows.push_back(hbox({
+                    text(std::string(kStackIndent, ' ')),
+                    value_style(text(line)),
+                }));
+            }
+            continue;
+        }
+
+        rows.push_back(hbox({
+            text("  "),
+            marker,
+            text(layout::pad_to_width(f.label, L.labelW)) | color(theme::dim_color()),
+            text("  "),
+            value_style(text(lines.front())),
+        }));
+        // Continuation lines sit under the value column, so the label column
+        // still reads as a column.
+        for (std::size_t i = 1; i < lines.size(); ++i) {
+            rows.push_back(hbox({
+                text(std::string(static_cast<std::size_t>(L.lead), ' ')),
+                value_style(text(lines[i])),
+            }));
+        }
+    }
+}
+
+void print_info_panel(std::string_view title, std::span<const InfoField> fields, std::span<const InfoField> extra) {
+    using namespace ftxui;
+
+    auto L = measure_panel_(title, fields, extra);
+
+    // The divider spans the panel. It used to be forty hardcoded box glyphs
+    // whatever the panel measured, so a 230-column `self doctor` header sat
+    // on a forty-column rule and read as a frame that failed to draw.
+    auto divider = [&] {
+        return text("  " + layout::repeat(theme::icon::divider, L.width - 4))
+               | color(theme::border_color());
+    };
+
+    Elements rows;
+    rows.push_back(hbox({
+        text("  " + std::string(theme::icon::package) + " ") | color(theme::magenta()),
+        text(std::string(title)) | theme::highlight(),
+    }));
+    rows.push_back(divider());
+
+    render_fields_(rows, fields, L);
+
+    if (!extra.empty()) {
+        rows.push_back(divider());
+        render_fields_(rows, extra, L);
+    }
+
+    rows.push_back(text(""));
+
+    layout::print_rows(std::move(rows), L.width);
+}
+
+void print_styled_list(std::string_view title,
+                       std::span<const ListRow> items,
+                       bool show_marker) {
+    using namespace ftxui;
+
+    constexpr int kMarkerW = 4;   // "  ◆ " or four spaces
+    constexpr int kGap = 2;
+
+    int nameMax = 0, descMax = 0, statusMax = 0;
+    for (auto& row : items) {
+        nameMax = std::max(nameMax, layout::display_width(row.name));
+        descMax = std::max(descMax, layout::display_width(row.desc));
+        statusMax = std::max(statusMax, layout::display_width(row.status));
+    }
+    // The status column is planned as part of the name block, not of the
+    // description, so it is never the thing that gets dropped or truncated.
+    const int statusBlock = statusMax > 0 ? kGap + statusMax : 0;
+    auto P = layout::plan_two_column(kMarkerW, kGap, nameMax + statusBlock,
+                                     descMax,
+                                     2 + layout::display_width(title));
+
+    Elements rows;
+    if (!title.empty()) {
+        rows.push_back(text("  " + std::string(title)) | bold | color(theme::text_color()));
+        rows.push_back(text(""));
+    }
+
+    for (auto& row : items) {
+        const auto& name = row.name;
+        const auto& desc = row.desc;
+        auto marker = show_marker
+            ? (text("  " + std::string(theme::icon::package) + " ") | color(theme::magenta()))
+            : text("    ");
+
+        if (P.stacked) {
+            // The name is wider than the terminal. It still does not get cut:
+            // it wraps. A package name that does not round-trip into the next
+            // `xlings install` is worse than a taller list.
+            auto nameLines = layout::wrap_to_width(
+                name, std::max(1, P.width - kMarkerW));
+            for (std::size_t i = 0; i < nameLines.size(); ++i) {
+                rows.push_back(hbox({
+                    i == 0 ? marker : text(std::string(kMarkerW, ' ')),
+                    text(nameLines[i]) | bold | color(theme::magenta()),
+                }));
+            }
+            // Its own line, never elided. The stacked branch is where the
+            // terminal is already too narrow for the name, which is exactly
+            // when a dropped qualifier would do the most damage.
+            if (!row.status.empty()) {
+                rows.push_back(hbox({
+                    text(std::string(kMarkerW + kGap, ' ')),
+                    text(row.status) | color(theme::amber()),
+                }));
+            }
+            if (P.descW > 0 && !desc.empty()) {
+                rows.push_back(hbox({
+                    text(std::string(kMarkerW + kGap, ' ')),
+                    text(layout::truncate_to_width(desc, P.descW)) | color(theme::dim_color()),
+                }));
+            }
+            continue;
+        }
+
+        Elements cells;
+        cells.push_back(marker);
+        cells.push_back(text(layout::pad_to_width(name, nameMax))
+                        | bold | color(theme::magenta()));
+        if (statusMax > 0) {
+            cells.push_back(text(std::string(kGap, ' ')));
+            cells.push_back(text(layout::pad_to_width(row.status, statusMax))
+                            | color(theme::amber()));
+        }
+        if (P.descW > 0 && !desc.empty()) {
+            cells.push_back(text(std::string(kGap, ' ')));
+            cells.push_back(text(layout::truncate_to_width(desc, P.descW))
+                            | color(theme::dim_color()));
+        }
+        rows.push_back(hbox(std::move(cells)));
+    }
+    rows.push_back(text(""));
+
+    layout::print_rows(std::move(rows), P.width);
+}
+
+void print_install_plan(std::span<const std::pair<std::string, std::string>> packages) {
+    using namespace ftxui;
+
+    constexpr int kMarkerW = 6;   // "    ◆ "
+    constexpr int kGap = 2;
+
+    int nameMax = 0, descMax = 0;
+    for (auto& [nameVer, desc] : packages) {
+        nameMax = std::max(nameMax, layout::display_width(nameVer));
+        descMax = std::max(descMax, layout::display_width(desc));
+    }
+    auto P = layout::plan_two_column(kMarkerW, kGap, nameMax, descMax);
+
+    // Print header
+    Elements header;
+    header.push_back(hbox({
+        text("  Packages to install (") | color(theme::text_color()),
+        text(std::to_string(packages.size())) | bold | color(theme::text_color()),
+        text("):") | color(theme::text_color()),
+    }));
+    header.push_back(text(""));
+    // The blank row above is the spacing. print_rows terminates every row,
+    // including that one, so a further "\n" here would double it.
+    layout::print_rows(std::move(header), P.width);
+
+    // Print package lines (will be replaced by download progress via
+    // cursor-up). One row per package, always — the progress renderer counts
+    // the rows it has to move back over, so this list truncates rather than
+    // wraps whatever the width.
+    Elements pkgRows;
+    for (auto& [nameVer, desc] : packages) {
+        Elements cells;
+        cells.push_back(text("    " + std::string(theme::icon::package) + " ")
+                        | color(theme::magenta()));
+        // The one place a package name may be elided: this list is
+        // overwritten row-for-row and cannot grow a second line. It is
+        // elided visibly, with an ellipsis, rather than clipped at the
+        // screen edge.
+        auto shown = P.stacked
+            ? layout::truncate_to_width(nameVer, std::max(1, P.width - kMarkerW))
+            : layout::pad_to_width(nameVer, P.nameW);
+        cells.push_back(text(shown) | bold | color(theme::magenta()));
+        if (!P.stacked && P.descW > 0 && !desc.empty()) {
+            cells.push_back(text(std::string(kGap, ' ')));
+            cells.push_back(text(layout::truncate_to_width(desc, P.descW))
+                            | color(theme::dim_color()));
+        }
+        pkgRows.push_back(hbox(std::move(cells)));
+    }
+    pkgRows.push_back(text(""));
+
+    layout::print_rows(std::move(pkgRows), P.width);
+}
+
+void print_subos_list(
+    std::span<const std::tuple<std::string, std::string, int, bool>> entries) {
+    using namespace ftxui;
+
+    constexpr int kMarkerW = 4;
+    constexpr int kGap = 2;
+
+    auto detail_of = [](const std::string& dir, int tools) {
+        return "(" + dir + "  tools: " + std::to_string(tools) + ")";
+    };
+
+    int nameMax = 0, detailMax = 0;
+    for (auto& [name, dir, tools, active] : entries) {
+        nameMax = std::max(nameMax, layout::display_width(name));
+        detailMax = std::max(detailMax, layout::display_width(detail_of(dir, tools)));
+    }
+    auto P = layout::plan_two_column(kMarkerW, kGap, nameMax, detailMax);
+
+    Elements rows;
+    rows.push_back(text("  Sub-OS environments:") | bold | color(theme::text_color()));
+    rows.push_back(text(""));
+
+    for (auto& [name, dir, tools, active] : entries) {
+        auto marker = active
+            ? (text("  " + std::string(theme::icon::active) + " ") | color(theme::cyan()))
+            : text("    ");
+        auto nameEl = active
+            ? (text(layout::pad_to_width(name, P.nameW)) | bold | color(theme::cyan()))
+            : (text(layout::pad_to_width(name, P.nameW)) | color(theme::text_color()));
+
+        Elements cells { marker, nameEl };
+        if (P.descW > 0) {
+            cells.push_back(text(std::string(kGap, ' ')));
+            cells.push_back(
+                text(layout::truncate_to_width(detail_of(dir, tools), P.descW))
+                | color(theme::dim_color()));
+        }
+        rows.push_back(hbox(std::move(cells)));
+    }
+    rows.push_back(text(""));
+
+    layout::print_rows(std::move(rows), P.width);
+}
+
+void print_subos_resolved(std::string_view query, std::string_view selected) {
+    std::println("{}  {} resolved subos '{}' -> {}{}{}{}",
+                 palette::fg(palette::cyan()), theme::icon::arrow, query,
+                 palette::strong(), selected, palette::off(), palette::off());
+}
+
+void print_subos_created(const std::string& name, const std::string& dir) {
+    using namespace subos_ansi_;
+    std::println("{}  {} subos created: {}{}{}{}", green(), theme::icon::done, bold(), name, reset(), reset());
+    if (!dir.empty()) {
+        std::println("{}    dir:{} {}", gray(), reset(), dir);
+    }
+}
+
+void print_subos_switched(const std::string& name, const std::string& dir) {
+    using namespace subos_ansi_;
+    // [global] tag distinguishes the persistent "--global" action from the
+    // per-shell spawn (which is the default `xlings subos use NAME`).
+    if (dir.empty()) {
+        std::println("{}  {} switched to subos {}{}{}{}  [global]{}",
+                     cyan(), theme::icon::arrow, bold(), name, reset(), cyan(), reset());
+    } else {
+        std::println("{}  {} switched to subos {}{}{}{}  [global]  ({}){}",
+                     cyan(), theme::icon::arrow, bold(), name, reset(), cyan(), dir, reset());
+    }
+}
+
+void print_subos_removed(const std::string& name) {
+    using namespace subos_ansi_;
+    std::println("{}  {} subos removed: {}{}{}", green(), theme::icon::done, bold(), name, reset());
+}
+
+void print_subos_entering(const std::string& name) {
+    using namespace subos_ansi_;
+    std::println("{}  {} entering subos {}{}{}{}{}  (exit to leave){}",
+                 magenta(), theme::icon::arrow, green(), bold(), name, reset(), magenta(), reset());
+}
+
+void print_subos_already_in(const std::string& name) {
+    using namespace subos_ansi_;
+    std::println("{}  {} already in subos {}{}{}{}",
+                 gray(), theme::icon::info, bold(), name, reset(), gray());
+    std::print("{}", reset());
+}
+
+void print_subos_nesting(const std::string& from, const std::string& to) {
+    using namespace subos_ansi_;
+    std::println("{}  {} nesting subos {}{}{}{} -> {}{}{}{}  ('exit' returns to {}{}{}{}){}",
+                 amber(), theme::icon::extracting,
+                 bold(), from, reset(), amber(),
+                 bold(), to, reset(), amber(),
+                 bold(), from, reset(), amber(), reset());
+}
+
+void print_install_summary(int success, int failed) {
+    using namespace ftxui;
+
+    Elements rows;
+    std::vector<std::string> measured;
+    rows.push_back(text(""));
+
+    if (success > 0) {
+        auto msg = std::to_string(success) + " package(s) installed";
+        measured.push_back(msg);
+        rows.push_back(hbox({
+            text("  " + std::string(theme::icon::done) + " ") | color(theme::green()),
+            text(msg) | color(theme::green()) | bold,
+        }));
+    }
+    if (failed > 0) {
+        auto msg = std::to_string(failed) + " package(s) failed";
+        measured.push_back(msg);
+        rows.push_back(hbox({
+            text("  " + std::string(theme::icon::failed) + " ") | color(theme::red()),
+            text(msg) | color(theme::red()) | bold,
+        }));
+    }
+    rows.push_back(text(""));
+
+    layout::print_rows(std::move(rows), message_width_(measured));
+}
+
+void print_remove_plan(const std::string& subos,
+                       const std::string& name,
+                       const std::string& version) {
+    using namespace ftxui;
+
+    auto label = remove_target_label_(name, version);
+
+    Elements rows;
+    rows.push_back(text(""));
+    rows.push_back(hbox({
+        text("  Package to remove:") | color(theme::text_color()),
+    }));
+    rows.push_back(text(""));
+    auto suffix = "  (subos: " + subos + ")";
+    rows.push_back(hbox({
+        text("    " + std::string(theme::icon::package) + " ") | color(theme::magenta()),
+        text(label) | bold | color(theme::magenta()),
+        text(suffix) | color(theme::dim_color()),
+    }));
+    rows.push_back(text(""));
+
+    std::vector<std::string> measured { "Package to remove:", label + suffix + "  " };
+    layout::print_rows(std::move(rows), message_width_(measured));
+}
+
+void print_remove_summary(const std::string& subos,
+                          const std::string& name,
+                          const std::string& version,
+                          bool detached,
+                          const std::vector<std::string>& pinnedBy) {
+    using namespace ftxui;
+
+    auto label = remove_target_label_(name, version);
+
+    auto suffix = subos.empty() ? std::string{} : "  (subos: " + subos + ")";
+
+    Elements rows;
+    std::vector<std::string> measured;
+    rows.push_back(text(""));
+    if (detached) {
+        measured.push_back(label + " detached" + suffix);
+        rows.push_back(hbox({
+            text("  " + std::string(theme::icon::done) + " ") | color(theme::green()),
+            text(label + " detached") | color(theme::green()) | bold,
+            suffix.empty() ? text("")
+                           : (text(suffix) | color(theme::dim_color())),
+        }));
+        // Say how many, and name them only while the line still fits.
+        //
+        // ftxui clips at the screen edge, and on a pipe that is 80 columns:
+        // a home with 20 referencing subos rendered four names and a
+        // half-word, which reads as a complete list and is not. That is the
+        // same "looks finished, isn't" failure this whole change removes, so
+        // the cap is applied here where the count is known rather than left
+        // to the terminal. The COUNT is the load-bearing fact — it tells the
+        // user this is not one more `remove` away — and it always fits.
+        constexpr std::size_t kMaxNamed = 2;
+        if (pinnedBy.empty()) {
+            // Pinned by something the subos scan cannot name (a project-local
+            // subos, say). Still say the payload stayed.
+            measured.emplace_back("payload kept — another subos still uses it");
+            rows.push_back(text("    payload kept — another subos still uses it")
+                           | color(theme::dim_color()));
+        } else {
+            std::string line = std::format("    payload kept — {} other subos still use it",
+                                           pinnedBy.size());
+            if (pinnedBy.size() <= kMaxNamed) {
+                std::string names;
+                for (const auto& n : pinnedBy) {
+                    if (!names.empty()) names += ", ";
+                    names += n;
+                }
+                line = std::format("    payload kept — still used by {}", names);
+            }
+            measured.push_back(line);
+            rows.push_back(text(line) | color(theme::dim_color()));
+            rows.push_back(text("    remove it there too to delete it for good")
+                           | color(theme::dim_color()));
+        }
+    } else {
+        measured.push_back(label + " removed" + suffix);
+        rows.push_back(hbox({
+            text("  " + std::string(theme::icon::done) + " ") | color(theme::green()),
+            text(label + " removed") | color(theme::green()) | bold,
+            suffix.empty() ? text("")
+                           : (text(suffix) | color(theme::dim_color())),
+        }));
+    }
+    rows.push_back(text(""));
+
+    layout::print_rows(std::move(rows), message_width_(measured));
+}
+
+}
diff --git a/src/ui/info_panel.cppm b/src/ui/info_panel.cppm
index 83509f43..466d5fd6 100644
--- a/src/ui/info_panel.cppm
+++ b/src/ui/info_panel.cppm
@@ -78,132 +78,17 @@ inline int field_value_width_(const InfoField& f) {
 
 PanelLayout measure_panel_(std::string_view title,
                            std::span<const InfoField> fields,
-                           std::span<const InfoField> extra) {
-    PanelLayout L;
-
-    auto scan = [&](std::span<const InfoField> fs) {
-        for (auto& f : fs) {
-            L.labelW = std::max(L.labelW, layout::display_width(f.label));
-            if (f.is_highlight || f.is_alert) L.markerW = 2;
-        }
-    };
-    scan(fields);
-    scan(extra);
-    L.labelW = std::max(L.labelW, 12);  // keeps short panels looking like a column
-
-    int valueMax = 0;
-    auto widest = [&](std::span<const InfoField> fs) {
-        for (auto& f : fs) valueMax = std::max(valueMax, field_value_width_(f));
-    };
-    widest(fields);
-    widest(extra);
-
-    L.lead = 2 + L.markerW + L.labelW + 2;
-    int titleW = 2 + 2 + layout::display_width(title);
-    int natural = std::max({ L.lead + valueMax, titleW, 42 });
-
-    L.width = layout::fit_width(natural);
-    L.valueW = L.width - L.lead;
-    L.stacked = (L.valueW < kMinValueW) || (L.labelW > L.width / 2);
-    if (L.stacked) L.valueW = std::max(1, L.width - kStackIndent);
-    return L;
-}
+                           std::span<const InfoField> extra);
 
 // Render info fields into rows, wrapping values that do not fit.
 void render_fields_(ftxui::Elements& rows, std::span<const InfoField> fields,
-                    const PanelLayout& L) {
-    using namespace ftxui;
-
-    for (auto& f : fields) {
-        // The active/notable marker is a glyph, not a color. `xlings use`
-        // used to say "this version is the active one" in green and nothing
-        // else, so NO_COLOR, a pipe, or a colorblind reader lost the one
-        // fact the command exists to report.
-        auto marker = L.markerW == 0
-            ? text("")
-            : (f.is_alert
-                   ? (text(std::string(theme::icon::warn) + " ") | color(theme::amber()))
-                   : f.is_highlight
-                       ? (text(std::string(theme::icon::active) + " ") | color(theme::green()))
-                       : text("  "));
-
-        auto value_style = [&](Element e) {
-            if (f.is_alert)     return e | color(theme::amber()) | bold;
-            if (f.is_highlight) return e | color(theme::green()) | bold;
-            return e | color(theme::text_color());
-        };
-
-        auto lines = layout::wrap_to_width(f.value, L.valueW);
-
-        if (L.stacked) {
-            rows.push_back(hbox({
-                text("  "),
-                marker,
-                text(f.label) | color(theme::dim_color()),
-            }));
-            for (auto& line : lines) {
-                if (line.empty()) continue;
-                rows.push_back(hbox({
-                    text(std::string(kStackIndent, ' ')),
-                    value_style(text(line)),
-                }));
-            }
-            continue;
-        }
-
-        rows.push_back(hbox({
-            text("  "),
-            marker,
-            text(layout::pad_to_width(f.label, L.labelW)) | color(theme::dim_color()),
-            text("  "),
-            value_style(text(lines.front())),
-        }));
-        // Continuation lines sit under the value column, so the label column
-        // still reads as a column.
-        for (std::size_t i = 1; i < lines.size(); ++i) {
-            rows.push_back(hbox({
-                text(std::string(static_cast<std::size_t>(L.lead), ' ')),
-                value_style(text(lines[i])),
-            }));
-        }
-    }
-}
+                    const PanelLayout& L);
 
 // Print a styled info panel with a title and key-value fields,
 // plus an optional second section separated by a divider.
 void print_info_panel(std::string_view title,
                       std::span<const InfoField> fields,
-                      std::span<const InfoField> extra = {}) {
-    using namespace ftxui;
-
-    auto L = measure_panel_(title, fields, extra);
-
-    // The divider spans the panel. It used to be forty hardcoded box glyphs
-    // whatever the panel measured, so a 230-column `self doctor` header sat
-    // on a forty-column rule and read as a frame that failed to draw.
-    auto divider = [&] {
-        return text("  " + layout::repeat(theme::icon::divider, L.width - 4))
-               | color(theme::border_color());
-    };
-
-    Elements rows;
-    rows.push_back(hbox({
-        text("  " + std::string(theme::icon::package) + " ") | color(theme::magenta()),
-        text(std::string(title)) | theme::highlight(),
-    }));
-    rows.push_back(divider());
-
-    render_fields_(rows, fields, L);
-
-    if (!extra.empty()) {
-        rows.push_back(divider());
-        render_fields_(rows, extra, L);
-    }
-
-    rows.push_back(text(""));
-
-    layout::print_rows(std::move(rows), L.width);
-}
+                      std::span<const InfoField> extra = {});
 
 // Print a styled list of items with a title.
 //
@@ -212,195 +97,17 @@ void print_info_panel(std::string_view title,
 // never elided; the description is.
 void print_styled_list(std::string_view title,
                        std::span<const ListRow> items,
-                       bool show_marker) {
-    using namespace ftxui;
-
-    constexpr int kMarkerW = 4;   // "  ◆ " or four spaces
-    constexpr int kGap = 2;
-
-    int nameMax = 0, descMax = 0, statusMax = 0;
-    for (auto& row : items) {
-        nameMax = std::max(nameMax, layout::display_width(row.name));
-        descMax = std::max(descMax, layout::display_width(row.desc));
-        statusMax = std::max(statusMax, layout::display_width(row.status));
-    }
-    // The status column is planned as part of the name block, not of the
-    // description, so it is never the thing that gets dropped or truncated.
-    const int statusBlock = statusMax > 0 ? kGap + statusMax : 0;
-    auto P = layout::plan_two_column(kMarkerW, kGap, nameMax + statusBlock,
-                                     descMax,
-                                     2 + layout::display_width(title));
-
-    Elements rows;
-    if (!title.empty()) {
-        rows.push_back(text("  " + std::string(title)) | bold | color(theme::text_color()));
-        rows.push_back(text(""));
-    }
-
-    for (auto& row : items) {
-        const auto& name = row.name;
-        const auto& desc = row.desc;
-        auto marker = show_marker
-            ? (text("  " + std::string(theme::icon::package) + " ") | color(theme::magenta()))
-            : text("    ");
-
-        if (P.stacked) {
-            // The name is wider than the terminal. It still does not get cut:
-            // it wraps. A package name that does not round-trip into the next
-            // `xlings install` is worse than a taller list.
-            auto nameLines = layout::wrap_to_width(
-                name, std::max(1, P.width - kMarkerW));
-            for (std::size_t i = 0; i < nameLines.size(); ++i) {
-                rows.push_back(hbox({
-                    i == 0 ? marker : text(std::string(kMarkerW, ' ')),
-                    text(nameLines[i]) | bold | color(theme::magenta()),
-                }));
-            }
-            // Its own line, never elided. The stacked branch is where the
-            // terminal is already too narrow for the name, which is exactly
-            // when a dropped qualifier would do the most damage.
-            if (!row.status.empty()) {
-                rows.push_back(hbox({
-                    text(std::string(kMarkerW + kGap, ' ')),
-                    text(row.status) | color(theme::amber()),
-                }));
-            }
-            if (P.descW > 0 && !desc.empty()) {
-                rows.push_back(hbox({
-                    text(std::string(kMarkerW + kGap, ' ')),
-                    text(layout::truncate_to_width(desc, P.descW)) | color(theme::dim_color()),
-                }));
-            }
-            continue;
-        }
-
-        Elements cells;
-        cells.push_back(marker);
-        cells.push_back(text(layout::pad_to_width(name, nameMax))
-                        | bold | color(theme::magenta()));
-        if (statusMax > 0) {
-            cells.push_back(text(std::string(kGap, ' ')));
-            cells.push_back(text(layout::pad_to_width(row.status, statusMax))
-                            | color(theme::amber()));
-        }
-        if (P.descW > 0 && !desc.empty()) {
-            cells.push_back(text(std::string(kGap, ' ')));
-            cells.push_back(text(layout::truncate_to_width(desc, P.descW))
-                            | color(theme::dim_color()));
-        }
-        rows.push_back(hbox(std::move(cells)));
-    }
-    rows.push_back(text(""));
-
-    layout::print_rows(std::move(rows), P.width);
-}
+                       bool show_marker);
 
 // Print install plan display.
 // Saves cursor position before package lines so download progress can replace them.
-void print_install_plan(std::span<const std::pair<std::string, std::string>> packages) {
-    using namespace ftxui;
-
-    constexpr int kMarkerW = 6;   // "    ◆ "
-    constexpr int kGap = 2;
-
-    int nameMax = 0, descMax = 0;
-    for (auto& [nameVer, desc] : packages) {
-        nameMax = std::max(nameMax, layout::display_width(nameVer));
-        descMax = std::max(descMax, layout::display_width(desc));
-    }
-    auto P = layout::plan_two_column(kMarkerW, kGap, nameMax, descMax);
-
-    // Print header
-    Elements header;
-    header.push_back(hbox({
-        text("  Packages to install (") | color(theme::text_color()),
-        text(std::to_string(packages.size())) | bold | color(theme::text_color()),
-        text("):") | color(theme::text_color()),
-    }));
-    header.push_back(text(""));
-    // The blank row above is the spacing. print_rows terminates every row,
-    // including that one, so a further "\n" here would double it.
-    layout::print_rows(std::move(header), P.width);
-
-    // Print package lines (will be replaced by download progress via
-    // cursor-up). One row per package, always — the progress renderer counts
-    // the rows it has to move back over, so this list truncates rather than
-    // wraps whatever the width.
-    Elements pkgRows;
-    for (auto& [nameVer, desc] : packages) {
-        Elements cells;
-        cells.push_back(text("    " + std::string(theme::icon::package) + " ")
-                        | color(theme::magenta()));
-        // The one place a package name may be elided: this list is
-        // overwritten row-for-row and cannot grow a second line. It is
-        // elided visibly, with an ellipsis, rather than clipped at the
-        // screen edge.
-        auto shown = P.stacked
-            ? layout::truncate_to_width(nameVer, std::max(1, P.width - kMarkerW))
-            : layout::pad_to_width(nameVer, P.nameW);
-        cells.push_back(text(shown) | bold | color(theme::magenta()));
-        if (!P.stacked && P.descW > 0 && !desc.empty()) {
-            cells.push_back(text(std::string(kGap, ' ')));
-            cells.push_back(text(layout::truncate_to_width(desc, P.descW))
-                            | color(theme::dim_color()));
-        }
-        pkgRows.push_back(hbox(std::move(cells)));
-    }
-    pkgRows.push_back(text(""));
-
-    layout::print_rows(std::move(pkgRows), P.width);
-}
+void print_install_plan(std::span<const std::pair<std::string, std::string>> packages);
 
 // Print subos list
 void print_subos_list(
-    std::span<const std::tuple<std::string, std::string, int, bool>> entries) {
-    using namespace ftxui;
-
-    constexpr int kMarkerW = 4;
-    constexpr int kGap = 2;
-
-    auto detail_of = [](const std::string& dir, int tools) {
-        return "(" + dir + "  tools: " + std::to_string(tools) + ")";
-    };
+    std::span<const std::tuple<std::string, std::string, int, bool>> entries);
 
-    int nameMax = 0, detailMax = 0;
-    for (auto& [name, dir, tools, active] : entries) {
-        nameMax = std::max(nameMax, layout::display_width(name));
-        detailMax = std::max(detailMax, layout::display_width(detail_of(dir, tools)));
-    }
-    auto P = layout::plan_two_column(kMarkerW, kGap, nameMax, detailMax);
-
-    Elements rows;
-    rows.push_back(text("  Sub-OS environments:") | bold | color(theme::text_color()));
-    rows.push_back(text(""));
-
-    for (auto& [name, dir, tools, active] : entries) {
-        auto marker = active
-            ? (text("  " + std::string(theme::icon::active) + " ") | color(theme::cyan()))
-            : text("    ");
-        auto nameEl = active
-            ? (text(layout::pad_to_width(name, P.nameW)) | bold | color(theme::cyan()))
-            : (text(layout::pad_to_width(name, P.nameW)) | color(theme::text_color()));
-
-        Elements cells { marker, nameEl };
-        if (P.descW > 0) {
-            cells.push_back(text(std::string(kGap, ' ')));
-            cells.push_back(
-                text(layout::truncate_to_width(detail_of(dir, tools), P.descW))
-                | color(theme::dim_color()));
-        }
-        rows.push_back(hbox(std::move(cells)));
-    }
-    rows.push_back(text(""));
-
-    layout::print_rows(std::move(rows), P.width);
-}
-
-void print_subos_resolved(std::string_view query, std::string_view selected) {
-    std::println("{}  {} resolved subos '{}' -> {}{}{}{}",
-                 palette::fg(palette::cyan()), theme::icon::arrow, query,
-                 palette::strong(), selected, palette::off(), palette::off());
-}
+void print_subos_resolved(std::string_view query, std::string_view selected);
 
 // Subos status messages are single-line with a possibly-long path, and they
 // stay plain `std::print` rather than going through a rendered document: the
@@ -421,31 +128,11 @@ namespace subos_ansi_ {
     inline std::string amber()   { return palette::fg(palette::amber()); }    // nesting (caution-ish)
 }
 
-void print_subos_created(const std::string& name, const std::string& dir) {
-    using namespace subos_ansi_;
-    std::println("{}  {} subos created: {}{}{}{}", green(), theme::icon::done, bold(), name, reset(), reset());
-    if (!dir.empty()) {
-        std::println("{}    dir:{} {}", gray(), reset(), dir);
-    }
-}
+void print_subos_created(const std::string& name, const std::string& dir);
 
-void print_subos_switched(const std::string& name, const std::string& dir) {
-    using namespace subos_ansi_;
-    // [global] tag distinguishes the persistent "--global" action from the
-    // per-shell spawn (which is the default `xlings subos use NAME`).
-    if (dir.empty()) {
-        std::println("{}  {} switched to subos {}{}{}{}  [global]{}",
-                     cyan(), theme::icon::arrow, bold(), name, reset(), cyan(), reset());
-    } else {
-        std::println("{}  {} switched to subos {}{}{}{}  [global]  ({}){}",
-                     cyan(), theme::icon::arrow, bold(), name, reset(), cyan(), dir, reset());
-    }
-}
+void print_subos_switched(const std::string& name, const std::string& dir);
 
-void print_subos_removed(const std::string& name) {
-    using namespace subos_ansi_;
-    std::println("{}  {} subos removed: {}{}{}", green(), theme::icon::done, bold(), name, reset());
-}
+void print_subos_removed(const std::string& name);
 
 // `xlings subos use <name>` (default spawn mode): user is entering a fresh
 // sub-shell where XLINGS_ACTIVE_SUBOS=<name> is set. Reuses the same
@@ -456,32 +143,16 @@ void print_subos_removed(const std::string& name) {
 // The subos NAME is rendered in bold green (matching the prompt marker
 // styling) so the user's eye lands on it; the rest of the line stays in
 // the magenta accent that distinguishes "spawn" from "switched" (cyan).
-void print_subos_entering(const std::string& name) {
-    using namespace subos_ansi_;
-    std::println("{}  {} entering subos {}{}{}{}{}  (exit to leave){}",
-                 magenta(), theme::icon::arrow, green(), bold(), name, reset(), magenta(), reset());
-}
+void print_subos_entering(const std::string& name);
 
 // `xlings subos use <same>` while already in <same>: nothing happens, but
 // we tell the user so they know the command was received and acknowledged.
-void print_subos_already_in(const std::string& name) {
-    using namespace subos_ansi_;
-    std::println("{}  {} already in subos {}{}{}{}",
-                 gray(), theme::icon::info, bold(), name, reset(), gray());
-    std::print("{}", reset());
-}
+void print_subos_already_in(const std::string& name);
 
 // `xlings subos use <other>` while in <current>: the spawn will create a
 // nested sub-shell. Single-line summary; the entering line that follows
 // gives the destination, no need to repeat the layer count separately.
-void print_subos_nesting(const std::string& from, const std::string& to) {
-    using namespace subos_ansi_;
-    std::println("{}  {} nesting subos {}{}{}{} -> {}{}{}{}  ('exit' returns to {}{}{}{}){}",
-                 amber(), theme::icon::extracting,
-                 bold(), from, reset(), amber(),
-                 bold(), to, reset(), amber(),
-                 bold(), from, reset(), amber(), reset());
-}
+void print_subos_nesting(const std::string& from, const std::string& to);
 
 // Width for a short message block: the widest line it will draw, clamped to
 // the terminal. These blocks are a couple of lines of prose, so there is no
@@ -493,33 +164,7 @@ inline int message_width_(std::span<const std::string> lines) {
 }
 
 // Print install summary with success/fail counts
-void print_install_summary(int success, int failed) {
-    using namespace ftxui;
-
-    Elements rows;
-    std::vector<std::string> measured;
-    rows.push_back(text(""));
-
-    if (success > 0) {
-        auto msg = std::to_string(success) + " package(s) installed";
-        measured.push_back(msg);
-        rows.push_back(hbox({
-            text("  " + std::string(theme::icon::done) + " ") | color(theme::green()),
-            text(msg) | color(theme::green()) | bold,
-        }));
-    }
-    if (failed > 0) {
-        auto msg = std::to_string(failed) + " package(s) failed";
-        measured.push_back(msg);
-        rows.push_back(hbox({
-            text("  " + std::string(theme::icon::failed) + " ") | color(theme::red()),
-            text(msg) | color(theme::red()) | bold,
-        }));
-    }
-    rows.push_back(text(""));
-
-    layout::print_rows(std::move(rows), message_width_(measured));
-}
+void print_install_summary(int success, int failed);
 
 // Format "<name>[@<version>]" for display. Centralized so the plan and
 // summary lines stay aligned when version is absent.
@@ -532,28 +177,7 @@ inline std::string remove_target_label_(const std::string& name,
 // Print remove plan (shown before the confirmation prompt)
 void print_remove_plan(const std::string& subos,
                        const std::string& name,
-                       const std::string& version) {
-    using namespace ftxui;
-
-    auto label = remove_target_label_(name, version);
-
-    Elements rows;
-    rows.push_back(text(""));
-    rows.push_back(hbox({
-        text("  Package to remove:") | color(theme::text_color()),
-    }));
-    rows.push_back(text(""));
-    auto suffix = "  (subos: " + subos + ")";
-    rows.push_back(hbox({
-        text("    " + std::string(theme::icon::package) + " ") | color(theme::magenta()),
-        text(label) | bold | color(theme::magenta()),
-        text(suffix) | color(theme::dim_color()),
-    }));
-    rows.push_back(text(""));
-
-    std::vector<std::string> measured { "Package to remove:", label + suffix + "  " };
-    layout::print_rows(std::move(rows), message_width_(measured));
-}
+                       const std::string& version);
 
 // Print uninstall summary
 // `detached` distinguishes the two outcomes `remove` can have. They used to
@@ -565,68 +189,6 @@ void print_remove_summary(const std::string& subos,
                           const std::string& name,
                           const std::string& version,
                           bool detached,
-                          const std::vector<std::string>& pinnedBy) {
-    using namespace ftxui;
-
-    auto label = remove_target_label_(name, version);
-
-    auto suffix = subos.empty() ? std::string{} : "  (subos: " + subos + ")";
-
-    Elements rows;
-    std::vector<std::string> measured;
-    rows.push_back(text(""));
-    if (detached) {
-        measured.push_back(label + " detached" + suffix);
-        rows.push_back(hbox({
-            text("  " + std::string(theme::icon::done) + " ") | color(theme::green()),
-            text(label + " detached") | color(theme::green()) | bold,
-            suffix.empty() ? text("")
-                           : (text(suffix) | color(theme::dim_color())),
-        }));
-        // Say how many, and name them only while the line still fits.
-        //
-        // ftxui clips at the screen edge, and on a pipe that is 80 columns:
-        // a home with 20 referencing subos rendered four names and a
-        // half-word, which reads as a complete list and is not. That is the
-        // same "looks finished, isn't" failure this whole change removes, so
-        // the cap is applied here where the count is known rather than left
-        // to the terminal. The COUNT is the load-bearing fact — it tells the
-        // user this is not one more `remove` away — and it always fits.
-        constexpr std::size_t kMaxNamed = 2;
-        if (pinnedBy.empty()) {
-            // Pinned by something the subos scan cannot name (a project-local
-            // subos, say). Still say the payload stayed.
-            measured.emplace_back("payload kept — another subos still uses it");
-            rows.push_back(text("    payload kept — another subos still uses it")
-                           | color(theme::dim_color()));
-        } else {
-            std::string line = std::format("    payload kept — {} other subos still use it",
-                                           pinnedBy.size());
-            if (pinnedBy.size() <= kMaxNamed) {
-                std::string names;
-                for (const auto& n : pinnedBy) {
-                    if (!names.empty()) names += ", ";
-                    names += n;
-                }
-                line = std::format("    payload kept — still used by {}", names);
-            }
-            measured.push_back(line);
-            rows.push_back(text(line) | color(theme::dim_color()));
-            rows.push_back(text("    remove it there too to delete it for good")
-                           | color(theme::dim_color()));
-        }
-    } else {
-        measured.push_back(label + " removed" + suffix);
-        rows.push_back(hbox({
-            text("  " + std::string(theme::icon::done) + " ") | color(theme::green()),
-            text(label + " removed") | color(theme::green()) | bold,
-            suffix.empty() ? text("")
-                           : (text(suffix) | color(theme::dim_color())),
-        }));
-    }
-    rows.push_back(text(""));
-
-    layout::print_rows(std::move(rows), message_width_(measured));
-}
+                          const std::vector<std::string>& pinnedBy);
 
 } // namespace xlings::ui
diff --git a/src/ui/layout.cppm b/src/ui/layout.cppm
index ba4315e6..a595b0b8 100644
--- a/src/ui/layout.cppm
+++ b/src/ui/layout.cppm
@@ -8,7 +8,6 @@ module;
 export module xlings.ui:layout;
 
 import std;
-import xlings.platform;
 import xlings.core.palette;
 import :theme;
 
diff --git a/src/ui/progress.cpp b/src/ui/progress.cpp
new file mode 100644
index 00000000..387b6062
--- /dev/null
+++ b/src/ui/progress.cpp
@@ -0,0 +1,356 @@
+module;
+
+#include "ftxui/dom/elements.hpp"
+#include "ftxui/screen/screen.hpp"
+#include "ftxui/screen/color.hpp"
+
+module xlings.ui;
+
+import std;
+import xlings.core.palette;
+
+namespace xlings::ui {
+
+std::string phase_icon(Phase p) {
+    switch (p) {
+        case Phase::Pending:      return theme::icon::pending;
+        case Phase::Downloading:  return theme::icon::downloading;
+        case Phase::Extracting:   return theme::icon::extracting;
+        case Phase::Installing:   return theme::icon::installing;
+        case Phase::Configuring:  return theme::icon::configuring;
+        case Phase::Done:         return theme::icon::done;
+        case Phase::Failed:       return theme::icon::failed;
+    }
+    return "?";
+}
+
+ftxui::Color phase_color(Phase p) {
+    switch (p) {
+        case Phase::Pending:      return theme::dim_color();
+        case Phase::Downloading:  return theme::cyan();
+        case Phase::Extracting:   return theme::amber();
+        case Phase::Installing:   return theme::amber();
+        case Phase::Configuring:  return theme::amber();
+        case Phase::Done:         return theme::green();
+        case Phase::Failed:       return theme::red();
+    }
+    return theme::dim_color();
+}
+
+std::string phase_label(Phase p) {
+    switch (p) {
+        case Phase::Pending:      return "pending";
+        case Phase::Downloading:  return "downloading";
+        case Phase::Extracting:   return "extracting";
+        case Phase::Installing:   return "installing";
+        case Phase::Configuring:  return "configuring";
+        case Phase::Done:         return "done";
+        case Phase::Failed:       return "failed";
+    }
+    return "unknown";
+}
+
+ftxui::Element name_as_progress(const std::string& shownName, float progress, ftxui::Color litColor, ftxui::Color dimColor, std::size_t nameWidth, bool isBold, bool showCursor) {
+    using namespace ftxui;
+
+    // The column may have been narrowed to keep the row inside the terminal.
+    // Elide visibly rather than letting ftxui clip at the column edge.
+    const std::string name =
+        layout::truncate_to_width(shownName, static_cast<int>(nameWidth));
+
+    // Clamp progress
+    if (progress < 0.0f) progress = 0.0f;
+    if (progress > 1.0f) progress = 1.0f;
+
+    // Split by display columns, not bytes: the split used to be
+    // `progress * name.size()`, which cuts a multi-byte name mid-sequence
+    // and mis-measures how much of it is "lit".
+    const int nameCols = layout::display_width(name);
+    auto splitPos = layout::split_at_width(
+        name, static_cast<int>(progress * static_cast<float>(nameCols)));
+
+    // Padding spaces always in dimColor
+    std::size_t padCount = (static_cast<int>(nameWidth) > nameCols)
+        ? static_cast<std::size_t>(static_cast<int>(nameWidth) - nameCols) : 0;
+    std::string padding(padCount, ' ');
+
+    // Three parts: lit | cursor (orange+blink) | dim
+    std::string litPart = name.substr(0, splitPos);
+    std::string cursorPart;
+    std::string dimNamePart;
+
+    if (showCursor && splitPos < name.size()) {
+        auto cursorEnd = splitPos + layout::glyph_len(name, splitPos);
+        cursorPart = name.substr(splitPos, cursorEnd - splitPos);
+        dimNamePart = name.substr(cursorEnd);
+    } else {
+        dimNamePart = name.substr(splitPos);
+    }
+
+    Element litEl = text(litPart) | color(litColor);
+    Element dimEl = text(dimNamePart + padding) | color(dimColor);
+    if (isBold) {
+        litEl = litEl | bold;
+        dimEl = dimEl | bold;
+    }
+
+    Element result;
+    if (!cursorPart.empty()) {
+        Element cursorEl = text(cursorPart)
+            | color(theme::amber()) | bold | blink;
+        result = hbox({ litEl, cursorEl, dimEl });
+    } else {
+        result = hbox({ litEl, dimEl });
+    }
+    // Enforce exact width for alignment across rows
+    return result | size(WIDTH, EQUAL, static_cast<int>(nameWidth));
+}
+
+void print_progress(std::span<const StatusEntry> entries) {
+    using namespace ftxui;
+
+    // Status label width for alignment
+    constexpr std::size_t statusWidth = 8;
+    constexpr int iconW = 3;   // " <icon> "
+
+    // Compute max name width for alignment
+    std::size_t nameWidth = 20;
+    for (auto& e : entries) {
+        nameWidth = std::max(nameWidth,
+                             static_cast<std::size_t>(layout::display_width(e.name)));
+    }
+    nameWidth += 2; // padding
+    nameWidth = fit_name_width_(nameWidth, iconW, static_cast<int>(statusWidth));
+
+    Elements rows;
+    for (auto& e : entries) {
+        auto pc = phase_color(e.phase);
+        auto icon = text(" " + phase_icon(e.phase) + " ") | color(pc);
+
+        Element nameEl;
+        std::string statusStr;
+
+        if (e.phase == Phase::Pending) {
+            nameEl = name_as_progress(e.name, 0.0f,
+                theme::dim_color(), theme::border_color(), nameWidth, false);
+            statusStr = "pending";
+        } else if (e.phase == Phase::Downloading || e.phase == Phase::Extracting ||
+                   e.phase == Phase::Installing || e.phase == Phase::Configuring) {
+            float pct = e.progress;
+            nameEl = name_as_progress(e.name, pct,
+                pc, theme::border_color(), nameWidth, true, true);
+            if (pct > 0.0f) {
+                int whole = static_cast<int>(pct * 100.0f);
+                int frac = static_cast<int>(pct * 1000.0f) % 10;
+                statusStr = std::to_string(whole) + "." + std::to_string(frac) + "%";
+            } else {
+                statusStr = phase_label(e.phase);
+            }
+        } else if (e.phase == Phase::Done) {
+            nameEl = name_as_progress(e.name, 1.0f,
+                theme::green(), theme::green(), nameWidth, true);
+            statusStr = "done";
+        } else { // Failed
+            nameEl = name_as_progress(e.name, 1.0f,
+                theme::red(), theme::red(), nameWidth, true);
+            statusStr = "failed";
+            if (!e.message.empty()) statusStr += ": " + e.message;
+        }
+
+        // Right-pad status for alignment
+        while (statusStr.size() < statusWidth) statusStr = " " + statusStr;
+
+        auto statusEl = text(" " + statusStr);
+        if (e.phase == Phase::Done) statusEl = statusEl | color(theme::green());
+        else if (e.phase == Phase::Failed) statusEl = statusEl | color(theme::red()) | bold;
+        else if (e.phase == Phase::Pending) statusEl = statusEl | color(theme::dim_color());
+        else statusEl = statusEl | color(theme::dim_color());
+
+        rows.push_back(hbox({ icon, nameEl, statusEl }));
+    }
+    layout::print_rows(std::move(rows),
+                       layout::fit_width(row_width_(nameWidth, iconW,
+                                                    static_cast<int>(statusWidth))));
+    std::println("");
+}
+
+std::string format_eta(int seconds) {
+    if (seconds < 0) return "";
+    if (seconds < 60) return std::to_string(seconds) + "s";
+    int min = seconds / 60;
+    int sec = seconds % 60;
+    return std::to_string(min) + "m" + std::to_string(sec) + "s";
+}
+
+std::string format_speed(double bytesPerSec) {
+    if (bytesPerSec < 1024.0)
+        return std::to_string(static_cast<int>(bytesPerSec)) + " B/s";
+    if (bytesPerSec < 1024.0 * 1024.0) {
+        int kb = static_cast<int>(bytesPerSec / 1024.0 * 10.0);
+        return std::to_string(kb / 10) + "." + std::to_string(kb % 10) + " KB/s";
+    }
+    int mb = static_cast<int>(bytesPerSec / (1024.0 * 1024.0) * 10.0);
+    return std::to_string(mb / 10) + "." + std::to_string(mb % 10) + " MB/s";
+}
+
+int render_download_progress(std::span<const DownloadProgressEntry> progState, std::size_t nameWidth, double elapsedSec, bool sizesReady, int prevLines) {
+    using namespace ftxui;
+    const bool rewrite = palette::cursor_rewrite_allowed();
+    constexpr std::size_t statusWidth = 8;
+    constexpr int iconW = 6;   // "    <icon> "
+
+    // The caller measures the name column in bytes (core has no display-width
+    // table). Re-measure it here in columns, then fit it to the terminal.
+    std::size_t measured = 20;
+    for (auto& p : progState) {
+        measured = std::max(measured,
+                            static_cast<std::size_t>(layout::display_width(p.name)));
+    }
+    nameWidth = fit_name_width_(measured + 2, iconW, static_cast<int>(statusWidth));
+
+    Elements rows;
+    double totalBytes = 0.0;
+    double totalDownloaded = 0.0;
+
+    for (auto& p : progState) {
+        Element icon;
+        Element nameEl;
+        std::string statusStr;
+
+        totalBytes += p.totalBytes;
+
+        if (!p.started) {
+            icon = text("    " + std::string(theme::icon::pending) + " ")
+                | color(theme::dim_color());
+            nameEl = name_as_progress(p.name, 0.0f,
+                theme::dim_color(), theme::border_color(), nameWidth, false);
+            statusStr = "pending";
+        } else if (!p.finished) {
+            float pct = (p.totalBytes > 0)
+                ? static_cast<float>(p.downloadedBytes / p.totalBytes)
+                : 0.0f;
+            totalDownloaded += p.downloadedBytes;
+            icon = text("    " + std::string(theme::icon::downloading) + " ")
+                | color(theme::cyan());
+            nameEl = name_as_progress(p.name, pct,
+                theme::cyan(), theme::border_color(), nameWidth, true, rewrite);
+            if (pct > 0.0f) {
+                int whole = static_cast<int>(pct * 100.0f);
+                int frac = static_cast<int>(pct * 1000.0f) % 10;
+                statusStr = std::to_string(whole) + "." + std::to_string(frac) + "%";
+            } else {
+                statusStr = "0.0%";
+            }
+        } else if (p.success) {
+            totalDownloaded += p.totalBytes;
+            icon = text("    " + std::string(theme::icon::done) + " ")
+                | color(theme::green());
+            nameEl = name_as_progress(p.name, 1.0f,
+                theme::green(), theme::green(), nameWidth, true);
+            statusStr = "done";
+        } else {
+            totalDownloaded += p.totalBytes;
+            icon = text("    " + std::string(theme::icon::failed) + " ")
+                | color(theme::red()) | bold;
+            nameEl = name_as_progress(p.name, 1.0f,
+                theme::red(), theme::red(), nameWidth, true);
+            statusStr = "failed";
+        }
+
+        while (statusStr.size() < statusWidth) statusStr = " " + statusStr;
+
+        auto statusEl = text(" " + statusStr);
+        if (p.finished && p.success) statusEl = statusEl | color(theme::green());
+        else if (p.finished) statusEl = statusEl | color(theme::red()) | bold;
+        else if (!p.started) statusEl = statusEl | color(theme::dim_color());
+        else statusEl = statusEl | color(theme::dim_color());
+
+        rows.push_back(hbox({ icon, nameEl, statusEl }));
+    }
+
+    // Overall progress bar
+    // When some packages have unknown sizes (totalBytes==0 and not finished),
+    // byte-based progress is misleading. Fall back to finished_count/total_count.
+    float overallPct = 0.0f;
+    std::string speedStr;
+    std::string etaStr;
+
+    int totalCount = static_cast<int>(progState.size());
+    int finishedCount = 0;
+    bool allSizesKnown = true;
+    for (auto& p : progState) {
+        if (p.finished) ++finishedCount;
+        else if (p.totalBytes <= 0.0) allSizesKnown = false;
+    }
+
+    if (allSizesKnown && totalBytes > 0.0) {
+        // All sizes known: use byte-weighted progress
+        overallPct = static_cast<float>(totalDownloaded / totalBytes);
+        if (overallPct > 1.0f) overallPct = 1.0f;
+
+        if (elapsedSec > 0.5 && totalDownloaded > 0.0) {
+            double speed = totalDownloaded / elapsedSec;
+            speedStr = "  " + format_speed(speed);
+        }
+
+        if (overallPct > 0.01f && overallPct < 1.0f && elapsedSec > 1.0) {
+            double speed = totalDownloaded / elapsedSec;
+            if (speed > 0.0) {
+                double remainingBytes = totalBytes - totalDownloaded;
+                int remainingSec = static_cast<int>(remainingBytes / speed);
+                etaStr = "  ETA " + format_eta(remainingSec);
+            }
+        }
+    } else if (totalCount > 0) {
+        // Fallback: count-based progress
+        overallPct = static_cast<float>(finishedCount) / static_cast<float>(totalCount);
+    }
+
+    int pctWhole = static_cast<int>(overallPct * 100.0f);
+    int pctFrac = static_cast<int>(overallPct * 1000.0f) % 10;
+    std::string pctStr = std::to_string(pctWhole) + "." + std::to_string(pctFrac) + "%";
+
+    // The bar shares its line with the percentage, speed and ETA, so it gives
+    // ground first rather than pushing the line past the edge.
+    constexpr int kGaugeMax = 30;
+    const int gaugeTail = 4
+        + layout::display_width("  " + pctStr)
+        + layout::display_width(speedStr)
+        + layout::display_width(etaStr);
+
+    int width = layout::fit_width(
+        std::max(row_width_(nameWidth, iconW, static_cast<int>(statusWidth)),
+                 gaugeTail + kGaugeMax));
+    int gaugeW = std::clamp(width - gaugeTail, 8, kGaugeMax);
+
+    rows.push_back(text(""));
+    rows.push_back(hbox({
+        text("  " + std::string(theme::icon::arrow) + " ") | color(theme::cyan()),
+        gauge(overallPct) | size(WIDTH, EQUAL, gaugeW) | color(theme::cyan()),
+        text("  " + pctStr) | bold | color(theme::text_color()),
+        text(speedStr) | color(theme::cyan()),
+        text(etaStr) | color(theme::dim_color()),
+    }));
+    // erase_eol rather than padding: the frame is drawn over the previous
+    // one, and a trimmed line that is shorter than its predecessor would
+    // otherwise leave the old tail behind.
+    auto body = layout::render_to_string(vbox(std::move(rows)), width,
+                                         /*erase_eol=*/rewrite);
+
+    // Build single output buffer: cursor-up + content + clear trailing.
+    std::string output;
+    if (rewrite && prevLines > 0) {
+        output += "\033[" + std::to_string(prevLines) + "A\r";
+    }
+    output += body;
+    if (rewrite) output += "\033[J";
+
+    std::cout << output << std::flush;
+
+    // Every row fits the terminal (fit_name_width_ above), so rendered rows
+    // and physical lines are the same number and the cursor-up on the next
+    // frame lands where this frame started.
+    return static_cast<int>(std::ranges::count(body, '\n'));
+}
+
+}
diff --git a/src/ui/progress.cppm b/src/ui/progress.cppm
index 3aa93dac..ee3f4b49 100644
--- a/src/ui/progress.cppm
+++ b/src/ui/progress.cppm
@@ -7,7 +7,6 @@ module;
 export module xlings.ui:progress;
 
 import std;
-import xlings.core.palette;
 import :theme;
 import :layout;
 
@@ -22,44 +21,11 @@ struct StatusEntry {
     std::string message;
 };
 
-std::string phase_icon(Phase p) {
-    switch (p) {
-        case Phase::Pending:      return theme::icon::pending;
-        case Phase::Downloading:  return theme::icon::downloading;
-        case Phase::Extracting:   return theme::icon::extracting;
-        case Phase::Installing:   return theme::icon::installing;
-        case Phase::Configuring:  return theme::icon::configuring;
-        case Phase::Done:         return theme::icon::done;
-        case Phase::Failed:       return theme::icon::failed;
-    }
-    return "?";
-}
+std::string phase_icon(Phase p);
 
-ftxui::Color phase_color(Phase p) {
-    switch (p) {
-        case Phase::Pending:      return theme::dim_color();
-        case Phase::Downloading:  return theme::cyan();
-        case Phase::Extracting:   return theme::amber();
-        case Phase::Installing:   return theme::amber();
-        case Phase::Configuring:  return theme::amber();
-        case Phase::Done:         return theme::green();
-        case Phase::Failed:       return theme::red();
-    }
-    return theme::dim_color();
-}
+ftxui::Color phase_color(Phase p);
 
-std::string phase_label(Phase p) {
-    switch (p) {
-        case Phase::Pending:      return "pending";
-        case Phase::Downloading:  return "downloading";
-        case Phase::Extracting:   return "extracting";
-        case Phase::Installing:   return "installing";
-        case Phase::Configuring:  return "configuring";
-        case Phase::Done:         return "done";
-        case Phase::Failed:       return "failed";
-    }
-    return "unknown";
-}
+std::string phase_label(Phase p);
 
 // Build a name element where the name itself is the progress bar:
 // characters colored from left to right based on progress percentage.
@@ -69,61 +35,7 @@ std::string phase_label(Phase p) {
 ftxui::Element name_as_progress(const std::string& shownName, float progress,
                                 ftxui::Color litColor, ftxui::Color dimColor,
                                 std::size_t nameWidth, bool isBold,
-                                bool showCursor = false) {
-    using namespace ftxui;
-
-    // The column may have been narrowed to keep the row inside the terminal.
-    // Elide visibly rather than letting ftxui clip at the column edge.
-    const std::string name =
-        layout::truncate_to_width(shownName, static_cast<int>(nameWidth));
-
-    // Clamp progress
-    if (progress < 0.0f) progress = 0.0f;
-    if (progress > 1.0f) progress = 1.0f;
-
-    // Split by display columns, not bytes: the split used to be
-    // `progress * name.size()`, which cuts a multi-byte name mid-sequence
-    // and mis-measures how much of it is "lit".
-    const int nameCols = layout::display_width(name);
-    auto splitPos = layout::split_at_width(
-        name, static_cast<int>(progress * static_cast<float>(nameCols)));
-
-    // Padding spaces always in dimColor
-    std::size_t padCount = (static_cast<int>(nameWidth) > nameCols)
-        ? static_cast<std::size_t>(static_cast<int>(nameWidth) - nameCols) : 0;
-    std::string padding(padCount, ' ');
-
-    // Three parts: lit | cursor (orange+blink) | dim
-    std::string litPart = name.substr(0, splitPos);
-    std::string cursorPart;
-    std::string dimNamePart;
-
-    if (showCursor && splitPos < name.size()) {
-        auto cursorEnd = splitPos + layout::glyph_len(name, splitPos);
-        cursorPart = name.substr(splitPos, cursorEnd - splitPos);
-        dimNamePart = name.substr(cursorEnd);
-    } else {
-        dimNamePart = name.substr(splitPos);
-    }
-
-    Element litEl = text(litPart) | color(litColor);
-    Element dimEl = text(dimNamePart + padding) | color(dimColor);
-    if (isBold) {
-        litEl = litEl | bold;
-        dimEl = dimEl | bold;
-    }
-
-    Element result;
-    if (!cursorPart.empty()) {
-        Element cursorEl = text(cursorPart)
-            | color(theme::amber()) | bold | blink;
-        result = hbox({ litEl, cursorEl, dimEl });
-    } else {
-        result = hbox({ litEl, dimEl });
-    }
-    // Enforce exact width for alignment across rows
-    return result | size(WIDTH, EQUAL, static_cast<int>(nameWidth));
-}
+                                bool showCursor = false);
 
 // Columns a progress row occupies: " <icon> " + name + " " + status.
 inline int row_width_(std::size_t nameWidth, int iconW, int statusWidth) {
@@ -146,73 +58,7 @@ inline std::size_t fit_name_width_(std::size_t nameWidth, int iconW, int statusW
 }
 
 // Render a static snapshot of install progress to stdout
-void print_progress(std::span<const StatusEntry> entries) {
-    using namespace ftxui;
-
-    // Status label width for alignment
-    constexpr std::size_t statusWidth = 8;
-    constexpr int iconW = 3;   // " <icon> "
-
-    // Compute max name width for alignment
-    std::size_t nameWidth = 20;
-    for (auto& e : entries) {
-        nameWidth = std::max(nameWidth,
-                             static_cast<std::size_t>(layout::display_width(e.name)));
-    }
-    nameWidth += 2; // padding
-    nameWidth = fit_name_width_(nameWidth, iconW, static_cast<int>(statusWidth));
-
-    Elements rows;
-    for (auto& e : entries) {
-        auto pc = phase_color(e.phase);
-        auto icon = text(" " + phase_icon(e.phase) + " ") | color(pc);
-
-        Element nameEl;
-        std::string statusStr;
-
-        if (e.phase == Phase::Pending) {
-            nameEl = name_as_progress(e.name, 0.0f,
-                theme::dim_color(), theme::border_color(), nameWidth, false);
-            statusStr = "pending";
-        } else if (e.phase == Phase::Downloading || e.phase == Phase::Extracting ||
-                   e.phase == Phase::Installing || e.phase == Phase::Configuring) {
-            float pct = e.progress;
-            nameEl = name_as_progress(e.name, pct,
-                pc, theme::border_color(), nameWidth, true, true);
-            if (pct > 0.0f) {
-                int whole = static_cast<int>(pct * 100.0f);
-                int frac = static_cast<int>(pct * 1000.0f) % 10;
-                statusStr = std::to_string(whole) + "." + std::to_string(frac) + "%";
-            } else {
-                statusStr = phase_label(e.phase);
-            }
-        } else if (e.phase == Phase::Done) {
-            nameEl = name_as_progress(e.name, 1.0f,
-                theme::green(), theme::green(), nameWidth, true);
-            statusStr = "done";
-        } else { // Failed
-            nameEl = name_as_progress(e.name, 1.0f,
-                theme::red(), theme::red(), nameWidth, true);
-            statusStr = "failed";
-            if (!e.message.empty()) statusStr += ": " + e.message;
-        }
-
-        // Right-pad status for alignment
-        while (statusStr.size() < statusWidth) statusStr = " " + statusStr;
-
-        auto statusEl = text(" " + statusStr);
-        if (e.phase == Phase::Done) statusEl = statusEl | color(theme::green());
-        else if (e.phase == Phase::Failed) statusEl = statusEl | color(theme::red()) | bold;
-        else if (e.phase == Phase::Pending) statusEl = statusEl | color(theme::dim_color());
-        else statusEl = statusEl | color(theme::dim_color());
-
-        rows.push_back(hbox({ icon, nameEl, statusEl }));
-    }
-    layout::print_rows(std::move(rows),
-                       layout::fit_width(row_width_(nameWidth, iconW,
-                                                    static_cast<int>(statusWidth))));
-    std::println("");
-}
+void print_progress(std::span<const StatusEntry> entries);
 
 // ─── Download progress rendering ───
 // Data structure mirroring xim::TaskProgress (avoids circular dependency)
@@ -225,24 +71,9 @@ struct DownloadProgressEntry {
     bool success  { false };
 };
 
-std::string format_eta(int seconds) {
-    if (seconds < 0) return "";
-    if (seconds < 60) return std::to_string(seconds) + "s";
-    int min = seconds / 60;
-    int sec = seconds % 60;
-    return std::to_string(min) + "m" + std::to_string(sec) + "s";
-}
+std::string format_eta(int seconds);
 
-std::string format_speed(double bytesPerSec) {
-    if (bytesPerSec < 1024.0)
-        return std::to_string(static_cast<int>(bytesPerSec)) + " B/s";
-    if (bytesPerSec < 1024.0 * 1024.0) {
-        int kb = static_cast<int>(bytesPerSec / 1024.0 * 10.0);
-        return std::to_string(kb / 10) + "." + std::to_string(kb % 10) + " KB/s";
-    }
-    int mb = static_cast<int>(bytesPerSec / (1024.0 * 1024.0) * 10.0);
-    return std::to_string(mb / 10) + "." + std::to_string(mb % 10) + " MB/s";
-}
+std::string format_speed(double bytesPerSec);
 
 // Render download progress using FTXUI themed elements.
 // Called from a TUI refresh thread. Outputs to stdout.
@@ -253,164 +84,6 @@ int render_download_progress(std::span<const DownloadProgressEntry> progState,
                              std::size_t nameWidth,
                              double elapsedSec,
                              bool sizesReady,
-                             int prevLines = 0) {
-    using namespace ftxui;
-    const bool rewrite = palette::cursor_rewrite_allowed();
-    constexpr std::size_t statusWidth = 8;
-    constexpr int iconW = 6;   // "    <icon> "
-
-    // The caller measures the name column in bytes (core has no display-width
-    // table). Re-measure it here in columns, then fit it to the terminal.
-    std::size_t measured = 20;
-    for (auto& p : progState) {
-        measured = std::max(measured,
-                            static_cast<std::size_t>(layout::display_width(p.name)));
-    }
-    nameWidth = fit_name_width_(measured + 2, iconW, static_cast<int>(statusWidth));
-
-    Elements rows;
-    double totalBytes = 0.0;
-    double totalDownloaded = 0.0;
-
-    for (auto& p : progState) {
-        Element icon;
-        Element nameEl;
-        std::string statusStr;
-
-        totalBytes += p.totalBytes;
-
-        if (!p.started) {
-            icon = text("    " + std::string(theme::icon::pending) + " ")
-                | color(theme::dim_color());
-            nameEl = name_as_progress(p.name, 0.0f,
-                theme::dim_color(), theme::border_color(), nameWidth, false);
-            statusStr = "pending";
-        } else if (!p.finished) {
-            float pct = (p.totalBytes > 0)
-                ? static_cast<float>(p.downloadedBytes / p.totalBytes)
-                : 0.0f;
-            totalDownloaded += p.downloadedBytes;
-            icon = text("    " + std::string(theme::icon::downloading) + " ")
-                | color(theme::cyan());
-            nameEl = name_as_progress(p.name, pct,
-                theme::cyan(), theme::border_color(), nameWidth, true, rewrite);
-            if (pct > 0.0f) {
-                int whole = static_cast<int>(pct * 100.0f);
-                int frac = static_cast<int>(pct * 1000.0f) % 10;
-                statusStr = std::to_string(whole) + "." + std::to_string(frac) + "%";
-            } else {
-                statusStr = "0.0%";
-            }
-        } else if (p.success) {
-            totalDownloaded += p.totalBytes;
-            icon = text("    " + std::string(theme::icon::done) + " ")
-                | color(theme::green());
-            nameEl = name_as_progress(p.name, 1.0f,
-                theme::green(), theme::green(), nameWidth, true);
-            statusStr = "done";
-        } else {
-            totalDownloaded += p.totalBytes;
-            icon = text("    " + std::string(theme::icon::failed) + " ")
-                | color(theme::red()) | bold;
-            nameEl = name_as_progress(p.name, 1.0f,
-                theme::red(), theme::red(), nameWidth, true);
-            statusStr = "failed";
-        }
-
-        while (statusStr.size() < statusWidth) statusStr = " " + statusStr;
-
-        auto statusEl = text(" " + statusStr);
-        if (p.finished && p.success) statusEl = statusEl | color(theme::green());
-        else if (p.finished) statusEl = statusEl | color(theme::red()) | bold;
-        else if (!p.started) statusEl = statusEl | color(theme::dim_color());
-        else statusEl = statusEl | color(theme::dim_color());
-
-        rows.push_back(hbox({ icon, nameEl, statusEl }));
-    }
-
-    // Overall progress bar
-    // When some packages have unknown sizes (totalBytes==0 and not finished),
-    // byte-based progress is misleading. Fall back to finished_count/total_count.
-    float overallPct = 0.0f;
-    std::string speedStr;
-    std::string etaStr;
-
-    int totalCount = static_cast<int>(progState.size());
-    int finishedCount = 0;
-    bool allSizesKnown = true;
-    for (auto& p : progState) {
-        if (p.finished) ++finishedCount;
-        else if (p.totalBytes <= 0.0) allSizesKnown = false;
-    }
-
-    if (allSizesKnown && totalBytes > 0.0) {
-        // All sizes known: use byte-weighted progress
-        overallPct = static_cast<float>(totalDownloaded / totalBytes);
-        if (overallPct > 1.0f) overallPct = 1.0f;
-
-        if (elapsedSec > 0.5 && totalDownloaded > 0.0) {
-            double speed = totalDownloaded / elapsedSec;
-            speedStr = "  " + format_speed(speed);
-        }
-
-        if (overallPct > 0.01f && overallPct < 1.0f && elapsedSec > 1.0) {
-            double speed = totalDownloaded / elapsedSec;
-            if (speed > 0.0) {
-                double remainingBytes = totalBytes - totalDownloaded;
-                int remainingSec = static_cast<int>(remainingBytes / speed);
-                etaStr = "  ETA " + format_eta(remainingSec);
-            }
-        }
-    } else if (totalCount > 0) {
-        // Fallback: count-based progress
-        overallPct = static_cast<float>(finishedCount) / static_cast<float>(totalCount);
-    }
-
-    int pctWhole = static_cast<int>(overallPct * 100.0f);
-    int pctFrac = static_cast<int>(overallPct * 1000.0f) % 10;
-    std::string pctStr = std::to_string(pctWhole) + "." + std::to_string(pctFrac) + "%";
-
-    // The bar shares its line with the percentage, speed and ETA, so it gives
-    // ground first rather than pushing the line past the edge.
-    constexpr int kGaugeMax = 30;
-    const int gaugeTail = 4
-        + layout::display_width("  " + pctStr)
-        + layout::display_width(speedStr)
-        + layout::display_width(etaStr);
-
-    int width = layout::fit_width(
-        std::max(row_width_(nameWidth, iconW, static_cast<int>(statusWidth)),
-                 gaugeTail + kGaugeMax));
-    int gaugeW = std::clamp(width - gaugeTail, 8, kGaugeMax);
-
-    rows.push_back(text(""));
-    rows.push_back(hbox({
-        text("  " + std::string(theme::icon::arrow) + " ") | color(theme::cyan()),
-        gauge(overallPct) | size(WIDTH, EQUAL, gaugeW) | color(theme::cyan()),
-        text("  " + pctStr) | bold | color(theme::text_color()),
-        text(speedStr) | color(theme::cyan()),
-        text(etaStr) | color(theme::dim_color()),
-    }));
-    // erase_eol rather than padding: the frame is drawn over the previous
-    // one, and a trimmed line that is shorter than its predecessor would
-    // otherwise leave the old tail behind.
-    auto body = layout::render_to_string(vbox(std::move(rows)), width,
-                                         /*erase_eol=*/rewrite);
-
-    // Build single output buffer: cursor-up + content + clear trailing.
-    std::string output;
-    if (rewrite && prevLines > 0) {
-        output += "\033[" + std::to_string(prevLines) + "A\r";
-    }
-    output += body;
-    if (rewrite) output += "\033[J";
-
-    std::cout << output << std::flush;
-
-    // Every row fits the terminal (fit_name_width_ above), so rendered rows
-    // and physical lines are the same number and the cursor-up on the next
-    // frame lands where this frame started.
-    return static_cast<int>(std::ranges::count(body, '\n'));
-}
+                             int prevLines = 0);
 
 } // namespace xlings::ui
diff --git a/src/ui/selector.cpp b/src/ui/selector.cpp
new file mode 100644
index 00000000..6b897bf0
--- /dev/null
+++ b/src/ui/selector.cpp
@@ -0,0 +1,175 @@
+module;
+
+#include "ftxui/component/component.hpp"
+#include "ftxui/component/screen_interactive.hpp"
+#include "ftxui/dom/elements.hpp"
+#include "ftxui/screen/color.hpp"
+
+module xlings.ui;
+
+import std;
+import xlings.core.palette;
+
+namespace xlings::ui {
+
+std::optional<std::string>
+select_package(std::span<const std::pair<std::string, std::string>> items) {
+    using namespace ftxui;
+
+    if (items.empty()) return std::nullopt;
+    if (items.size() == 1) return std::string { items[0].first };
+
+    int selected { 0 };
+    bool confirmed { false };
+
+    std::vector<std::string> labels;
+    labels.reserve(items.size());
+    int nameW = 20;
+    for (auto& [name, desc] : items) {
+        nameW = std::max(nameW, layout::display_width(name));
+    }
+    for (auto& [name, desc] : items) {
+        labels.push_back(layout::pad_to_width(name, nameW) + " " + desc);
+    }
+
+    auto menu = Menu(&labels, &selected);
+    auto screen = ScreenInteractive::TerminalOutput();
+
+    auto component = CatchEvent(menu, [&](Event event) {
+        if (event == Event::Return) {
+            confirmed = true;
+            screen.Exit();
+            return true;
+        }
+        if (event == Event::Escape || event == Event::Character('q')) {
+            screen.Exit();
+            return true;
+        }
+        return false;
+    });
+
+    screen.Loop(Renderer(component, [&] {
+        return vbox({
+            text(" Select a package:") | theme::title(),
+            separator() | color(theme::border_color()),
+            component->Render() | vscroll_indicator | frame
+                | size(HEIGHT, LESS_THAN, 20),
+            separator() | color(theme::border_color()),
+            text(" \u2191\u2193 navigate  Enter select  Esc cancel") | theme::hint(),
+        }) | borderRounded | color(theme::border_color());
+    }));
+
+    if (confirmed && selected >= 0 && selected < (int)items.size()) {
+        return std::string { items[selected].first };
+    }
+    return std::nullopt;
+}
+
+std::optional<int>
+select_option(std::string_view title, std::span<const std::pair<std::string, std::string>> items, std::string_view done_label, int default_idx) {
+    using namespace ftxui;
+
+    if (items.empty()) return std::nullopt;
+
+    int selected = (default_idx >= 0 && default_idx < static_cast<int>(items.size()))
+        ? default_idx : 0;
+    bool confirmed { false };
+
+    // Build labels: "name   description"
+    std::vector<std::string> labels;
+    labels.reserve(items.size() + (done_label.empty() ? 0 : 1));
+    int nameW = 24;
+    for (auto& [name, desc] : items) {
+        nameW = std::max(nameW, layout::display_width(name));
+    }
+    for (auto& [name, desc] : items) {
+        labels.push_back(layout::pad_to_width(name, nameW) + desc);
+    }
+    if (!done_label.empty()) {
+        labels.push_back(std::string(done_label));
+    }
+
+    MenuOption menu_opt;
+    menu_opt.entries_option.transform = [](const EntryState& state) {
+        auto e = text((state.focused ? "> " : "  ") + state.label);
+        if (state.focused) {
+            e = e | bold | inverted;
+        } else {
+            e = e | color(theme::text_color());
+        }
+        return e;
+    };
+    auto menu = Menu(&labels, &selected, menu_opt);
+    auto screen = ScreenInteractive::Fullscreen();
+
+    auto component = CatchEvent(menu, [&](Event event) {
+        if (event == Event::Return) {
+            confirmed = true;
+            screen.Exit();
+            return true;
+        }
+        if (event == Event::Escape || event == Event::Character('q')) {
+            screen.Exit();
+            return true;
+        }
+        return false;
+    });
+
+    screen.Loop(Renderer(component, [&] {
+        auto box = vbox({
+            text(" " + std::string(title)) | theme::title(),
+            separator() | color(theme::border_color()),
+            component->Render() | vscroll_indicator | frame
+                | size(HEIGHT, LESS_THAN, 15),
+            separator() | color(theme::border_color()),
+            text(" \u2191\u2193 navigate  Enter select  Esc cancel") | theme::hint(),
+        }) | borderRounded | color(theme::border_color())
+           | size(WIDTH, LESS_THAN, 72);
+
+        return box | center;
+    }));
+
+    if (!confirmed) return std::nullopt;
+
+    // "done" item selected
+    if (!done_label.empty() && selected == static_cast<int>(items.size())) {
+        return -1; // sentinel for "done"
+    }
+
+    if (selected >= 0 && selected < static_cast<int>(items.size())) {
+        return selected;
+    }
+    return std::nullopt;
+}
+
+std::string read_line(std::string_view prompt) {
+    std::print("{}  {} {}", palette::fg(palette::cyan()), prompt, palette::off());
+    std::cout.flush();
+    std::string line;
+    std::getline(std::cin, line);
+    while (!line.empty() && (line.back() == ' ' || line.back() == '\n' || line.back() == '\r'))
+        line.pop_back();
+    while (!line.empty() && line.front() == ' ')
+        line.erase(line.begin());
+    return line;
+}
+
+bool confirm(std::string_view message, bool defaultYes) {
+    std::string prompt = defaultYes ? "[Y/n] " : "[y/N] ";
+    // Inline prompt (not an ftxui-rendered document), so it writes SGR
+    // directly — from the shared palette, which also turns it off under
+    // NO_COLOR / a pipe.
+    std::print("{}  {} {}{}{}{}{}",
+               palette::fg(palette::cyan()), theme::icon::arrow, palette::off(),
+               message,
+               palette::fg(palette::dim()), prompt, palette::off());
+    std::cout.flush();
+
+    std::string input;
+    if (!std::getline(std::cin, input)) return defaultYes;
+    if (input.empty()) return defaultYes;
+
+    return input[0] == 'y' || input[0] == 'Y';
+}
+
+}
diff --git a/src/ui/selector.cppm b/src/ui/selector.cppm
index e562b624..313f10ab 100644
--- a/src/ui/selector.cppm
+++ b/src/ui/selector.cppm
@@ -8,7 +8,6 @@ module;
 export module xlings.ui:selector;
 
 import std;
-import xlings.core.palette;
 import :theme;
 import :layout;
 
@@ -16,57 +15,7 @@ export namespace xlings::ui {
 
 // Interactive package selector from name-description pairs
 std::optional<std::string>
-select_package(std::span<const std::pair<std::string, std::string>> items) {
-    using namespace ftxui;
-
-    if (items.empty()) return std::nullopt;
-    if (items.size() == 1) return std::string { items[0].first };
-
-    int selected { 0 };
-    bool confirmed { false };
-
-    std::vector<std::string> labels;
-    labels.reserve(items.size());
-    int nameW = 20;
-    for (auto& [name, desc] : items) {
-        nameW = std::max(nameW, layout::display_width(name));
-    }
-    for (auto& [name, desc] : items) {
-        labels.push_back(layout::pad_to_width(name, nameW) + " " + desc);
-    }
-
-    auto menu = Menu(&labels, &selected);
-    auto screen = ScreenInteractive::TerminalOutput();
-
-    auto component = CatchEvent(menu, [&](Event event) {
-        if (event == Event::Return) {
-            confirmed = true;
-            screen.Exit();
-            return true;
-        }
-        if (event == Event::Escape || event == Event::Character('q')) {
-            screen.Exit();
-            return true;
-        }
-        return false;
-    });
-
-    screen.Loop(Renderer(component, [&] {
-        return vbox({
-            text(" Select a package:") | theme::title(),
-            separator() | color(theme::border_color()),
-            component->Render() | vscroll_indicator | frame
-                | size(HEIGHT, LESS_THAN, 20),
-            separator() | color(theme::border_color()),
-            text(" \u2191\u2193 navigate  Enter select  Esc cancel") | theme::hint(),
-        }) | borderRounded | color(theme::border_color());
-    }));
-
-    if (confirmed && selected >= 0 && selected < (int)items.size()) {
-        return std::string { items[selected].first };
-    }
-    return std::nullopt;
-}
+select_package(std::span<const std::pair<std::string, std::string>> items);
 
 // Generic option selector with title + description pairs (fullscreen, centered)
 // Returns selected index or nullopt if cancelled
@@ -75,119 +24,19 @@ std::optional<int>
 select_option(std::string_view title,
               std::span<const std::pair<std::string, std::string>> items,
               std::string_view done_label = "",
-              int default_idx = 0) {
-    using namespace ftxui;
-
-    if (items.empty()) return std::nullopt;
-
-    int selected = (default_idx >= 0 && default_idx < static_cast<int>(items.size()))
-        ? default_idx : 0;
-    bool confirmed { false };
-
-    // Build labels: "name   description"
-    std::vector<std::string> labels;
-    labels.reserve(items.size() + (done_label.empty() ? 0 : 1));
-    int nameW = 24;
-    for (auto& [name, desc] : items) {
-        nameW = std::max(nameW, layout::display_width(name));
-    }
-    for (auto& [name, desc] : items) {
-        labels.push_back(layout::pad_to_width(name, nameW) + desc);
-    }
-    if (!done_label.empty()) {
-        labels.push_back(std::string(done_label));
-    }
-
-    MenuOption menu_opt;
-    menu_opt.entries_option.transform = [](const EntryState& state) {
-        auto e = text((state.focused ? "> " : "  ") + state.label);
-        if (state.focused) {
-            e = e | bold | inverted;
-        } else {
-            e = e | color(theme::text_color());
-        }
-        return e;
-    };
-    auto menu = Menu(&labels, &selected, menu_opt);
-    auto screen = ScreenInteractive::Fullscreen();
-
-    auto component = CatchEvent(menu, [&](Event event) {
-        if (event == Event::Return) {
-            confirmed = true;
-            screen.Exit();
-            return true;
-        }
-        if (event == Event::Escape || event == Event::Character('q')) {
-            screen.Exit();
-            return true;
-        }
-        return false;
-    });
-
-    screen.Loop(Renderer(component, [&] {
-        auto box = vbox({
-            text(" " + std::string(title)) | theme::title(),
-            separator() | color(theme::border_color()),
-            component->Render() | vscroll_indicator | frame
-                | size(HEIGHT, LESS_THAN, 15),
-            separator() | color(theme::border_color()),
-            text(" \u2191\u2193 navigate  Enter select  Esc cancel") | theme::hint(),
-        }) | borderRounded | color(theme::border_color())
-           | size(WIDTH, LESS_THAN, 72);
-
-        return box | center;
-    }));
-
-    if (!confirmed) return std::nullopt;
-
-    // "done" item selected
-    if (!done_label.empty() && selected == static_cast<int>(items.size())) {
-        return -1; // sentinel for "done"
-    }
-
-    if (selected >= 0 && selected < static_cast<int>(items.size())) {
-        return selected;
-    }
-    return std::nullopt;
-}
+              int default_idx = 0);
 
 // Read a line from stdin with ANSI-colored prompt.
 //
 // Colors come from the shared palette rather than a dark-palette literal, so
 // the prompt follows the terminal background and goes quiet under NO_COLOR —
 // it is the one line the user has to read before they can answer it.
-std::string read_line(std::string_view prompt) {
-    std::print("{}  {} {}", palette::fg(palette::cyan()), prompt, palette::off());
-    std::cout.flush();
-    std::string line;
-    std::getline(std::cin, line);
-    while (!line.empty() && (line.back() == ' ' || line.back() == '\n' || line.back() == '\r'))
-        line.pop_back();
-    while (!line.empty() && line.front() == ' ')
-        line.erase(line.begin());
-    return line;
-}
+std::string read_line(std::string_view prompt);
 
 // Simple yes/no confirmation with styled prompt.
 //
 // Indented two columns like every panel above it. It used to start at column
 // 0, so the question sat outside the block it was asking about.
-bool confirm(std::string_view message, bool defaultYes) {
-    std::string prompt = defaultYes ? "[Y/n] " : "[y/N] ";
-    // Inline prompt (not an ftxui-rendered document), so it writes SGR
-    // directly — from the shared palette, which also turns it off under
-    // NO_COLOR / a pipe.
-    std::print("{}  {} {}{}{}{}{}",
-               palette::fg(palette::cyan()), theme::icon::arrow, palette::off(),
-               message,
-               palette::fg(palette::dim()), prompt, palette::off());
-    std::cout.flush();
-
-    std::string input;
-    if (!std::getline(std::cin, input)) return defaultYes;
-    if (input.empty()) return defaultYes;
-
-    return input[0] == 'y' || input[0] == 'Y';
-}
+bool confirm(std::string_view message, bool defaultYes);
 
 } // namespace xlings::ui
diff --git a/src/ui/table.cpp b/src/ui/table.cpp
new file mode 100644
index 00000000..40578b9d
--- /dev/null
+++ b/src/ui/table.cpp
@@ -0,0 +1,65 @@
+module;
+
+#include "ftxui/dom/elements.hpp"
+#include "ftxui/dom/table.hpp"
+#include "ftxui/screen/screen.hpp"
+#include "ftxui/screen/color.hpp"
+
+module xlings.ui;
+
+import std;
+
+namespace xlings::ui {
+
+void print_table(std::span<const std::string> headers,
+                 std::span<const std::vector<std::string>> rows) {
+    using namespace ftxui;
+
+    std::vector<std::vector<std::string>> tableData;
+    tableData.push_back(std::vector<std::string>(headers.begin(), headers.end()));
+    for (auto& row : rows) {
+        tableData.push_back(row);
+    }
+    int width = detail::fit_columns_(tableData);
+
+    auto table = Table(std::move(tableData));
+    table.SelectAll().Border(ROUNDED);
+    table.SelectRow(0).Decorate(bold);
+    table.SelectRow(0).Decorate(color(theme::cyan()));
+    table.SelectRow(0).SeparatorVertical(LIGHT);
+    table.SelectRow(0).BorderBottom(LIGHT);
+
+    layout::print_doc(table.Render(), width);
+    std::println("");
+}
+
+void print_search_results(
+    std::span<const std::pair<std::string, std::string>> results) {
+    using namespace ftxui;
+
+    if (results.empty()) return;
+
+    std::vector<std::vector<std::string>> tableData;
+    tableData.push_back({ "Package", "Description" });
+    for (auto& [name, desc] : results) {
+        tableData.push_back({ name, desc });
+    }
+    int width = detail::fit_columns_(tableData);
+
+    auto table = Table(std::move(tableData));
+    table.SelectAll().Border(ROUNDED);
+    table.SelectRow(0).Decorate(bold);
+    table.SelectRow(0).Decorate(color(theme::cyan()));
+    table.SelectRow(0).BorderBottom(LIGHT);
+
+    // Style package name column with magenta
+    for (int i = 1; i < static_cast<int>(results.size()) + 1; ++i) {
+        table.SelectCell(i, 0).Decorate(bold);
+        table.SelectCell(i, 0).Decorate(color(theme::magenta()));
+    }
+
+    layout::print_doc(table.Render(), width);
+    std::println("");
+}
+
+}
diff --git a/src/ui/table.cppm b/src/ui/table.cppm
index a459fefa..57cbea18 100644
--- a/src/ui/table.cppm
+++ b/src/ui/table.cppm
@@ -66,55 +66,10 @@ inline int fit_columns_(std::vector<std::vector<std::string>>& data) {
 
 // Print a formatted table with headers and rows
 void print_table(std::span<const std::string> headers,
-                 std::span<const std::vector<std::string>> rows) {
-    using namespace ftxui;
-
-    std::vector<std::vector<std::string>> tableData;
-    tableData.push_back(std::vector<std::string>(headers.begin(), headers.end()));
-    for (auto& row : rows) {
-        tableData.push_back(row);
-    }
-    int width = detail::fit_columns_(tableData);
-
-    auto table = Table(std::move(tableData));
-    table.SelectAll().Border(ROUNDED);
-    table.SelectRow(0).Decorate(bold);
-    table.SelectRow(0).Decorate(color(theme::cyan()));
-    table.SelectRow(0).SeparatorVertical(LIGHT);
-    table.SelectRow(0).BorderBottom(LIGHT);
-
-    layout::print_doc(table.Render(), width);
-    std::println("");
-}
+                 std::span<const std::vector<std::string>> rows);
 
 // Print search results as a table
 void print_search_results(
-    std::span<const std::pair<std::string, std::string>> results) {
-    using namespace ftxui;
-
-    if (results.empty()) return;
-
-    std::vector<std::vector<std::string>> tableData;
-    tableData.push_back({ "Package", "Description" });
-    for (auto& [name, desc] : results) {
-        tableData.push_back({ name, desc });
-    }
-    int width = detail::fit_columns_(tableData);
-
-    auto table = Table(std::move(tableData));
-    table.SelectAll().Border(ROUNDED);
-    table.SelectRow(0).Decorate(bold);
-    table.SelectRow(0).Decorate(color(theme::cyan()));
-    table.SelectRow(0).BorderBottom(LIGHT);
-
-    // Style package name column with magenta
-    for (int i = 1; i < static_cast<int>(results.size()) + 1; ++i) {
-        table.SelectCell(i, 0).Decorate(bold);
-        table.SelectCell(i, 0).Decorate(color(theme::magenta()));
-    }
-
-    layout::print_doc(table.Render(), width);
-    std::println("");
-}
+    std::span<const std::pair<std::string, std::string>> results);
 
 } // namespace xlings::ui
diff --git a/src/ui/theme.cpp b/src/ui/theme.cpp
new file mode 100644
index 00000000..add9ae6b
--- /dev/null
+++ b/src/ui/theme.cpp
@@ -0,0 +1,31 @@
+module;
+
+#include "ftxui/dom/elements.hpp"
+#include "ftxui/screen/color.hpp"
+
+module xlings.ui;
+
+import std;
+import xlings.platform;
+import xlings.core.glyph;
+import xlings.core.palette;
+
+namespace xlings::ui::theme {
+
+auto title()     -> Decorator { return ftxui::bold | ftxui::color(cyan()); }
+
+auto success()   -> Decorator { return ftxui::bold | ftxui::color(green()); }
+
+auto warning()   -> Decorator { return ftxui::bold | ftxui::color(amber()); }
+
+auto error()     -> Decorator { return ftxui::bold | ftxui::color(red()); }
+
+auto hint()      -> Decorator { return ftxui::dim | ftxui::color(dim_color()); }
+
+auto highlight() -> Decorator { return ftxui::bold | ftxui::color(magenta()); }
+
+auto label()     -> Decorator { return ftxui::color(dim_color()); }
+
+auto body()      -> Decorator { return ftxui::color(text_color()); }
+
+}
diff --git a/src/ui/theme.cppm b/src/ui/theme.cppm
index 60f82ac6..7fe008e9 100644
--- a/src/ui/theme.cppm
+++ b/src/ui/theme.cppm
@@ -6,7 +6,6 @@ module;
 export module xlings.ui:theme;
 
 import std;
-import xlings.platform;
 import xlings.core.glyph;
 import xlings.core.palette;
 
@@ -39,14 +38,14 @@ inline auto surface()      -> Color { return detail::rgb_(palette::surface()); }
 inline auto border_color() -> Color { return detail::rgb_(palette::border()); }
 
 // ─── Decorator helpers ─────────────────────────────────────
-auto title()     -> Decorator { return ftxui::bold | ftxui::color(cyan()); }
-auto success()   -> Decorator { return ftxui::bold | ftxui::color(green()); }
-auto warning()   -> Decorator { return ftxui::bold | ftxui::color(amber()); }
-auto error()     -> Decorator { return ftxui::bold | ftxui::color(red()); }
-auto hint()      -> Decorator { return ftxui::dim | ftxui::color(dim_color()); }
-auto highlight() -> Decorator { return ftxui::bold | ftxui::color(magenta()); }
-auto label()     -> Decorator { return ftxui::color(dim_color()); }
-auto body()      -> Decorator { return ftxui::color(text_color()); }
+auto title()     -> Decorator;
+auto success()   -> Decorator;
+auto warning()   -> Decorator;
+auto error()     -> Decorator;
+auto hint()      -> Decorator;
+auto highlight() -> Decorator;
+auto label()     -> Decorator;
+auto body()      -> Decorator;
 
 // ─── Icons ─────────────────────────────────────────────────
 //
diff --git a/tests/scripts/test_cli_spec_parity.py b/tests/scripts/test_cli_spec_parity.py
index 1d3d8222..a4c9b447 100644
--- a/tests/scripts/test_cli_spec_parity.py
+++ b/tests/scripts/test_cli_spec_parity.py
@@ -174,12 +174,27 @@ def forward(xlings, spec, env, failures):
     re.compile(r'\bcmdline::Option\("([a-zA-Z][\w-]*)"\)'),
 )
 
-PARSER_SOURCES = (
-    "src/core/subos.cppm",
-    "src/core/xself.cppm",
-    "src/cli.cppm",
+# The modules whose hand-written argv loops this pass reads.  Named by stem and
+# scanned on BOTH sides: a module's interface unit and its implementation unit
+# are one module, and an argv loop can live in either.  Naming `.cppm` alone
+# made this pass silently match zero literals once the loops moved to the
+# implementation units — the guard reported a pattern regression rather than the
+# file move that caused it.
+PARSER_MODULES = (
+    "src/core/subos",
+    "src/core/xself",
+    "src/cli",
 )
 
+
+def parser_sources():
+    found = []
+    for stem in PARSER_MODULES:
+        for ext in (".cppm", ".cpp"):
+            if (ROOT / (stem + ext)).exists():
+                found.append(stem + ext)
+    return found
+
 # Flags consumed and removed before any command sees them, or diagnostics-only
 # spellings that are deliberately undocumented.
 REVERSE_EXEMPT = {"--command-reference-json"}
@@ -196,7 +211,7 @@ def spec_flags(spec):
 def reverse(spec, failures):
     published = spec_flags(spec)
     checked = 0
-    for relative in PARSER_SOURCES:
+    for relative in parser_sources():
         text = (ROOT / relative).read_text()
         for pattern in LITERAL_PATTERNS:
             for match in pattern.finditer(text):
@@ -261,7 +276,7 @@ def main():
     if reverse_checked < 20:
         failures.append(f"reverse pass matched only {reverse_checked} parser "
                         f"literals -- LITERAL_PATTERNS no longer match the "
-                        f"argv loops in {', '.join(PARSER_SOURCES)}")
+                        f"argv loops in {', '.join(parser_sources())}")
 
     if failures:
         print("CommandSpec / parser parity failed:\n", file=sys.stderr)