From 263beff4b6d715c1c3ed86fbb60a62b6d0f7700e Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 08:52:20 +0800
Subject: [PATCH 01/19] docs: plan the module interface/implementation split,
 with the mechanism measured first

110 .cppm files carry both interface and implementation, so every body edit
changes the BMI and every importer recompiles. Average transitive downstream
is 10.7 modules; platform.cppm's is 63.

Before planning the edit, a throwaway probe established that mcpp orders
.cpp implementation units via P1689 dyndep and emits no BMI for them, and
that the three shapes this codebase actually needs all hold: a non-exported
helper declared in the interface and defined in the implementation unit is
callable from an exported template instantiated downstream; an extern
module-linkage global works the same way; export/default-args/constexpr have
to stay put.

Records the classification rules, the globals-ordering invariant, the
84.9%/15.1% free-function vs class-body split, the inline/LTO trade-off to
measure rather than assume, and main's cold-build baseline (68.85/55.14/64.12s).
---
 ...-08-13-module-interface-impl-separation.md | 136 ++++++++++++++++++
 1 file changed, 136 insertions(+)
 create mode 100644 .agents/plans/2026-08-13-module-interface-impl-separation.md

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.

From 826cc2165cc7685adfbf1eceb8daa3189c82d8f1 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 08:57:20 +0800
Subject: [PATCH 02/19] tools: a splitter for the interface/implementation
 migration, and the sizing analysis behind it

split.py transforms one .cppm that carries its own implementation into a
standard (.cppm interface, .cpp implementation) pair. It scrubs comments and
literals to a length-preserving mask, scans one brace level into items, and
classifies each: types/templates/constexpr/inline/const stay whole in the
interface; non-template function definitions and dynamically-initialised
namespace-scope variables split into a declaration plus a definition; #if
conditionals are emitted to both units so a definition never loses its guard.

Doing it with one tool rather than 110 hand edits is what makes the diff
reviewable -- every file is transformed by the same rules, and gcc verifies
the result.

Three facts established by probe before the rules were written:
- an implementation unit implicitly sees everything its interface declares,
  including non-exported namespace aliases, type aliases and types, so
  nothing has to be duplicated
- `export` must not appear in the implementation unit, and a default argument
  must appear only in the declaration
- namespace-scope `static` has to lose the keyword: internal linkage cannot
  span two units, and module linkage already keeps the name module-private

analyze.py sizes the job: 84.9% of the 46,253 lines sit outside class bodies.
---
 .agents/tools/module-split/analyze.py |  93 ++++++
 .agents/tools/module-split/cold.sh    |  25 ++
 .agents/tools/module-split/split.py   | 391 ++++++++++++++++++++++++++
 3 files changed, 509 insertions(+)
 create mode 100644 .agents/tools/module-split/analyze.py
 create mode 100644 .agents/tools/module-split/cold.sh
 create mode 100644 .agents/tools/module-split/split.py

diff --git a/.agents/tools/module-split/analyze.py b/.agents/tools/module-split/analyze.py
new file mode 100644
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/cold.sh b/.agents/tools/module-split/cold.sh
new file mode 100644
index 00000000..d4f9a11d
--- /dev/null
+++ b/.agents/tools/module-split/cold.sh
@@ -0,0 +1,25 @@
+#!/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"
+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/split.py b/.agents/tools/module-split/split.py
new file mode 100644
index 00000000..87ce0952
--- /dev/null
+++ b/.agents/tools/module-split/split.py
@@ -0,0 +1,391 @@
+#!/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 item: accumulate until ';' or '{' at paren depth 0
+        start = i
+        pdepth = 0
+        body = None
+        while i < n:
+            c = sc[i]
+            if c in '([':
+                pdepth += 1
+            elif c in ')]':
+                pdepth -= 1
+            elif pdepth == 0 and c == ';':
+                i += 1
+                break
+            elif pdepth == 0 and c == '{':
+                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())
+
+
+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 = 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 classify(it: Item, in_class: bool) -> str:
+    """Return 'stay' | 'namespace' | 'both' | 'split-fn' | 'split-var'."""
+    if it.kind == 'blank':
+        return 'stay'
+    if it.kind == 'preproc':
+        return 'both'                      # conditionals must bracket both units
+    h = head_norm(it.head)
+    if not h:
+        return 'stay'
+    if NS_HEAD.match(it.head):
+        return 'namespace' if it.body else 'stay'
+    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'
+    # `const` at namespace scope has internal linkage, so its definition
+    # cannot be moved to another unit without changing linkage.
+    if re.search(r'\bconst\b', h.split('(')[0]):
+        return 'stay'
+    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'
+        return 'split-fn'
+    # A variable definition — with an initialiser (`T x {..};`, `T x = ..;`)
+    # or default-constructed (`T x;`).  Both are definitions and both move.
+    if re.match(r'^(?:export\s+)?(?:static\s+)?[\w:<>,\s*&\[\]]+\w\s*(?:$|=|\[)', h.rstrip(';')):
+        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 Split:
+    def __init__(self):
+        self.iface: list[str] = []
+        self.impl: list[str] = []
+        self.moved = 0
+        self.moved_lines = 0
+
+
+def process_level(items: list[Item], out: Split, indent: str, in_class=False):
+    for it in items:
+        cls = classify(it, in_class)
+        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()
+            process_level(scan_items(inner), sub, indent)
+            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 == 'stay':
+            out.iface.append(it.raw)
+        elif cls == 'split-fn':
+            out.iface.append(it.lead + decl_from_def(it.head))
+            impl_head = strip_defaults(strip_static(strip_export(it.head)))
+            out.impl.append(impl_head.lstrip('\n') + it.body + it.tail)
+            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()
+            out.iface.append(it.lead + 'extern ' + decl + ';')
+            defn = bare + (it.body or '') + it.tail
+            out.impl.append(defn.strip() if defn.rstrip().endswith(';')
+                            else defn.strip() + ';')
+            out.moved += 1
+            out.moved_lines += (it.body or '').count('\n')
+        else:
+            out.iface.append(it.raw)
+
+
+PREAMBLE = re.compile(r'\A(?P<gmf>.*?)^export module (?P<mod>[\w.]+);',
+                      re.S | re.M)
+
+
+def split_file(path: str):
+    src = open(path).read()
+    m = PREAMBLE.search(src)
+    if not m:
+        return None, f'{path}: no `export module` declaration'
+    gmf, mod = m.group('gmf'), m.group('mod')
+    rest = src[m.end():]
+    # the import block that immediately follows the module declaration
+    im = re.match(r'\A((?:\s*(?:import [\w.:]+;|//[^\n]*|/\*.*?\*/))*\s*)',
+                  rest, re.S)
+    imports_blk = im.group(1) if im else ''
+    body = rest[len(imports_blk):]
+    imports = re.findall(r'^import [\w.:]+;', imports_blk, re.M)
+
+    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};' + imports_blk + ''.join(out.iface)
+    impl = (gmf if gmf.strip() else '') + f'module {mod};\n'
+    if imports:
+        impl += '\n' + '\n'.join(imports) + '\n'
+    impl += '\n' + '\n\n'.join(x.strip('\n') for x in out.impl if x.strip())
+    return (iface, impl.rstrip() + '\n', out.moved, out.moved_lines, mod), 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')
+    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)
+        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()

From 8365df015e87f458f4e6046917ea9c5f6ed9c6ca Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 09:23:46 +0800
Subject: [PATCH 03/19] refactor: separate module interface from implementation
 across 81 modules (phase 1)

Every .cppm carried its own function bodies, so an implementation edit changed
the BMI and recompiled every importer -- 10.7 modules on average, 64 TUs for
platform.cppm.

Phase 1 moves namespace-scope implementations into module implementation units
(`module M;` in a .cpp), which produce no BMI. 81 files, 779 entities, 26,606
body lines. The interface surface drops from 46,253 lines to 19,633 (42% of
what it was); that is the part every importer has to read.

Done by one tool (.agents/tools/module-split/split.py) rather than 81 hand
edits, so every file is transformed by the same rules and the diff is
reviewable. Five rules came out of compiler feedback rather than from reading
the standard first, and each names a real hazard:

- a deduced return type (`auto f() {...}` with no trailing `-> T`) cannot move:
  callers in other units would have nothing to deduce from
- an out-of-line member definition cannot be split, because a member function
  cannot be *declared* at namespace scope -- so the out-of-line `= default`
  assignment operators in xvm/types and libxpkg/types/type stay put
- an anonymous namespace moves WHOLE: internal linkage cannot span two units,
  and mirror/forms' constants proved it by vanishing from their callers
- `operator=` is a NAME, not an initialiser; reading the '=' as one turned
  four defaulted operators into `extern ... ::operator;`
- namespace-scope `static` loses the keyword: internal linkage cannot span two
  units either, and module linkage already keeps the name module-private

Verification: mcpp build clean, and mcpp test 38/38 binaries passed, 0 failed.

Not verified here, and CI has to carry it: 1,228 lines of the moved code sit
behind _WIN32/__APPLE__ guards that a Linux build never compiles.
---
 .agents/tools/module-split/incr.py     |   85 +
 .agents/tools/module-split/outline.py  |  223 ++
 .agents/tools/module-split/split.py    |  144 +-
 src/agent/agent.cpp                    |   97 +
 src/agent/agent.cppm                   |   75 +-
 src/agent/resources.cpp                |   24 +
 src/agent/resources.cppm               |    7 +-
 src/agent/text_renderer.cpp            |  206 ++
 src/agent/text_renderer.cppm           |  191 +-
 src/capabilities.cpp                   |   54 +
 src/capabilities.cppm                  |   32 +-
 src/cli.cpp                            | 1215 +++++++++
 src/cli.cppm                           | 1177 +--------
 src/cli/spec.cpp                       |  307 +++
 src/cli/spec.cppm                      |  285 +--
 src/core/cmdprocessor.cpp              |  292 +++
 src/core/cmdprocessor.cppm             |  277 +-
 src/core/common.cpp                    |   24 +
 src/core/common.cppm                   |   12 +-
 src/core/compact/git.cpp               |   99 +
 src/core/compact/git.cppm              |   86 +-
 src/core/compact/xself.cpp             |  110 +
 src/core/compact/xself.cppm            |   73 +-
 src/core/config.cpp                    |   61 +
 src/core/config.cppm                   |   46 +-
 src/core/entry_binary.cpp              |  103 +
 src/core/entry_binary.cppm             |   61 +-
 src/core/home_config.cpp               |   48 +
 src/core/home_config.cppm              |   38 +-
 src/core/i18n.cpp                      |   34 +
 src/core/i18n.cppm                     |   26 +-
 src/core/log.cpp                       |  104 +
 src/core/log.cppm                      |   91 +-
 src/core/mirror/adaptive.cpp           |  138 +
 src/core/mirror/adaptive.cppm          |  109 +-
 src/core/mirror/expand.cpp             |  160 ++
 src/core/mirror/expand.cppm            |  141 +-
 src/core/mirror/forms.cpp              |  122 +
 src/core/mirror/forms.cppm             |  110 +-
 src/core/mirror/registry.cpp           |  179 ++
 src/core/mirror/registry.cppm          |  159 +-
 src/core/profile.cpp                   |  365 +++
 src/core/profile.cppm                  |  338 +--
 src/core/subos.cpp                     | 1585 ++++++++++++
 src/core/subos.cppm                    | 1516 +----------
 src/core/subos/graphics.cpp            |  280 +++
 src/core/subos/graphics.cppm           |  211 +-
 src/core/subos/manifest.cpp            |  482 ++++
 src/core/subos/manifest.cppm           |  462 +---
 src/core/subos/sandbox.cpp             |  953 +++++++
 src/core/subos/sandbox.cppm            |  897 +------
 src/core/utf8.cpp                      |   24 +
 src/core/utf8.cppm                     |   16 +-
 src/core/utils.cpp                     |   85 +
 src/core/utils.cppm                    |   76 +-
 src/core/version_order.cpp             |   25 +
 src/core/version_order.cppm            |   17 +-
 src/core/xim/catalog.cpp               |  305 +++
 src/core/xim/catalog.cppm              |  267 +-
 src/core/xim/commands.cpp              | 1722 +++++++++++++
 src/core/xim/commands.cppm             | 1681 +------------
 src/core/xim/compatibility.cpp         |  140 ++
 src/core/xim/compatibility.cppm        |  120 +-
 src/core/xim/downloader.cpp            |  938 +++++++
 src/core/xim/downloader.cppm           |  904 +------
 src/core/xim/extract.cpp               |  302 +++
 src/core/xim/extract.cppm              |  279 +--
 src/core/xim/index.cpp                 |  165 ++
 src/core/xim/index.cppm                |  148 +-
 src/core/xim/index_cmd.cpp             |  229 ++
 src/core/xim/index_cmd.cppm            |  213 +-
 src/core/xim/indexfetch.cpp            |  676 +++++
 src/core/xim/indexfetch.cppm           |  637 +----
 src/core/xim/install_state.cpp         |   94 +
 src/core/xim/install_state.cppm        |   70 +-
 src/core/xim/installer.cpp             | 1966 +++++++++++++++
 src/core/xim/installer.cppm            | 1876 +-------------
 src/core/xim/inventory.cpp             |  612 +++++
 src/core/xim/inventory.cppm            |  570 +----
 src/core/xim/libxpkg/types/script.cpp  |  133 +
 src/core/xim/libxpkg/types/script.cppm |  114 +-
 src/core/xim/libxpkg/types/subos.cpp   |  109 +
 src/core/xim/libxpkg/types/subos.cppm  |   90 +-
 src/core/xim/payload.cpp               |  213 ++
 src/core/xim/payload.cppm              |  202 +-
 src/core/xim/repo.cpp                  |  712 ++++++
 src/core/xim/repo.cppm                 |  680 +----
 src/core/xim/resolver.cpp              |  242 ++
 src/core/xim/resolver.cppm             |  223 +-
 src/core/xself.cpp                     |  199 ++
 src/core/xself.cppm                    |  158 +-
 src/core/xself/clean.cpp               |   35 +
 src/core/xself/clean.cppm              |   25 +-
 src/core/xself/config.cpp              |   47 +
 src/core/xself/config.cppm             |   37 +-
 src/core/xself/doctor.cpp              | 3205 ++++++++++++++++++++++++
 src/core/xself/doctor.cppm             | 3142 +----------------------
 src/core/xself/init.cpp                |  315 +++
 src/core/xself/init.cppm               |  297 +--
 src/core/xself/install.cpp             |  785 ++++++
 src/core/xself/install.cppm            |  766 +-----
 src/core/xself/migrate.cpp             |   84 +
 src/core/xself/migrate.cppm            |   72 +-
 src/core/xself/repair.cpp              |  150 ++
 src/core/xself/repair.cppm             |  139 +-
 src/core/xself/uninstall.cpp           |  345 +++
 src/core/xself/uninstall.cppm          |  327 +--
 src/core/xself/update.cpp              |   79 +
 src/core/xself/update.cppm             |   70 +-
 src/core/xvm/bindings.cpp              |  565 +++++
 src/core/xvm/bindings.cppm             |  508 +---
 src/core/xvm/commands.cpp              |  759 ++++++
 src/core/xvm/commands.cppm             |  720 +-----
 src/core/xvm/db.cpp                    | 1045 ++++++++
 src/core/xvm/db.cppm                   | 1013 +-------
 src/core/xvm/errors.cpp                |  260 ++
 src/core/xvm/errors.cppm               |  250 +-
 src/core/xvm/groups.cpp                |  175 ++
 src/core/xvm/groups.cppm               |  158 +-
 src/core/xvm/inspect.cpp               |  615 +++++
 src/core/xvm/inspect.cppm              |  572 +----
 src/core/xvm/lock.cpp                  |   66 +
 src/core/xvm/lock.cppm                 |   56 +-
 src/core/xvm/owner.cpp                 |  120 +
 src/core/xvm/owner.cppm                |  106 +-
 src/core/xvm/registration.cpp          |  992 ++++++++
 src/core/xvm/registration.cppm         |  950 +------
 src/core/xvm/removal.cpp               |  395 +++
 src/core/xvm/removal.cppm              |  377 +--
 src/core/xvm/shim.cpp                  |  622 +++++
 src/core/xvm/shim.cppm                 |  587 +----
 src/core/xvm/switch_plan.cpp           |  237 ++
 src/core/xvm/switch_plan.cppm          |  217 +-
 src/core/xvm/types.cpp                 |   59 +
 src/core/xvm/types.cppm                |   38 +-
 src/interface.cpp                      |  199 ++
 src/interface.cppm                     |  171 +-
 src/libs/sha256.cpp                    |   33 +
 src/libs/sha256.cppm                   |   17 +-
 src/libs/tinyhttps.cpp                 |  337 +++
 src/libs/tinyhttps.cppm                |  323 +--
 src/platform.cpp                       |  418 +++
 src/platform.cppm                      |  365 +--
 src/platform/linux.cpp                 |  216 ++
 src/platform/linux.cppm                |  185 +-
 src/platform/macos.cpp                 |  195 ++
 src/platform/macos.cppm                |  162 +-
 src/platform/target.cpp                |   53 +
 src/platform/target.cppm               |   37 +-
 src/platform/unix.cpp                  |  230 ++
 src/platform/unix.cppm                 |  188 +-
 src/platform/windows.cpp               |  344 +++
 src/platform/windows.cppm              |  313 +--
 src/ui/banner.cpp                      |  237 ++
 src/ui/banner.cppm                     |  218 +-
 src/ui/info_panel.cpp                  |  498 ++++
 src/ui/info_panel.cppm                 |  470 +---
 src/ui/progress.cpp                    |  358 +++
 src/ui/progress.cppm                   |  342 +--
 src/ui/selector.cpp                    |  177 ++
 src/ui/selector.cppm                   |  158 +-
 src/ui/table.cpp                       |   67 +
 src/ui/table.cppm                      |   49 +-
 src/ui/theme.cpp                       |   31 +
 src/ui/theme.cppm                      |   16 +-
 165 files changed, 31506 insertions(+), 27429 deletions(-)
 create mode 100644 .agents/tools/module-split/incr.py
 create mode 100644 .agents/tools/module-split/outline.py
 create mode 100644 src/agent/agent.cpp
 create mode 100644 src/agent/resources.cpp
 create mode 100644 src/agent/text_renderer.cpp
 create mode 100644 src/capabilities.cpp
 create mode 100644 src/cli.cpp
 create mode 100644 src/cli/spec.cpp
 create mode 100644 src/core/cmdprocessor.cpp
 create mode 100644 src/core/common.cpp
 create mode 100644 src/core/compact/git.cpp
 create mode 100644 src/core/compact/xself.cpp
 create mode 100644 src/core/config.cpp
 create mode 100644 src/core/entry_binary.cpp
 create mode 100644 src/core/home_config.cpp
 create mode 100644 src/core/i18n.cpp
 create mode 100644 src/core/log.cpp
 create mode 100644 src/core/mirror/adaptive.cpp
 create mode 100644 src/core/mirror/expand.cpp
 create mode 100644 src/core/mirror/forms.cpp
 create mode 100644 src/core/mirror/registry.cpp
 create mode 100644 src/core/profile.cpp
 create mode 100644 src/core/subos.cpp
 create mode 100644 src/core/subos/graphics.cpp
 create mode 100644 src/core/subos/manifest.cpp
 create mode 100644 src/core/subos/sandbox.cpp
 create mode 100644 src/core/utf8.cpp
 create mode 100644 src/core/utils.cpp
 create mode 100644 src/core/version_order.cpp
 create mode 100644 src/core/xim/catalog.cpp
 create mode 100644 src/core/xim/commands.cpp
 create mode 100644 src/core/xim/compatibility.cpp
 create mode 100644 src/core/xim/downloader.cpp
 create mode 100644 src/core/xim/extract.cpp
 create mode 100644 src/core/xim/index.cpp
 create mode 100644 src/core/xim/index_cmd.cpp
 create mode 100644 src/core/xim/indexfetch.cpp
 create mode 100644 src/core/xim/install_state.cpp
 create mode 100644 src/core/xim/installer.cpp
 create mode 100644 src/core/xim/inventory.cpp
 create mode 100644 src/core/xim/libxpkg/types/script.cpp
 create mode 100644 src/core/xim/libxpkg/types/subos.cpp
 create mode 100644 src/core/xim/payload.cpp
 create mode 100644 src/core/xim/repo.cpp
 create mode 100644 src/core/xim/resolver.cpp
 create mode 100644 src/core/xself.cpp
 create mode 100644 src/core/xself/clean.cpp
 create mode 100644 src/core/xself/config.cpp
 create mode 100644 src/core/xself/doctor.cpp
 create mode 100644 src/core/xself/init.cpp
 create mode 100644 src/core/xself/install.cpp
 create mode 100644 src/core/xself/migrate.cpp
 create mode 100644 src/core/xself/repair.cpp
 create mode 100644 src/core/xself/uninstall.cpp
 create mode 100644 src/core/xself/update.cpp
 create mode 100644 src/core/xvm/bindings.cpp
 create mode 100644 src/core/xvm/commands.cpp
 create mode 100644 src/core/xvm/db.cpp
 create mode 100644 src/core/xvm/errors.cpp
 create mode 100644 src/core/xvm/groups.cpp
 create mode 100644 src/core/xvm/inspect.cpp
 create mode 100644 src/core/xvm/lock.cpp
 create mode 100644 src/core/xvm/owner.cpp
 create mode 100644 src/core/xvm/registration.cpp
 create mode 100644 src/core/xvm/removal.cpp
 create mode 100644 src/core/xvm/shim.cpp
 create mode 100644 src/core/xvm/switch_plan.cpp
 create mode 100644 src/core/xvm/types.cpp
 create mode 100644 src/interface.cpp
 create mode 100644 src/libs/sha256.cpp
 create mode 100644 src/libs/tinyhttps.cpp
 create mode 100644 src/platform.cpp
 create mode 100644 src/platform/linux.cpp
 create mode 100644 src/platform/macos.cpp
 create mode 100644 src/platform/target.cpp
 create mode 100644 src/platform/unix.cpp
 create mode 100644 src/platform/windows.cpp
 create mode 100644 src/ui/banner.cpp
 create mode 100644 src/ui/info_panel.cpp
 create mode 100644 src/ui/progress.cpp
 create mode 100644 src/ui/selector.cpp
 create mode 100644 src/ui/table.cpp
 create mode 100644 src/ui/theme.cpp

diff --git a/.agents/tools/module-split/incr.py b/.agents/tools/module-split/incr.py
new file mode 100644
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/outline.py b/.agents/tools/module-split/outline.py
new file mode 100644
index 00000000..9f587a68
--- /dev/null
+++ b/.agents/tools/module-split/outline.py
@@ -0,0 +1,223 @@
+#!/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,
+                   CONSTEXPR, TYPE_HEAD, NS_HEAD)
+
+CLASS_HEAD = re.compile(
+    r'^\s*(?:export\s+)?(?P<kw>struct|class)\s+(?P<name>\w+)'
+    r'(?P<rest>[^;{]*)$')
+
+
+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 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
+    o = s.find('(')
+    pre = head[:o]
+    m = None
+    for m in re.finditer(r'[\w~]+\s*$', pre):
+        pass
+    if not m:
+        return head
+    ret = pre[:m.start()]
+    name = pre[m.start():]
+    # 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 outline_class(cls_item: Item, ns: str, out_impl: list, stats: dict) -> str:
+    """Rewrite one class body; append out-of-line definitions 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 ':' in m.group('rest') or 'template' in cls_item.head:
+        # a base-class list is fine, but a template class is not: its members
+        # cannot be defined in another unit without explicit instantiation
+        if 'template' in cls_item.head:
+            return cls_item.raw
+    body = cls_item.body[1:-1]
+    nested = nested_type_names(body)
+    qual = f'{ns}::{cname}' if ns else cname
+    pieces = []
+    for it in scan_items(body):
+        keep = True
+        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]
+            )
+            if movable:
+                # in-class: declaration only, default arguments kept
+                pieces.append(it.lead + decl.rstrip() + ';')
+                out_impl.append(
+                    qualify(strip_defaults(decl), qual, nested, cname).strip()
+                    + init + it.body + it.tail)
+                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) -> str:
+    parts = []
+    for it in items:
+        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)
+            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))
+        else:
+            parts.append(it.raw)
+    return ''.join(parts)
+
+
+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)
+    if not stats['members']:
+        return 0, 0, f'{path}: no outlinable members'
+    if write:
+        open(path, 'w').write(preamble + new_body)
+        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// ── out-of-line class members '
+                     '─────────────────────────────────\n\n')
+            fh.write('\n\n'.join(x.strip('\n') for x in out_impl) + '\n')
+    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')
+    a = ap.parse_args()
+    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/split.py b/.agents/tools/module-split/split.py
index 87ce0952..29eb867a 100644
--- a/.agents/tools/module-split/split.py
+++ b/.agents/tools/module-split/split.py
@@ -109,6 +109,14 @@ def scan_items(text: str) -> list[Item]:
             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
@@ -175,10 +183,22 @@ 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 = scrub(h)
+    s = mask_operator(scrub(h))
     p = s.find('(')
     if p < 0:
         return False
@@ -189,36 +209,95 @@ def is_function_head(h: str) -> bool:
     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, in_class: bool) -> str:
     """Return 'stay' | 'namespace' | 'both' | 'split-fn' | 'split-var'."""
-    if it.kind == 'blank':
+    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):
-        return 'namespace' if it.body else 'stay'
+        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'
-    # `const` at namespace scope has internal linkage, so its definition
-    # cannot be moved to another unit without changing linkage.
-    if re.search(r'\bconst\b', h.split('(')[0]):
-        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.
-    if re.match(r'^(?:export\s+)?(?:static\s+)?[\w:<>,\s*&\[\]]+\w\s*(?:$|=|\[)', h.rstrip(';')):
+    # 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'
 
@@ -307,6 +386,11 @@ def process_level(items: list[Item], out: Split, indent: str, in_class=False):
                                 + 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':
@@ -332,35 +416,55 @@ def process_level(items: list[Item], out: Split, indent: str, in_class=False):
             out.iface.append(it.raw)
 
 
-PREAMBLE = re.compile(r'\A(?P<gmf>.*?)^export module (?P<mod>[\w.]+);',
-                      re.S | re.M)
+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)
 
 
-def split_file(path: str):
+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 = m.group('gmf'), m.group('mod')
+    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*(?:import [\w.:]+;|//[^\n]*|/\*.*?\*/))*\s*)',
-                  rest, re.S)
+    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):]
-    imports = re.findall(r'^import [\w.:]+;', imports_blk, re.M)
+    # 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};' + imports_blk + ''.join(out.iface)
+    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'
     impl += '\n' + '\n\n'.join(x.strip('\n') for x in out.impl if x.strip())
-    return (iface, impl.rstrip() + '\n', out.moved, out.moved_lines, mod), None
+    return (iface, impl.rstrip() + '\n', out.moved, out.moved_lines,
+            mod + part), None
 
 
 def main():
@@ -369,11 +473,15 @@ def main():
     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)
+        res, err = split_file(f, a.partition_import)
         if err:
             print(f'SKIP {err}')
             continue
diff --git a/src/agent/agent.cpp b/src/agent/agent.cpp
new file mode 100644
index 00000000..3cfa3c5a
--- /dev/null
+++ b/src/agent/agent.cpp
@@ -0,0 +1,97 @@
+// 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 {
+
+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";
+}
+
+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..31a95740 100644
--- a/src/agent/agent.cppm
+++ b/src/agent/agent.cppm
@@ -21,81 +21,12 @@ 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";
-}
+void print_overview(const SkillRegistry& reg);
 
 // 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;
-}
+bool print_skill(const SkillRegistry& reg, std::string_view name);
 
 // 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/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..0b2f941b 100644
--- a/src/agent/text_renderer.cppm
+++ b/src/agent/text_renderer.cppm
@@ -15,195 +15,6 @@ 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..678d7bc0
--- /dev/null
+++ b/src/capabilities.cpp
@@ -0,0 +1,54 @@
+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;
+}
+
+}
diff --git a/src/capabilities.cppm b/src/capabilities.cppm
index f4443a45..4d47cfa1 100644
--- a/src/capabilities.cppm
+++ b/src/capabilities.cppm
@@ -24,9 +24,7 @@ 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:
@@ -577,32 +575,6 @@ public:
     }
 };
 
-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..d4ad4fc2
--- /dev/null
+++ b/src/cli.cpp
@@ -0,0 +1,1215 @@
+module;
+
+#include "ftxui/component/event.hpp"
+#include "ftxui/component/mouse.hpp"
+
+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 {
+
+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);
+    }
+}
+
+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);
+}
+
+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;
+}
+
+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));
+}
+
+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;
+}
+
+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);
+}
+
+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;
+}
+
+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..9155ea87 100644
--- a/src/cli.cppm
+++ b/src/cli.cppm
@@ -39,336 +39,18 @@ 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);
-    }
-}
+static void dispatch_data_event(const DataEvent& e);
 
 // ─── 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);
-}
+static void handle_prompt(EventStream& stream, const PromptEvent& p);
 
 // 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;
-}
+xvm::Workspace parse_legacy_config_(const std::filesystem::path& configFile);
 
 // 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));
-}
+void generate_xlings_json_(const std::filesystem::path& dir, const xvm::Workspace& workspace);
 
 // Normalize a target-spec from positional args for the single-target
 // commands (remove/update/info — `use` has its own list-versions
@@ -388,236 +70,16 @@ void generate_xlings_json_(const std::filesystem::path& dir, const xvm::Workspac
 // 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;
-}
+                        std::string& out);
 
 // 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;
-            }
-        }
+int install_from_project_config_(EventStream& stream);
 
-        // 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);
-}
+void apply_global_opts_(const mcpplibs::cmdline::ParsedArgs& args);
 
 
 // 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;
-}
+int cmd_config_(const mcpplibs::cmdline::ParsedArgs& args, EventStream& stream);
 
 // `xlings profile list|commit|rollback` — generations of the active subos.
 //
@@ -630,627 +92,8 @@ int cmd_config_(const mcpplibs::cmdline::ParsedArgs& args, EventStream& stream)
 // 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);
-            }));
+int run_profile_(int argc, char* argv[], EventStream& stream);
 
-    // 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/cmdprocessor.cpp b/src/core/cmdprocessor.cpp
new file mode 100644
index 00000000..38cb52db
--- /dev/null
+++ b/src/core/cmdprocessor.cpp
@@ -0,0 +1,292 @@
+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 {
+
+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) {
+    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) {
+    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]");
+}
+
+}
diff --git a/src/core/cmdprocessor.cppm b/src/core/cmdprocessor.cppm
index f9f812ac..c33ec77a 100644
--- a/src/core/cmdprocessor.cppm
+++ b/src/core/cmdprocessor.cppm
@@ -67,281 +67,22 @@ private:
 // (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;
+std::filesystem::path find_xim_project_dir();
 
-    auto is_xim_project = [](const fs::path& dir) {
-        return fs::exists(dir / "xim") && fs::exists(dir / "xmake.lua");
-    };
+int xim_exec(const std::string& flags, int argc, char* argv[], int startIdx = 2);
 
-    // 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;
-        }
-    }
+int xvm_exec(const std::string& subcommand, int argc, char* argv[], int startIdx = 2);
 
-    // 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_xlings_json();
 
-std::filesystem::path find_project_legacy_xlings_lua() {
-    namespace fs = std::filesystem;
-    std::error_code ec;
+std::filesystem::path find_project_legacy_xlings_lua();
 
-    auto cwd = fs::current_path(ec);
-    if (ec) return {};
-    auto homeDir = Config::paths().homeDir;
+static int install_targets_from_list(const std::vector<std::string>& targets);
 
-    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);
-    }
+static int install_from_legacy_config_xlings_via_xim(const std::filesystem::path& cfg);
 
-    std::println("Tip: create <project>/.xlings.json with deps (preferred), or use config.xlings xim table, or run `xlings install <package>`");
-    return 0;
-}
+int install_from_project_config();
 
-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..1567c979 100644
--- a/src/core/common.cppm
+++ b/src/core/common.cppm
@@ -15,16 +15,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..42192745 100644
--- a/src/core/compact/xself.cppm
+++ b/src/core/compact/xself.cppm
@@ -212,84 +212,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..3be2fac1
--- /dev/null
+++ b/src/core/config.cpp
@@ -0,0 +1,61 @@
+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;
+}
+
+}
diff --git a/src/core/config.cppm b/src/core/config.cppm
index 779c4ca7..bfcad0a7 100644
--- a/src/core/config.cppm
+++ b/src/core/config.cppm
@@ -39,17 +39,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 +60,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>>;
 
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..95514877 100644
--- a/src/core/entry_binary.cppm
+++ b/src/core/entry_binary.cppm
@@ -44,45 +44,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 +67,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..f7623092 100644
--- a/src/core/home_config.cppm
+++ b/src/core/home_config.cppm
@@ -52,29 +52,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 +75,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..678d380a 100644
--- a/src/core/i18n.cppm
+++ b/src/core/i18n.cppm
@@ -165,31 +165,15 @@ constexpr MsgEntry gMessages_[] = {
 static_assert(sizeof(gMessages_) / sizeof(gMessages_[0]) == MSG_COUNT,
               "gMessages_ size must match Msg enum count");
 
-std::string gLang_;
+extern std::string gLang_;
 
-export void set_language(const std::string& lang) {
-    gLang_ = lang;
-}
+export void set_language(const std::string& lang);
 
-export [[nodiscard]] const std::string& language() {
-    if (gLang_.empty()) {
-        gLang_ = platform::get_system_language();
-        if (gLang_ != "zh") {
-            gLang_ = "en";
-        }
-    }
-    return gLang_;
-}
+export [[nodiscard]] const std::string& language();
 
-export [[nodiscard]] bool is_chinese() {
-    return language() == "zh";
-}
+export [[nodiscard]] bool is_chinese();
 
-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..4444627b
--- /dev/null
+++ b/src/core/log.cpp
@@ -0,0 +1,104 @@
+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;
+}
+
+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..704460d1 100644
--- a/src/core/log.cppm
+++ b/src/core/log.cppm
@@ -17,99 +17,44 @@ 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_;
+extern std::ofstream gFile_;
+extern bool gColor_;
 // 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);
 
 // 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(); }
+bool color_on_();
+bool color_on_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 colored_err_(palette::Rgb c, const char* text);
 
-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 timestamp_();
 
-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) {
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..9f5f872d 100644
--- a/src/core/mirror/adaptive.cppm
+++ b/src/core/mirror/adaptive.cppm
@@ -27,40 +27,7 @@ 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 +35,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 +56,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..8df43bc2 100644
--- a/src/core/mirror/expand.cppm
+++ b/src/core/mirror/expand.cppm
@@ -17,112 +17,20 @@ 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 +38,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..34ac2ac2 100644
--- a/src/core/mirror/registry.cppm
+++ b/src/core/mirror/registry.cppm
@@ -20,169 +20,16 @@ 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..97ac6aff
--- /dev/null
+++ b/src/core/profile.cpp
@@ -0,0 +1,365 @@
+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;
+}
+
+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;
+}
+
+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..289ee05e 100644
--- a/src/core/profile.cppm
+++ b/src/core/profile.cppm
@@ -26,24 +26,9 @@ 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;
-}
+std::string utc_now_iso_();
 
-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;
-}
+int next_gen_number_(const fs::path& gensDir);
 
 // 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`
@@ -52,86 +37,15 @@ int next_gen_number_(const fs::path& gensDir) {
 // 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;
-}
+std::uintmax_t dir_size_(const fs::path& dir);
 
-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);
+                  const std::string& reason);
 
-    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;
-}
-
-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 +60,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 +84,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 +101,15 @@ 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;
-}
+                                 const xvm::SubosWorkspace& workspace);
 
 // 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::set<std::string> collect_subos_references_(const fs::path& xlingsHome);
 
 // 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 +128,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/subos.cpp b/src/core/subos.cpp
new file mode 100644
index 00000000..793f608d
--- /dev/null
+++ b/src/core/subos.cpp
@@ -0,0 +1,1585 @@
+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,
+        });
+    }
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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..ed1f1f97 100644
--- a/src/core/subos.cppm
+++ b/src/core/subos.cppm
@@ -60,89 +60,19 @@ 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};
-}
+nlohmann::json read_config_json_(const fs::path& path);
 
-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));
-        }
-    }
+void write_config_json_(const fs::path& path, const nlohmann::json& json);
 
-    // 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));
-    }
+SubosInfo candidate_info_(const std::string& name, bool includeToolCount);
 
-    std::ranges::sort(view.candidates, {}, &SubosInfo::name);
-    return view;
-}
+export SubosCandidateView candidate_view(bool includeToolCount = true);
 
-export std::vector<SubosInfo> list_all() {
-    return candidate_view().candidates;
-}
+export std::vector<SubosInfo> list_all();
 
-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::string lowercase_name_(std::string_view name);
 
-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::size_t edit_distance_(std::string_view lhs, std::string_view rhs);
 
 struct CandidateResolution_ {
     std::string selected;
@@ -153,104 +83,14 @@ struct CandidateResolution_ {
 
 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)};
-    }
+        std::span<const SubosInfo> candidates);
 
-    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)};
-}
+CandidateResolution_ resolve_candidate_(std::string_view query);
 
 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()});
-}
+                      std::string_view hint = {});
 
 struct UseNameResolution_ {
     std::string selected;
@@ -258,71 +98,11 @@ struct UseNameResolution_ {
 };
 
 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};
-}
+                                    EventStream& stream);
 
 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,
-        });
-    }
-}
+                              const fs::path& targetDir);
 
 // ─────────────────────────────────────────────────────────────────────
 // Sandbox subos helpers (0.4.23 V4 — see .agents/docs/sandbox-v4-design.md)
@@ -361,31 +141,7 @@ void update_current_symlink_(EventStream& stream,
 // 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;
-}
+bool ensure_subos_info_(const fs::path& dir, std::string_view runtime);
 
 // Create a subos. V6: storage mode is a creation-time property
 // (`--storage image|tmpfs|shared`). Non-shared modes force sandbox
@@ -398,257 +154,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,9 +187,7 @@ 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;
-}
+bool is_pkg_spec_(const std::string& spec);
 
 // Parse `[<ns>:]<name>[@<ver>]` → {ns, name, ver}. Empty ns if absent;
 // empty ver if absent ("latest" semantics handled downstream).
@@ -684,257 +197,24 @@ 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;
-}
+PkgRef parse_pkg_spec_(const std::string& spec);
 
 // 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;
-}
+               EventStream& stream);
 
 // 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;
-}
+fs::path locate_base_pkg_(const PkgRef& ref);
 
 } // 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:
 //
@@ -1233,35 +513,7 @@ inline void apply_subos_env_(const std::string& name) {
 
 // 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;
-}
+int use_global(const std::string& name, EventStream& stream);
 
 // Internal — not exported. Powers the hidden `--shell <kind>` flag,
 // kept available for tests and power users that want eval-able output
@@ -1299,126 +551,13 @@ int use_global(const std::string& name, EventStream& stream) {
 //     `--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()});
-}
+                               EventStream& stream);
 
-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;
-}
+void warn_storage_dormant_on_shell_(const std::string& name);
 
 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;
-}
+                          EventStream& stream);
 
 
 
@@ -1448,243 +587,18 @@ 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;
-    }
+export int use(const std::string& name, EventStream& stream);
 
-    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;
-    }
+export int remove(const std::string& name, EventStream& stream);
 
-    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};
-}
+export std::optional<SubosInfo> info(const std::string& name);
 
-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;
-}
+int run_list_(EventStream& stream);
 
 // The graphics section of `xlings subos info`.
 //
@@ -1698,374 +612,10 @@ int run_list_(EventStream& stream) {
 //
 // 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;
-}
-
-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;
-        }
+nlohmann::json graphics_fields_(const fs::path& subosDir);
 
-        auto resolved = resolve_use_name_(name, stream);
-        if (resolved.selected.empty()) return resolved.exitCode;
-        name = std::move(resolved.selected);
+int run_info_(const std::string& name, EventStream& stream);
 
-        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..5478bcca
--- /dev/null
+++ b/src/core/subos/graphics.cpp
@@ -0,0 +1,280 @@
+// 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";
+}
+
+}
diff --git a/src/core/subos/graphics.cppm b/src/core/subos/graphics.cppm
index b0be7f36..9d872c6f 100644
--- a/src/core/subos/graphics.cppm
+++ b/src/core/subos/graphics.cppm
@@ -192,57 +192,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 +278,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 ─────────────────────────────────────────────────────
 //
@@ -444,26 +329,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 +342,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/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..772335bb 100644
--- a/src/core/subos/manifest.cppm
+++ b/src/core/subos/manifest.cppm
@@ -95,35 +95,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 +129,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 +137,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 +160,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 +185,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 +196,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 +217,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 +262,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 +287,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 +296,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 +318,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 +357,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 +456,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..a4b6a0d0
--- /dev/null
+++ b/src/core/subos/sandbox.cpp
@@ -0,0 +1,953 @@
+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__)
+
+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);
+}
+
+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;
+}
+
+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());
+}
+
+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, 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;
+}
+
+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;
+}
+
+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");
+}
+
+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) };
+}
+
+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;
+}
+
+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, const fs::path& mountpoint, bool gpu, 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;
+}
+
+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;
+}
+
+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..4e8763be 100644
--- a/src/core/subos/sandbox.cppm
+++ b/src/core/subos/sandbox.cppm
@@ -58,14 +58,7 @@ 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(); }
-}
+nlohmann::json read_config_json_(const fs::path& path);
 
 // ── Storage mode (V6) ──────────────────────────────────────────────
 // Storage isolation mode for sandbox data. Set at subos creation time
@@ -90,14 +83,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
@@ -113,34 +99,8 @@ export StorageMode read_storage_mode_(const fs::path& subos_dir) {
 // (= /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);
-}
+std::string make_etc_passwd_(const std::string& user, uid_t uid, gid_t gid);
+std::string make_etc_group_(const std::string& user, gid_t gid);
 inline constexpr std::string_view kEtcHosts =
     "127.0.0.1 localhost\n::1 localhost\n";
 inline constexpr std::string_view kEtcNsswitch =
@@ -216,122 +176,26 @@ inline void write_sandbox_rc_(const fs::path& home_dir) {
 // 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);
-}
+                        uid_t uid, gid_t gid);
 
 #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;
-}
+export bool is_mounted_(const fs::path& path);
 
 // 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;
-}
+                 const std::string& user = {});
 
 // 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());
-}
+export int unmount_image_(const fs::path& mountpoint);
 
 
 // ─────────────────────────────────────────────────────────────────────
@@ -359,89 +223,7 @@ export int unmount_image_(const fs::path& mountpoint) {
 //
 // 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()));
-}
+locate_proot_(const fs::path& home_dir);
 
 // ── Unified bind list (shared by proot + bwrap) ──────────────────────
 //
@@ -468,67 +250,7 @@ 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;
-}
+               const fs::path& mountpoint = {});
 
 // Build proot argv from unified bind list. When `cmd` is non-empty, ends
 // in `<shell> -c <cmd>` for non-interactive single-command exec (M3);
@@ -539,34 +261,7 @@ build_proot_argv_(const fs::path& proot_bin,
                   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;
-}
+                  const std::string& cmd = "");
 
 // ── bwrap backend (V5) ────────────────────────────────────────────────
 
@@ -580,78 +275,21 @@ build_proot_argv_(const fs::path& proot_bin,
 // 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");
-}
+locate_bwrap_(const fs::path& home_dir);
 
 // 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) };
-}
+probe_bwrap_(const fs::path& bwrap_bin);
 
 // 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;
-}
+                                         const fs::path& bin);
 
 // Build bwrap argv from unified bind list. Uses targeted --ro-bind
 // instead of `--ro-bind / /` to match proot's security profile
@@ -668,54 +306,7 @@ build_bwrap_argv_(const fs::path& bwrap_bin,
                   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;
-}
+                  const std::string& cmd = "");
 
 // ── Backend detection + auto-install ─────────────────────────────────
 
@@ -729,35 +320,11 @@ struct BackendInfo {
 // 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");
-}
+void maybe_show_bwrap_hint_(const fs::path& subos_dir);
 
 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;
-}
+                const fs::path& subos_dir = {});
 
 // Should we even try to fetch a sandbox backend for this host? Answered from
 // the on-disk index, with no network access.
@@ -780,48 +347,9 @@ detect_backend_(const fs::path& home_dir,
 // 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);
-}
+std::optional<std::string> backend_target_unavailable_();
 
-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 +361,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..5572769b
--- /dev/null
+++ b/src/core/xim/catalog.cpp
@@ -0,0 +1,305 @@
+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);
+}
+
+}
diff --git a/src/core/xim/catalog.cppm b/src/core/xim/catalog.cppm
index dba03c71..2294a64a 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
 
@@ -862,12 +633,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..4ff8e92b 100644
--- a/src/core/xim/commands.cppm
+++ b/src/core/xim/commands.cppm
@@ -40,62 +40,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 +52,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 +73,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 +90,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 +109,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 +130,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..c2e6633c 100644
--- a/src/core/xim/downloader.cppm
+++ b/src/core/xim/downloader.cppm
@@ -21,23 +21,13 @@ 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 +45,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 +69,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 +104,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 +114,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 +133,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 +141,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 +178,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..a47c1031
--- /dev/null
+++ b/src/core/xim/extract.cpp
@@ -0,0 +1,302 @@
+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";
+}
+
+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; }
+
+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..a5fadf3e 100644
--- a/src/core/xim/extract.cppm
+++ b/src/core/xim/extract.cppm
@@ -72,60 +72,15 @@ 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};
-}
+check_safe_pathname_(const char* raw);
 
-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 path_from_wide_(const wchar_t* raw);
 
-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_pathname_(archive_entry* 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 entry_hardlink_(archive_entry* entry);
 
-std::string libarchive_error_(struct archive* a) {
-    if (auto* msg = ::archive_error_string(a); msg && *msg) {
-        return msg;
-    }
-    return "unknown libarchive error";
-}
+std::string libarchive_error_(struct archive* a);
 
 // User/group lookup callbacks for archive_write_disk that always return
 // 0 (root). Wired into archive_write_disk_set_user_lookup so libarchive
@@ -135,235 +90,23 @@ std::string libarchive_error_(struct archive* a) {
 // 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; }
+la_int64_t const_root_lookup_uid_(void*, const char*, la_int64_t);
+la_int64_t const_root_lookup_gid_(void*, const char*, la_int64_t);
 
 // 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)});
-        }
-    }
-}
+copy_entry_data_(struct archive* src, struct archive* 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
-    });
-}
+void ensure_archive_locale_();
 
 } // 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..a97ae0b4
--- /dev/null
+++ b/src/core/xim/index.cpp
@@ -0,0 +1,165 @@
+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;
+}
+
+}
diff --git a/src/core/xim/index.cppm b/src/core/xim/index.cppm
index 7b100e7f..ce84eef4 100644
--- a/src/core/xim/index.cppm
+++ b/src/core/xim/index.cppm
@@ -16,63 +16,14 @@ 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;
-    }
-}
+int type_to_int(xpkg::PackageType t);
+
+xpkg::PackageType int_to_type(int v);
 
 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 +32,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_
 
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..d9517107 100644
--- a/src/core/xim/index_cmd.cppm
+++ b/src/core/xim/index_cmd.cppm
@@ -34,225 +34,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..75cd9ebe
--- /dev/null
+++ b/src/core/xim/indexfetch.cpp
@@ -0,0 +1,676 @@
+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_ {
+
+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;
+}
+
+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;
+}
+
+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) {
+    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);
+}
+
+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;
+}
+
+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);
+    }
+}
+
+}
diff --git a/src/core/xim/indexfetch.cppm b/src/core/xim/indexfetch.cppm
index 884ab064..eaad950a 100644
--- a/src/core/xim/indexfetch.cppm
+++ b/src/core/xim/indexfetch.cppm
@@ -194,19 +194,10 @@ 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 index_repo_name_();
+std::string index_tag_();
 
-std::string lower_hex_(std::string s) {
-    for (auto& c : s) c = static_cast<char>(std::tolower((unsigned char)c));
-    return s;
-}
+std::string lower_hex_(std::string s);
 
 // Download the first working candidate URL into destFile, trying each candidate
 // explicitly and continuing past ANY failure — including HTTP 404. This differs
@@ -217,42 +208,7 @@ std::string lower_hex_(std::string s) {
 // 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;
-}
+                                 std::string_view wantSha256);
 
 // 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
@@ -261,18 +217,7 @@ 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;
-}
+BaseOverride resolve_base_();
 
 // Obtain `filename` into `dest`: local-dir copy, or remote (base override, else
 // the given remoteUrls). Verifies sha256 when wantSha is non-empty.
@@ -281,303 +226,42 @@ BaseOverride resolve_base_() {
 // 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);
-}
+                        const BaseOverride* forced = nullptr);
 
 // #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;
-}
+BaseOverride base_override_for_(const ArtifactSource& src);
 
 } // 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;
-}
+std::string describe_requirement_(const IndexSnapshot& s);
 
 }  // 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 +269,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().
@@ -637,14 +282,7 @@ inline std::map<std::string, std::map<std::string, std::string>>& client_latest_
 // 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;
-}
+std::string client_latest_for(std::string_view consumer, const ArtifactSource* custom);
 
 // Cached fetch of the COMBINED pointer file (xim-index-pointers.json): ONE raw
 // fetch per process covering ALL indexes (main + subs). One fetch (vs one per
@@ -652,194 +290,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 +309,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..f83f34f6
--- /dev/null
+++ b/src/core/xim/install_state.cpp
@@ -0,0 +1,94 @@
+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));
+}
+
+}
diff --git a/src/core/xim/install_state.cppm b/src/core/xim/install_state.cppm
index 74cd0fd7..56abe983 100644
--- a/src/core/xim/install_state.cppm
+++ b/src/core/xim/install_state.cppm
@@ -115,25 +115,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 +141,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 +155,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..5834e9e8
--- /dev/null
+++ b/src/core/xim/installer.cpp
@@ -0,0 +1,1966 @@
+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;
+}
+
+}
+
+}
diff --git a/src/core/xim/installer.cppm b/src/core/xim/installer.cppm
index 4bfb3934..929bd227 100644
--- a/src/core/xim/installer.cppm
+++ b/src/core/xim/installer.cppm
@@ -112,89 +112,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 +160,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 +168,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 +178,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 +187,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 +197,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 +234,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 +273,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 +291,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::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::string effective_store_name_(std::string_view namespaceName, std::string_view name);
 
-std::filesystem::path xpkg_snapshot_file_(const std::filesystem::path& installDir) {
-    return installDir / ".xpkg.lua";
-}
+std::string effective_store_name_(const PlanNode& node);
 
-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()));
-    }
+std::string effective_store_name_(const PackageMatch& match);
 
-    fs::create_directories(installDir, ec);
-    if (ec) {
-        return std::unexpected(
-            std::format("failed to create install dir for xpkg snapshot: {}", ec.message()));
-    }
+std::string version_namespace_(std::string_view namespaceName);
 
-    auto snapshotFile = xpkg_snapshot_file_(installDir);
-    ec.clear();
-    if (fs::exists(snapshotFile, ec)) {
-        ec.clear();
-        if (fs::equivalent(sourcePkgFile, snapshotFile, ec) && !ec) return {};
-    }
+std::string plan_key_(const PlanNode& node);
 
-    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 data_root_for_(const std::filesystem::path& targetRoot);
+
+std::filesystem::path runtime_dir_(const PlanNode& node,
+                                   const std::filesystem::path& fallbackDataDir);
+
+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);
 
 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 +346,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,147 +362,14 @@ 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);
-    }
+        std::string_view preferredMirror);
 
-    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 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;
-    };
-
-    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;
-    }
+                              const std::filesystem::path& installDir);
 
-    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_;
@@ -1329,32 +393,9 @@ public:
     }
 };
 
-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 +413,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 +437,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 +450,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 +473,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_
 
diff --git a/src/core/xim/inventory.cpp b/src/core/xim/inventory.cpp
new file mode 100644
index 00000000..9d47dec0
--- /dev/null
+++ b/src/core/xim/inventory.cpp
@@ -0,0 +1,612 @@
+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);
+}
+
+}
diff --git a/src/core/xim/inventory.cppm b/src/core/xim/inventory.cppm
index 12a187ef..b890365b 100644
--- a/src/core/xim/inventory.cppm
+++ b/src/core/xim/inventory.cppm
@@ -60,14 +60,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 {
 
@@ -217,32 +210,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 +239,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 +270,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 +302,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 +319,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 +329,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 +337,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..9c5ebaa8 100644
--- a/src/core/xim/libxpkg/types/script.cppm
+++ b/src/core/xim/libxpkg/types/script.cppm
@@ -14,120 +14,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..40bd9760 100644
--- a/src/core/xim/libxpkg/types/subos.cppm
+++ b/src/core/xim/libxpkg/types/subos.cppm
@@ -34,96 +34,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/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..9ac32e51 100644
--- a/src/core/xim/payload.cppm
+++ b/src/core/xim/payload.cppm
@@ -26,37 +26,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 +39,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 +70,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 +84,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 +99,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..1f6616a2 100644
--- a/src/core/xim/repo.cppm
+++ b/src/core/xim/repo.cppm
@@ -18,151 +18,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 +49,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 +69,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 +89,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 +111,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..a172ebf2 100644
--- a/src/core/xim/resolver.cppm
+++ b/src/core/xim/resolver.cppm
@@ -18,20 +18,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 +43,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 +63,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..59f891eb 100644
--- a/src/core/xself.cppm
+++ b/src/core/xself.cppm
@@ -46,162 +46,8 @@ 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;
-}
+static int cmd_help(EventStream& stream);
 
-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..f281d444 100644
--- a/src/core/xself/clean.cppm
+++ b/src/core/xself/clean.cppm
@@ -10,29 +10,6 @@ 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..8f5d8ea9 100644
--- a/src/core/xself/config.cppm
+++ b/src/core/xself/config.cppm
@@ -10,41 +10,6 @@ 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..c17234d6
--- /dev/null
+++ b/src/core/xself/doctor.cpp
@@ -0,0 +1,3205 @@
+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;
+}
+
+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");
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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)));
+            }
+        }
+    }
+}
+
+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();
+        }
+    }
+}
+
+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)));
+        }
+    }
+}
+
+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));
+        }
+    }
+}
+
+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));
+        }
+    }
+}
+
+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));
+        }
+    }
+}
+
+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..e5fb212f 100644
--- a/src/core/xself/doctor.cppm
+++ b/src/core/xself/doctor.cppm
@@ -294,49 +294,9 @@ 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;
-}
+std::string shim_filename_(const std::string& name);
 
-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;
-}
+DoctorState load_state_();
 
 // Does this payload ship ANY executable?
 //
@@ -348,30 +308,7 @@ DoctorState load_state_() {
 //
 // 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");
-}
+bool payload_has_any_executable_(const fs::path& dir);
 
 // An alias as the runtime would actually read it.
 //
@@ -384,17 +321,7 @@ bool payload_has_any_executable_(const fs::path& dir) {
 //   - ${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);
-}
+                           const std::string& homeStr);
 
 // ── detection ────────────────────────────────────────────────────────
 
@@ -417,11 +344,7 @@ 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;
-}
+fs::path audit_payload_dir_(const xim::PackageMatch& match);
 
 // The command that repairs a broken entry, or nothing.
 //
@@ -439,12 +362,7 @@ 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;
-}
+                   const CoordinateProbe& probe);
 
 // Would activating this release be undone by the repair that runs next?
 //
@@ -469,48 +387,7 @@ owning_coordinate_(const xvm::VersionDB& db,
 // 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;
-}
+                                 const std::string& rootVersion);
 
 // D1–D5 over the active subos's `subos_info`.
 //
@@ -525,285 +402,7 @@ std::string activation_conflict_(const DoctorState& st,
 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;
-}
+                                            const std::string& subosName);
 
 // Is the file every shim dispatches through the xlings this home says it runs?
 //
@@ -826,1273 +425,10 @@ std::vector<Finding> detect_subos_manifest_(const xvm::VersionDB& db,
 //
 // 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;
-}
+std::vector<Finding> detect_entry_binary_(const DoctorState& st);
 
 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 ───────────────────────────────────────────────────────────
 
@@ -2123,167 +459,7 @@ struct RepairReport {
 // 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)));
-            }
-        }
-    }
-}
+                   RepairReport& out);
 
 // The three state-file repairs, in an order that matters.
 //
@@ -2292,155 +468,7 @@ void repair_local_(const DoctorState& st, const Scan& scan,
 // 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();
-        }
-    }
-}
+void repair_state_(RepairReport& out);
 
 // Other subos: the deletions doctor could already describe exactly.
 //
@@ -2449,54 +477,7 @@ void repair_state_(RepairReport& out) {
 // 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)));
-        }
-    }
-}
+void repair_other_subos_(const DoctorState& st, RepairReport& out);
 
 // ── the payload ladder ───────────────────────────────────────────────
 
@@ -2511,92 +492,7 @@ void repair_other_subos_(const DoctorState& st, RepairReport& out) {
 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));
-        }
-    }
-}
+                      const std::function<void(std::string_view)>& onStep = {});
 
 // Activate what is installed and inactive, by running `use`.
 //
@@ -2619,41 +515,7 @@ void repair_payloads_(const DoctorState& st, const Scan& scan,
 // 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));
-        }
-    }
-}
+                      RepairReport& out);
 
 // Re-run the install of a payload whose own stamp records that it failed.
 //
@@ -2670,49 +532,7 @@ void repair_inactive_(const Scan& scan, const std::string& client,
 // 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));
-        }
-    }
-}
+                        const std::function<void(std::string_view)>& onStep = {});
 
 // The last rung: drop a registration that is provably dead.
 //
@@ -2736,94 +556,7 @@ void repair_incomplete_(const Scan& scan, const CommandRunner& run,
 // 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);
-    }
-}
+                               RepairReport& out);
 
 // ── render ───────────────────────────────────────────────────────────
 
@@ -2843,486 +576,10 @@ 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;
-}
+Counts count_(const Scan& scan);
 
 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()});
-}
+             bool dryRun, bool verbose, EventStream& stream);
 
 // ── the command ──────────────────────────────────────────────────────
 
@@ -3331,365 +588,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..a9e4387c
--- /dev/null
+++ b/src/core/xself/init.cpp
@@ -0,0 +1,315 @@
+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));
+}
+
+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));
+}
+
+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;
+}
+
+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));
+}
+
+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..b14286a1 100644
--- a/src/core/xself/init.cppm
+++ b/src/core/xself/init.cppm
@@ -45,184 +45,33 @@ 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;
+                               const fs::path& pkg_root);
 
-    for (auto name : SHIM_NAMES_BASE) {
-        auto dst = target_bin_dir / (std::string(name) + ext);
-        if (create_shim(shim_src, dst) == LinkResult::Failed) ++failures;
-    }
+static void ensure_parent_dirs_(const fs::path& file);
 
-    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));
-}
+static void write_if_missing_(const fs::path& path, std::string_view 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));
-}
+static void ensure_subos_manifest_(const fs::path& subos_dir);
 
 // 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;
-}
+static std::string extract_profile_version_(std::string_view text);
 
 // Profile-aware writer. Behavior:
 //
@@ -238,24 +87,7 @@ static std::string extract_profile_version_(std::string_view text) {
 // 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));
-}
+                                      std::string_view target_version);
 
 // Read-modify-writes `<home>/.xlings.json` without taking the state lock
 // itself. Both callers reach it through `ensure_home_layout`, and the only
@@ -263,117 +95,14 @@ static void write_or_upgrade_profile_(const fs::path& path,
 // 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;
-        }
-    }
+static void ensure_home_config_defaults_(const fs::path& home_dir);
 
-    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..cae29161
--- /dev/null
+++ b/src/core/xself/install.cpp
@@ -0,0 +1,785 @@
+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);
+}
+
+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
+}
+
+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");
+    }
+}
+
+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;
+}
+
+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..f8c870b8 100644
--- a/src/core/xself/install.cppm
+++ b/src/core/xself/install.cppm
@@ -17,453 +17,41 @@ 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::string read_version_from_json(const fs::path& homeDir);
 
-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::optional<std::string> normalize_mirror_(std::string mirror);
 
-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::string read_mirror_from_json_(const fs::path& configPath);
 
-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::optional<std::string> env_install_mirror_();
 
-static std::string detect_install_mirror_() {
-    if (auto mirror = env_install_mirror_()) return *mirror;
+static std::string detect_install_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 set_mirror_fields_(nlohmann::json& json, const std::string& mirror);
 
 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);
-}
+                                      bool overwriteDataSubos);
 
 /// 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 bool is_under_temp_dir(const fs::path& p);
 
-static fs::path default_home() {
-    return fs::path(platform::get_home_dir()) / ".xlings";
-}
+static fs::path detect_source_dir();
 
-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 fs::path detect_existing_home();
 
-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";
+static fs::path default_home();
 
-    auto sourceLine = "test -f \"" + profileSh.string() + "\" && source \"" + profileSh.string() + "\"";
+static void copy_directory_contents(const fs::path& src, const fs::path& dst);
 
-    // 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
-}
+static void setup_shell_profiles(const fs::path& homeDir);
 
 // 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");
-    }
-}
+static void warn_root_context_();
 
 // `XLINGS_HOME` as the CALLER set it, canonicalized the same way
 // detect_existing_home does, so the two can be compared without a spurious
@@ -475,17 +63,7 @@ static void warn_root_context_() {
 // 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;
-}
+static fs::path explicit_home_();
 
 // Do these two paths name the same directory?
 //
@@ -500,318 +78,8 @@ static fs::path explicit_home_() {
 // 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);
+static bool same_dir_(const fs::path& a, const fs::path& b);
 
-    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..1fab2f6e 100644
--- a/src/core/xself/migrate.cppm
+++ b/src/core/xself/migrate.cppm
@@ -12,76 +12,6 @@ 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..c30f02cc 100644
--- a/src/core/xself/repair.cppm
+++ b/src/core/xself/repair.cppm
@@ -82,14 +82,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 +107,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 +119,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 +132,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 +160,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 +182,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..51869bc6
--- /dev/null
+++ b/src/core/xself/uninstall.cpp
@@ -0,0 +1,345 @@
+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 {
+
+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;
+}
+
+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;
+}
+
+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
+
+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';
+}
+
+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..60477a44 100644
--- a/src/core/xself/uninstall.cppm
+++ b/src/core/xself/uninstall.cppm
@@ -35,347 +35,40 @@ export struct UninstallOpts {
 };
 
 // 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::uintmax_t dir_size_bytes_(const fs::path& dir);
 
-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;
-}
+static std::string format_bytes_(std::uintmax_t bytes);
 
 // 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;
-}
+static bool home_dir_safe_to_remove_(const fs::path& home);
 
 // 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;
-}
+static fs::path chdir_to_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;
-}
+static bool windows_self_displace_(const fs::path& xlingsExe);
 #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;
-}
+                          std::uintmax_t totalSize);
 
-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';
-}
+static bool prompt_yes_no_(const std::string& question);
 
 // 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;
-    }
+static std::vector<fs::path> hooked_startup_files_(const fs::path& userHome);
 
-    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;
-    }
+static void emit_shell_advisory_(const fs::path& home);
 
-    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..9296fb3e 100644
--- a/src/core/xself/update.cppm
+++ b/src/core/xself/update.cppm
@@ -12,74 +12,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..d9f06986
--- /dev/null
+++ b/src/core/xvm/bindings.cpp
@@ -0,0 +1,565 @@
+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;
+}
+
+}
diff --git a/src/core/xvm/bindings.cppm b/src/core/xvm/bindings.cppm
index efa28982..44ab447c 100644
--- a/src/core/xvm/bindings.cppm
+++ b/src/core/xvm/bindings.cppm
@@ -167,265 +167,57 @@ 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),
-    };
-}
+                            std::string message);
 
 bool same_group_identity_(const BindingGroupRef& lhs,
-                          const BindingGroupRef& rhs) {
-    return lhs.provider == rhs.provider
-        && lhs.providerVersion == rhs.providerVersion
-        && lhs.group == rhs.group;
-}
+                          const BindingGroupRef& rhs);
 
-bool same_group_(const BindingGroupRef& lhs, const BindingGroupRef& rhs) {
-    return same_group_identity_(lhs, rhs)
-        && lhs.rootTarget == rhs.rootTarget
-        && lhs.rootVersion == rhs.rootVersion;
-}
+bool same_group_(const BindingGroupRef& lhs, const BindingGroupRef& rhs);
 
-bool supported_kind_(std::string_view kind) {
-    return kind == "program" || kind == "lib" || kind == "group"
-        || kind == "files";
-}
+bool supported_kind_(std::string_view kind);
 
 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;
-}
+canonical_manifest_path_(const VData& data);
 
-bool has_canonical_manifest_(const VData& data) {
-    return canonical_manifest_path_(data).has_value();
-}
+bool has_canonical_manifest_(const VData& data);
 
 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::string_view 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);
-}
+                         const std::string& version);
 
-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::string json_pointer_token_(std::string_view token);
 
 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;
-}
+                              const std::string& version);
 
 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;
-}
+invalid_group_identity_path_(const BindingGroupRef& group);
 
 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 +226,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 +298,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..99923021 100644
--- a/src/core/xvm/commands.cppm
+++ b/src/core/xvm/commands.cppm
@@ -28,25 +28,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 +43,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 +56,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 +84,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 +130,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 +153,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 +205,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..7dbb135d
--- /dev/null
+++ b/src/core/xvm/inspect.cpp
@@ -0,0 +1,615 @@
+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_ {
+
+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;
+}
+
+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;
+}
+
+}
diff --git a/src/core/xvm/inspect.cppm b/src/core/xvm/inspect.cppm
index 7bf9f9f0..55418a54 100644
--- a/src/core/xvm/inspect.cppm
+++ b/src/core/xvm/inspect.cppm
@@ -27,20 +27,7 @@ namespace xlings::xvm::detail_ {
 // 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;
-}
+                                   const std::string& version);
 
 // Is this member's name currently held by a DIFFERENT provider?
 //
@@ -61,19 +48,7 @@ bool release_declares_file_assets_(const VersionDB& db,
 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;
-}
+                               const std::string& releaseProvider);
 
 }  // namespace xlings::xvm::detail_
 
@@ -109,235 +84,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 +114,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 +128,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 +147,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 +178,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.
 //
@@ -596,51 +220,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 +236,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 +256,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 {
@@ -752,46 +285,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 {
@@ -814,49 +311,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..23dd8bfc
--- /dev/null
+++ b/src/core/xvm/lock.cpp
@@ -0,0 +1,66 @@
+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;
+}
+
+}
diff --git a/src/core/xvm/lock.cppm b/src/core/xvm/lock.cppm
index f3c8c149..3bddc5f6 100644
--- a/src/core/xvm/lock.cppm
+++ b/src/core/xvm/lock.cppm
@@ -47,19 +47,13 @@ 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:
@@ -131,50 +125,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..f075a7ab
--- /dev/null
+++ b/src/core/xvm/owner.cpp
@@ -0,0 +1,120 @@
+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;
+}
+
+}
diff --git a/src/core/xvm/owner.cppm b/src/core/xvm/owner.cppm
index aaa40281..58ed7a4e 100644
--- a/src/core/xvm/owner.cppm
+++ b/src/core/xvm/owner.cppm
@@ -67,42 +67,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 +87,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..71670e2d
--- /dev/null
+++ b/src/core/xvm/registration.cpp
@@ -0,0 +1,992 @@
+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,
+    };
+}
+
+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;
+}
+
+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;
+}
+
+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..b76eb37a 100644
--- a/src/core/xvm/registration.cppm
+++ b/src/core/xvm/registration.cppm
@@ -151,103 +151,39 @@ RegistrationError registration_error_(
     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),
-    };
-}
+    std::string 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;
-}
+    const BindingGroupRef& rhs);
 
 RegistrationGroupIdentity registration_group_identity_(
-    const BindingGroupRef& group) {
-    return {
-        group.provider,
-        group.providerVersion,
-        group.group,
-        group.rootTarget,
-        group.rootVersion,
-    };
-}
+    const BindingGroupRef& group);
 
 // 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);
-}
+    const VData& 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_view 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::string_view 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;
-}
+    const VData& data);
 
-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;
-}
+std::string registration_path_token_(std::string_view token);
 
 // Path comparison that survives a record written on another platform.
 //
@@ -256,48 +192,14 @@ std::string registration_path_token_(std::string_view token) {
 // `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;
-}
+std::string normalized_payload_path_(std::string_view path);
 
 // 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()] == '/';
-}
+bool payload_path_covers_(std::string_view root, std::string_view candidate);
 
 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;
-            }
-        }
-    }
-}
+    const std::set<RegistrationExactKey>& exactNodes);
 
 }  // namespace xlings::xvm::detail_
 
@@ -309,834 +211,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..fb3262a9 100644
--- a/src/core/xvm/removal.cppm
+++ b/src/core/xvm/removal.cppm
@@ -37,120 +37,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 +50,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..9d3fa14f 100644
--- a/src/core/xvm/shim.cppm
+++ b/src/core/xvm/shim.cppm
@@ -25,15 +25,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 +49,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 +59,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 +68,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 +123,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 +134,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 +144,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..963a945c
--- /dev/null
+++ b/src/core/xvm/switch_plan.cpp
@@ -0,0 +1,237 @@
+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_ {
+
+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..18ad1ebd 100644
--- a/src/core/xvm/switch_plan.cppm
+++ b/src/core/xvm/switch_plan.cppm
@@ -30,16 +30,7 @@ namespace xlings::xvm::detail_ {
 // 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};
-}
+                                                 const std::string& version);
 
 }  // namespace xlings::xvm::detail_
 
@@ -169,210 +160,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..07cef718
--- /dev/null
+++ b/src/interface.cpp
@@ -0,0 +1,199 @@
+// 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;
+}
+
+}
diff --git a/src/interface.cppm b/src/interface.cppm
index fc77dc72..154aa260 100644
--- a/src/interface.cppm
+++ b/src/interface.cppm
@@ -29,37 +29,7 @@ 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
@@ -186,143 +156,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..b0156da1
--- /dev/null
+++ b/src/libs/sha256.cpp
@@ -0,0 +1,33 @@
+// 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();
+}
+
+}
diff --git a/src/libs/sha256.cppm b/src/libs/sha256.cppm
index 9a83c219..7fcddd0f 100644
--- a/src/libs/sha256.cppm
+++ b/src/libs/sha256.cppm
@@ -115,22 +115,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..b678d006
--- /dev/null
+++ b/src/libs/tinyhttps.cpp
@@ -0,0 +1,337 @@
+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;
+}
+
+}
diff --git a/src/libs/tinyhttps.cppm b/src/libs/tinyhttps.cppm
index 338d3806..f628902f 100644
--- a/src/libs/tinyhttps.cppm
+++ b/src/libs/tinyhttps.cppm
@@ -139,17 +139,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 +147,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 +174,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..6ea5e87b
--- /dev/null
+++ b/src/platform.cpp
@@ -0,0 +1,418 @@
+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;
+import :linux;
+import :macos;
+import :windows;
+import :unix;
+
+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..446fa443 100644
--- a/src/platform.cppm
+++ b/src/platform.cppm
@@ -25,7 +25,7 @@ export import :unix;
 namespace xlings {
 namespace platform {
 
-    static std::string gRundir = std::filesystem::current_path().string();
+    extern std::string gRundir;
 
     export using platform_impl::PATH_SEPARATOR;
     export using platform_impl::OS_NAME;
@@ -82,103 +82,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);
-            }
-        }
-    }
-
-    export [[nodiscard]] std::string get_rundir() {
-        return gRundir;
-    }
-
-    export void set_rundir(const std::string& dir) {
-        gRundir = dir;
-    }
+                                 bool recursive = true);
 
-    export [[nodiscard]] std::string get_system_language() {
-        try {
-            auto loc = std::locale("");
-            auto name = loc.name();
+    export [[nodiscard]] std::string get_rundir();
 
-            if (name.empty() || name == "C" || name == "POSIX") {
-                return "en";
-            }
+    export void set_rundir(const std::string& dir);
 
-            if (auto pos = name.find_first_of("_-.@"); pos != std::string::npos) {
-                return name.substr(0, pos);
-            }
+    export [[nodiscard]] std::string get_system_language();
 
-            return name;
-        } catch (const std::runtime_error&) {
-            return "en";
-        }
-    }
-
-    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 +128,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 +175,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 +231,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..4672d350 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) {
@@ -223,16 +75,9 @@ namespace platform_impl {
         std::println("{}", 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..5bc65cc7 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) {
@@ -203,15 +77,9 @@ namespace platform_impl {
         std::println("{}", 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..f276e361
--- /dev/null
+++ b/src/platform/target.cpp
@@ -0,0 +1,53 @@
+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; }
+
+}
diff --git a/src/platform/target.cppm b/src/platform/target.cppm
index 89a02b0a..880a8170 100644
--- a/src/platform/target.cppm
+++ b/src/platform/target.cppm
@@ -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..f7085590
--- /dev/null
+++ b/src/platform/unix.cpp
@@ -0,0 +1,230 @@
+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;
+    }
+
+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__)
diff --git a/src/platform/unix.cppm b/src/platform/unix.cppm
index c1362311..d1a8b47c 100644
--- a/src/platform/unix.cppm
+++ b/src/platform/unix.cppm
@@ -98,26 +98,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 +114,13 @@ 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;
-    }
+                                                 std::chrono::milliseconds timeout);
 
     // 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};
-    }
+    static std::chrono::milliseconds term_query_timeout_();
 
     // Query the controlling terminal for its background color via the
     // OSC-11 sequence (xterm spec, supported by xterm / iTerm2 / Alacritty
@@ -189,43 +133,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 +155,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 +172,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..b6460619
--- /dev/null
+++ b/src/platform/windows.cpp
@@ -0,0 +1,344 @@
+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)
diff --git a/src/platform/windows.cppm b/src/platform/windows.cppm
index 43387d71..b1576d4c 100644
--- a/src/platform/windows.cppm
+++ b/src/platform/windows.cppm
@@ -80,27 +80,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 +94,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;
-            }
+                             std::chrono::milliseconds timeout) -> std::pair<int, std::string>;
 
-            // 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};
-    }
+    export void clear_console();
 
-    export void clear_console() {
-        std::system("cls");
-    }
-
-    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) {
@@ -300,41 +136,24 @@ namespace platform_impl {
         std::println("{}", 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 +173,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 +187,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/ui/banner.cpp b/src/ui/banner.cpp
new file mode 100644
index 00000000..c94590bd
--- /dev/null
+++ b/src/ui/banner.cpp
@@ -0,0 +1,237 @@
+module;
+
+#include "ftxui/dom/elements.hpp"
+#include "ftxui/screen/screen.hpp"
+#include "ftxui/screen/color.hpp"
+
+module xlings.ui;
+
+import std;
+import :theme;
+import :layout;
+
+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..47915409
--- /dev/null
+++ b/src/ui/info_panel.cpp
@@ -0,0 +1,498 @@
+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;
+import :theme;
+import :layout;
+
+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/progress.cpp b/src/ui/progress.cpp
new file mode 100644
index 00000000..f7056a46
--- /dev/null
+++ b/src/ui/progress.cpp
@@ -0,0 +1,358 @@
+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;
+import :theme;
+import :layout;
+
+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..a2dfae22 100644
--- a/src/ui/progress.cppm
+++ b/src/ui/progress.cppm
@@ -22,44 +22,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 +36,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 +59,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 +72,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 +85,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..37ab940b
--- /dev/null
+++ b/src/ui/selector.cpp
@@ -0,0 +1,177 @@
+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;
+import :theme;
+import :layout;
+
+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..0f61f009 100644
--- a/src/ui/selector.cppm
+++ b/src/ui/selector.cppm
@@ -16,57 +16,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 +25,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..da883078
--- /dev/null
+++ b/src/ui/table.cpp
@@ -0,0 +1,67 @@
+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;
+import :theme;
+import :layout;
+
+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..a1a58f5f 100644
--- a/src/ui/theme.cppm
+++ b/src/ui/theme.cppm
@@ -39,14 +39,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 ─────────────────────────────────────────────────
 //

From b87f49bf71305fe6b1c5a813da6c0240f9986e31 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 09:47:52 +0800
Subject: [PATCH 04/19] refactor: out-of-line class members, and keep
 module-private declarations out of the interface (phase 2)

Two changes, both aimed at what is left in the BMI after phase 1.

**Class members.** A body defined inside a class is implicitly inline, so it
stayed in the interface and an edit to it still recompiled every importer.
286 members / 3,845 body lines move to out-of-line definitions in the
implementation unit. `config.cppm` is the case that pays: 93% class body and 34
direct importers.

Out-of-lining is not a text move, and each rule here is one gcc refused:
- the declarator-id becomes `C::name` and everything after it resolves in class
  scope, but the RETURN TYPE precedes it and does not -- so a nested return type
  gets qualified, and the definitions are emitted INSIDE their namespace rather
  than fully qualified at file scope (`Segment` does not resolve there)
- `override`/`final` are declaration-only; a virt-specifier outside a class is
  an error
- `: registry_ { registry }` -- a brace-initialised member-init list was being
  read as the function body, producing `Ctor(args); {}`
- a class inside `#if defined(_WIN32)` must have its outlined members re-wrapped
  in the same condition, or its Windows bodies compile on Linux

**Module-private declarations.** A non-exported helper's declaration only needs
to be in the interface if something still THERE names it -- an exported
template, an inline or constexpr body, a class member body. Otherwise it is
module-private and belongs in the implementation unit: in the interface it sits
in the BMI, so changing its signature would recompile every importer for
nothing. Deciding this needs care in two places gcc found:
- a qualified call `detail_::binding_error_(...)` IS a reference; a lookbehind
  rejecting ':' missed the common form
- inside `export namespace`, an entity is exported even though its own
  declaration does not say so
- when the declaration is dropped, the definition becomes the only declaration
  and must carry the default arguments the declaration used to hold

Interface surface: 46,253 -> 14,819 lines, 32% of the original.

Two members keep their bodies because moving them makes gcc@16.1.0 segfault,
both recorded with the evidence in ICE_SKIP. The second was found by bisecting
config.cppm's 85 movable members (bisect-member.sh): #34 is
`static Config& instance_() { static Config inst; return inst; }`, whose
function-local static is where the module-attached `Config` is first completed.
Moving it crashes cc1plus in an unrelated translation unit, on a different type,
in a different module -- so the message names nothing that changed.
---
 .agents/tools/module-split/bisect-member.sh |   32 +
 .agents/tools/module-split/outline.py       |  203 ++-
 .agents/tools/module-split/split.py         |  153 ++-
 src/agent/agent.cppm                        |    6 -
 src/agent/skills/contributing.cpp           |   22 +
 src/agent/skills/contributing.cppm          |    8 +-
 src/agent/skills/skill.cpp                  |   40 +
 src/agent/skills/skill.cppm                 |   25 +-
 src/agent/skills/usage.cpp                  |   33 +
 src/agent/skills/usage.cppm                 |   18 +-
 src/capabilities.cpp                        |  505 +++++++
 src/capabilities.cppm                       |  498 +------
 src/cli.cppm                                |   57 -
 src/core/cmdprocessor.cpp                   |   45 +-
 src/core/cmdprocessor.cppm                  |   55 +-
 src/core/config.cpp                         | 1165 ++++++++++++++++
 src/core/config.cppm                        | 1148 ++--------------
 src/core/i18n.cppm                          |    2 -
 src/core/log.cppm                           |   11 -
 src/core/profile.cppm                       |   17 -
 src/core/semver.cpp                         |   16 +
 src/core/semver.cppm                        |    4 +-
 src/core/subos.cpp                          |    5 +-
 src/core/subos.cppm                         |  149 +--
 src/core/subos/graphics.cpp                 |   33 +
 src/core/subos/graphics.cppm                |   26 +-
 src/core/subos/sandbox.cpp                  |   30 +-
 src/core/subos/sandbox.cppm                 |  146 --
 src/core/xim/catalog.cpp                    |  395 ++++++
 src/core/xim/catalog.cppm                   |  395 +-----
 src/core/xim/extract.cppm                   |   25 -
 src/core/xim/index.cpp                      |  160 +++
 src/core/xim/index.cppm                     |  160 +--
 src/core/xim/indexfetch.cpp                 |   15 +-
 src/core/xim/indexfetch.cppm                |   45 +-
 src/core/xim/install_state.cpp              |   43 +
 src/core/xim/install_state.cppm             |   34 +-
 src/core/xim/installer.cpp                  | 1320 +++++++++++++++++++
 src/core/xim/installer.cppm                 | 1309 +-----------------
 src/core/xim/inventory.cpp                  |  110 ++
 src/core/xim/inventory.cppm                 |  107 +-
 src/core/xim/libxpkg/types/type.cpp         |   19 +
 src/core/xim/libxpkg/types/type.cppm        |    9 +-
 src/core/xself.cppm                         |    2 -
 src/core/xself/doctor.cpp                   |    9 +-
 src/core/xself/doctor.cppm                  |  218 ---
 src/core/xself/init.cppm                    |   39 -
 src/core/xself/install.cppm                 |   63 -
 src/core/xself/uninstall.cppm               |   32 +-
 src/core/xvm/bindings.cpp                   |   17 +
 src/core/xvm/bindings.cppm                  |   36 +-
 src/core/xvm/inspect.cpp                    |   21 +
 src/core/xvm/inspect.cppm                   |   44 +-
 src/core/xvm/lock.cpp                       |   44 +
 src/core/xvm/lock.cppm                      |   38 +-
 src/core/xvm/owner.cpp                      |   18 +
 src/core/xvm/owner.cppm                     |   11 +-
 src/core/xvm/registration.cppm              |   55 -
 src/core/xvm/switch_plan.cppm               |    9 -
 src/interface.cpp                           |  104 ++
 src/interface.cppm                          |  110 +-
 src/libs/sha256.cpp                         |   96 ++
 src/libs/sha256.cppm                        |   89 +-
 src/libs/tinyhttps.cpp                      |   34 +
 src/libs/tinyhttps.cppm                     |   28 +-
 src/platform.cpp                            |    4 -
 src/platform.cppm                           |    2 -
 src/platform/target.cpp                     |    9 +
 src/platform/target.cppm                    |    2 +-
 src/platform/unix.cpp                       |   65 +
 src/platform/unix.cppm                      |   59 +-
 src/platform/windows.cpp                    |   63 +
 src/platform/windows.cppm                   |   52 +-
 src/runtime/cancellation.cpp                |   51 +
 src/runtime/cancellation.cppm               |   41 +-
 src/runtime/capability.cpp                  |   36 +
 src/runtime/capability.cppm                 |   27 +-
 src/runtime/event_stream.cpp                |   92 ++
 src/runtime/event_stream.cppm               |   88 +-
 src/runtime/task.cpp                        |  159 +++
 src/runtime/task.cppm                       |  163 +--
 src/ui/banner.cpp                           |    2 -
 src/ui/info_panel.cpp                       |    2 -
 src/ui/progress.cpp                         |    2 -
 src/ui/selector.cpp                         |    2 -
 src/ui/table.cpp                            |    2 -
 86 files changed, 5445 insertions(+), 5193 deletions(-)
 create mode 100644 .agents/tools/module-split/bisect-member.sh
 create mode 100644 src/agent/skills/contributing.cpp
 create mode 100644 src/agent/skills/skill.cpp
 create mode 100644 src/agent/skills/usage.cpp
 create mode 100644 src/core/semver.cpp
 create mode 100644 src/core/xim/libxpkg/types/type.cpp
 create mode 100644 src/runtime/cancellation.cpp
 create mode 100644 src/runtime/capability.cpp
 create mode 100644 src/runtime/event_stream.cpp
 create mode 100644 src/runtime/task.cpp

diff --git a/.agents/tools/module-split/bisect-member.sh b/.agents/tools/module-split/bisect-member.sh
new file mode 100644
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/outline.py b/.agents/tools/module-split/outline.py
index 9f587a68..33e3c2bb 100644
--- a/.agents/tools/module-split/outline.py
+++ b/.agents/tools/module-split/outline.py
@@ -34,6 +34,87 @@ class scope — but the RETURN TYPE comes before it and is not, so a return
     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
@@ -69,20 +150,42 @@ def split_member_init(head: str):
     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
+    # 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('(')
-    pre = head[:o]
     m = None
-    for m in re.finditer(r'[\w~]+\s*$', pre):
+    for m in re.finditer(r'[\w~]+\s*$', s[:o]):
         pass
     if not m:
         return head
-    ret = pre[:m.start()]
-    name = pre[m.start():]
+    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
@@ -97,24 +200,42 @@ def qualify(head: str, cls: str, nested: set[str], fn: str) -> str:
     return f'{lead_ws}{ret_stripped}{sep}{cls}::{name.strip()}' + head[o:]
 
 
-def outline_class(cls_item: Item, ns: str, out_impl: list, stats: dict) -> str:
-    """Rewrite one class body; append out-of-line definitions to out_impl.
-    Returns the rewritten class item text."""
+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 ':' in m.group('rest') or 'template' in cls_item.head:
-        # a base-class list is fine, but a template class is not: its members
-        # cannot be defined in another unit without explicit instantiation
-        if 'template' in cls_item.head:
-            return cls_item.raw
+    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)
-    qual = f'{ns}::{cname}' if ns else cname
+    # 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)
@@ -128,13 +249,16 @@ def outline_class(cls_item: Item, ns: str, out_impl: list, stats: dict) -> str:
                 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() + ';')
-                out_impl.append(
-                    qualify(strip_defaults(decl), qual, nested, cname).strip()
-                    + init + it.body + it.tail)
+                out_impl.append((ns, guards.current(),
+                    qualify(strip_virt_specifiers(strip_defaults(decl)),
+                            qual, nested, cname).strip()
+                    + init + it.body + it.tail))
                 stats['members'] += 1
                 stats['lines'] += it.body.count('\n')
                 keep = False
@@ -143,22 +267,54 @@ def outline_class(cls_item: Item, ns: str, out_impl: list, stats: dict) -> str:
     return cls_item.lead + cls_item.head + '{' + ''.join(pieces) + '}' + cls_item.tail
 
 
-def walk(items: list[Item], ns: str, out_impl: list, stats: dict) -> str:
+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)
+            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))
+            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)
+
+
+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()
@@ -174,7 +330,7 @@ def process(path: str, write: bool):
 
     out_impl: list[str] = []
     stats = {'members': 0, 'lines': 0}
-    new_body = walk(scan_items(body), '', out_impl, stats)
+    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:
@@ -197,7 +353,7 @@ def process(path: str, write: bool):
         with open(cpp, 'a') as fh:
             fh.write('\n\n// ── out-of-line class members '
                      '─────────────────────────────────\n\n')
-            fh.write('\n\n'.join(x.strip('\n') for x in out_impl) + '\n')
+            fh.write(group_by_namespace(out_impl) + '\n')
     return stats['members'], stats['lines'], None
 
 
@@ -206,7 +362,10 @@ def main():
     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:
diff --git a/.agents/tools/module-split/split.py b/.agents/tools/module-split/split.py
index 29eb867a..67cda16a 100644
--- a/.agents/tools/module-split/split.py
+++ b/.agents/tools/module-split/split.py
@@ -121,16 +121,44 @@ def scan_items(text: str) -> list[Item]:
         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:
@@ -360,15 +388,45 @@ def decl_from_def(h: str) -> str:
 
 # ─────────────────────────── emission ───────────────────────────
 
+class Cand:
+    """A module-private entity whose declaration may or may not be needed in
+    the interface."""
+    __slots__ = ('ns', 'decl', 'name', 'impl_with_defaults', 'impl_no_defaults')
+
+    def __init__(self, ns, decl, name, impl_with_defaults, impl_no_defaults):
+        self.ns = ns
+        self.decl = decl
+        self.name = name
+        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
 
 
-def process_level(items: list[Item], out: Split, indent: str, in_class=False):
+# 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, in_class=False,
+                  ns: str = '', exported: bool = False):
     for it in items:
         cls = classify(it, in_class)
         if cls == 'both':
@@ -377,7 +435,15 @@ def process_level(items: list[Item], out: Split, indent: str, in_class=False):
         elif cls == 'namespace':
             inner = it.body[1:-1]
             sub = Split()
-            process_level(scan_items(inner), sub, indent)
+            # 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):
@@ -394,9 +460,19 @@ def process_level(items: list[Item], out: Split, indent: str, in_class=False):
         elif cls == 'stay':
             out.iface.append(it.raw)
         elif cls == 'split-fn':
-            out.iface.append(it.lead + decl_from_def(it.head))
-            impl_head = strip_defaults(strip_static(strip_export(it.head)))
-            out.impl.append(impl_head.lstrip('\n') + it.body + it.tail)
+            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),
+                                      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':
@@ -406,16 +482,70 @@ def process_level(items: list[Item], out: Split, indent: str, in_class=False):
             # the declaration carries the type and name, never the initialiser
             eq = scrub(bare).find('=')
             decl = (bare[:eq].rstrip() if eq >= 0 else bare).strip()
-            out.iface.append(it.lead + 'extern ' + decl + ';')
+            ext = it.lead + 'extern ' + decl + ';'
             defn = bare + (it.body or '') + it.tail
-            out.impl.append(defn.strip() if defn.rstrip().endswith(';')
-                            else defn.strip() + ';')
+            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), 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)
+    impl = IMPL_RE.sub(
+        lambda m: (cands[int(m.group(1))].impl_no_defaults
+                   if int(m.group(1)) in keep
+                   else cands[int(m.group(1))].impl_with_defaults),
+        impl)
+    return iface, impl
+
+
 PREAMBLE = re.compile(
     r'\A(?P<gmf>.*?)^export module (?P<mod>[\w.]+)(?P<part>:\w+)?;',
     re.S | re.M)
@@ -462,7 +592,14 @@ def split_file(path: str, qualify_partition_import=False):
         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 (iface, impl.rstrip() + '\n', out.moved, out.moved_lines,
             mod + part), None
 
diff --git a/src/agent/agent.cppm b/src/agent/agent.cppm
index 31a95740..1a7d24a5 100644
--- a/src/agent/agent.cppm
+++ b/src/agent/agent.cppm
@@ -20,12 +20,6 @@ import xlings.agent.resources;
 
 namespace xlings::agent {
 
-// Print the overview text followed by the skill index table.
-void print_overview(const SkillRegistry& reg);
-
-// Print the full content of a named skill.
-bool print_skill(const SkillRegistry& reg, std::string_view name);
-
 // Top-level handler for `xlings agent [args...]`.
 export int run(int argc, char* argv[]);
 
diff --git a/src/agent/skills/contributing.cpp b/src/agent/skills/contributing.cpp
new file mode 100644
index 00000000..644f8042
--- /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..f0b925f3
--- /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..847f2e3a
--- /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/capabilities.cpp b/src/capabilities.cpp
index 678d7bc0..148f70fe 100644
--- a/src/capabilities.cpp
+++ b/src/capabilities.cpp
@@ -52,3 +52,508 @@ capability::Registry build_registry() {
 }
 
 }
+
+
+// ── 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 4d47cfa1..ed184934 100644
--- a/src/capabilities.cppm
+++ b/src/capabilities.cppm
@@ -28,49 +28,15 @@ 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
@@ -78,168 +44,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.
@@ -251,328 +99,64 @@ 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();
diff --git a/src/cli.cppm b/src/cli.cppm
index 9155ea87..4e04317b 100644
--- a/src/cli.cppm
+++ b/src/cli.cppm
@@ -37,63 +37,6 @@ namespace lua = mcpplibs::capi::lua;
 
 namespace xlings::cli {
 
-// ─── EventStream consumer: dispatch DataEvent to ui:: functions ───
-
-static void dispatch_data_event(const DataEvent& e);
-
-// ─── EventStream consumer: handle PromptEvent via ui:: interactive functions ───
-
-static void handle_prompt(EventStream& stream, const PromptEvent& p);
-
-// 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);
-
-// Generate .xlings.json from a workspace map
-void generate_xlings_json_(const std::filesystem::path& dir, const xvm::Workspace& workspace);
-
-// 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);
-
-// Install packages from project .xlings.json workspace
-int install_from_project_config_(EventStream& stream);
-
-void apply_global_opts_(const mcpplibs::cmdline::ParsedArgs& args);
-
-
-// config subcommand handler
-int cmd_config_(const mcpplibs::cmdline::ParsedArgs& args, EventStream& stream);
-
-// `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);
-
 export int run(int argc, char* argv[]);
 
 } // namespace xlings::cli
diff --git a/src/core/cmdprocessor.cpp b/src/core/cmdprocessor.cpp
index 38cb52db..a3f86e3c 100644
--- a/src/core/cmdprocessor.cpp
+++ b/src/core/cmdprocessor.cpp
@@ -43,7 +43,7 @@ std::filesystem::path find_xim_project_dir() {
     return homeDir;
 }
 
-int xim_exec(const std::string& flags, int argc, char* argv[], int startIdx) {
+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()) {
@@ -57,7 +57,7 @@ int xim_exec(const std::string& flags, int argc, char* argv[], int startIdx) {
     return platform::exec(cmd);
 }
 
-int xvm_exec(const std::string& subcommand, int argc, char* argv[], int startIdx) {
+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 += " ";
@@ -290,3 +290,44 @@ CommandProcessor create_processor() {
 }
 
 }
+
+
+// ── 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("Use 'xlings help' for usage information");
+        return 1;
+    }
+
+int CommandProcessor::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;
+    }
+
+} // namespace xlings::cmdprocessor
diff --git a/src/core/cmdprocessor.cppm b/src/core/cmdprocessor.cppm
index c33ec77a..beb4ea7c 100644
--- a/src/core/cmdprocessor.cppm
+++ b/src/core/cmdprocessor.cppm
@@ -24,65 +24,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();
-
-int xim_exec(const std::string& flags, int argc, char* argv[], int startIdx = 2);
-
-int xvm_exec(const std::string& subcommand, int argc, char* argv[], int startIdx = 2);
-
-std::filesystem::path find_project_xlings_json();
-
-std::filesystem::path find_project_legacy_xlings_lua();
-
-static int install_targets_from_list(const std::vector<std::string>& targets);
-
-static int install_from_legacy_config_xlings_via_xim(const std::filesystem::path& cfg);
-
-int install_from_project_config();
-
 export CommandProcessor create_processor();
 
 } // namespace xlings::cmdprocessor
diff --git a/src/core/config.cpp b/src/core/config.cpp
index 3be2fac1..f9688519 100644
--- a/src/core/config.cpp
+++ b/src/core/config.cpp
@@ -59,3 +59,1168 @@ std::vector<IndexRepo> parse_index_repos_json(const nlohmann::json& json,
 }
 
 }
+
+
+// ── 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("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));
+    }
+
+} // namespace xlings
diff --git a/src/core/config.cppm b/src/core/config.cppm
index bfcad0a7..aa1729bc 100644
--- a/src/core/config.cppm
+++ b/src/core/config.cppm
@@ -99,15 +99,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_;
@@ -141,270 +136,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.
@@ -423,70 +205,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".
     //
@@ -511,356 +234,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.
     //
@@ -875,22 +261,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;
@@ -898,43 +269,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.
@@ -952,44 +302,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.
@@ -1001,131 +328,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.
     //
@@ -1138,140 +381,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.
     //
@@ -1281,152 +436,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/i18n.cppm b/src/core/i18n.cppm
index 678d380a..ab6828cb 100644
--- a/src/core/i18n.cppm
+++ b/src/core/i18n.cppm
@@ -165,8 +165,6 @@ constexpr MsgEntry gMessages_[] = {
 static_assert(sizeof(gMessages_) / sizeof(gMessages_[0]) == MSG_COUNT,
               "gMessages_ size must match Msg enum count");
 
-extern std::string gLang_;
-
 export void set_language(const std::string& lang);
 
 export [[nodiscard]] const std::string& language();
diff --git a/src/core/log.cppm b/src/core/log.cppm
index 704460d1..a87af0c8 100644
--- a/src/core/log.cppm
+++ b/src/core/log.cppm
@@ -19,8 +19,6 @@ export enum class Level {
 
 extern Level gLevel_;
 extern std::string gContext_;
-extern std::ofstream gFile_;
-extern bool gColor_;
 // Terminal output is suppressed when platform::is_tui_mode() is true
 
 export void set_level(Level level);
@@ -38,13 +36,6 @@ export void set_context(std::string ctx);
 export void clear_context();
 
 export void enable_color(bool 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_();
 bool color_on_err_();
 
 std::string colored_(palette::Rgb c, const char* text);
@@ -52,8 +43,6 @@ 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);
 
-std::string timestamp_();
-
 void write_to_file_(std::string_view prefix, std::string_view msg);
 
 export template<typename... Args>
diff --git a/src/core/profile.cppm b/src/core/profile.cppm
index 289ee05e..c3034904 100644
--- a/src/core/profile.cppm
+++ b/src/core/profile.cppm
@@ -26,19 +26,6 @@ export struct Generation {
     std::map<std::string, std::string>     packages;
 };
 
-std::string utc_now_iso_();
-
-int next_gen_number_(const fs::path& gensDir);
-
-// 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);
-
 export Generation load_current(const fs::path& envDir);
 
 export int commit(const fs::path& envDir,
@@ -103,10 +90,6 @@ export std::vector<SubosSnapshot> load_subos_snapshots(const fs::path& xlingsHom
 export bool save_subos_workspace(const fs::path& subosRoot,
                                  const xvm::SubosWorkspace& workspace);
 
-// 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);
-
 // 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);
diff --git a/src/core/semver.cpp b/src/core/semver.cpp
new file mode 100644
index 00000000..35a2968d
--- /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
index 793f608d..441dd934 100644
--- a/src/core/subos.cpp
+++ b/src/core/subos.cpp
@@ -206,7 +206,10 @@ CandidateResolution_ resolve_candidate_(std::string_view query) {
             .candidates = suggestions_(query, all)};
 }
 
-void emit_candidates_(EventStream& stream, const CandidateResolution_& resolution, std::string_view query, std::string_view hint) {
+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({
diff --git a/src/core/subos.cppm b/src/core/subos.cppm
index ed1f1f97..51b0e8e9 100644
--- a/src/core/subos.cppm
+++ b/src/core/subos.cppm
@@ -60,20 +60,10 @@ export struct SubosCandidateView {
     std::vector<SubosInfo> candidates;
 };
 
-nlohmann::json read_config_json_(const fs::path& path);
-
-void write_config_json_(const fs::path& path, const nlohmann::json& json);
-
-SubosInfo candidate_info_(const std::string& name, bool includeToolCount);
-
 export SubosCandidateView candidate_view(bool includeToolCount = true);
 
 export std::vector<SubosInfo> list_all();
 
-std::string lowercase_name_(std::string_view name);
-
-std::size_t edit_distance_(std::string_view lhs, std::string_view rhs);
-
 struct CandidateResolution_ {
     std::string selected;
     std::string reason;
@@ -81,68 +71,11 @@ struct CandidateResolution_ {
     bool autoSelected { false };
 };
 
-std::vector<SubosInfo> suggestions_(
-        std::string_view query,
-        std::span<const SubosInfo> candidates);
-
-CandidateResolution_ resolve_candidate_(std::string_view query);
-
-void emit_candidates_(EventStream& stream,
-                      const CandidateResolution_& resolution,
-                      std::string_view query,
-                      std::string_view hint = {});
-
 struct UseNameResolution_ {
     std::string selected;
     int exitCode { 0 };
 };
 
-UseNameResolution_ resolve_use_name_(std::string_view query,
-                                    EventStream& stream);
-
-void update_current_symlink_(EventStream& stream,
-                              const fs::path& homeDir,
-                              const fs::path& targetDir);
-
-// ─────────────────────────────────────────────────────────────────────
-// 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);
-
 // 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.
@@ -187,8 +120,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);
-
 // Parse `[<ns>:]<name>[@<ver>]` → {ns, name, ver}. Empty ns if absent;
 // empty ver if absent ("latest" semantics handled downstream).
 struct PkgRef {
@@ -197,18 +128,6 @@ struct PkgRef {
     std::string ver;
 };
 
-PkgRef parse_pkg_spec_(const std::string& spec);
-
-// 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);
-
-// 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);
-
 } // namespace new_from_detail_
 
 export int new_from(const std::string& name, const fs::path& customDir,
@@ -509,55 +428,7 @@ 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);
-
-// 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);
-
-void warn_storage_dormant_on_shell_(const std::string& name);
-
-int use_emit_shell(const std::string& name,
-                          std::string_view shell_kind,
-                          EventStream& stream);
+}
 
 
 
@@ -598,24 +469,6 @@ export int remove(const std::string& name, EventStream& stream);
 
 export std::optional<SubosInfo> info(const std::string& name);
 
-int run_list_(EventStream& stream);
-
-// 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);
-
-int run_info_(const std::string& name, EventStream& stream);
-
 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
index 5478bcca..f7fcc8ab 100644
--- a/src/core/subos/graphics.cpp
+++ b/src/core/subos/graphics.cpp
@@ -278,3 +278,36 @@ std::string describe(const VendorWiring& v) {
 }
 
 }
+
+
+// ── 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 9d872c6f..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 ────────────────────────────────────────────────────────
@@ -305,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) {
diff --git a/src/core/subos/sandbox.cpp b/src/core/subos/sandbox.cpp
index a4b6a0d0..482923c2 100644
--- a/src/core/subos/sandbox.cpp
+++ b/src/core/subos/sandbox.cpp
@@ -170,7 +170,8 @@ bool is_mounted_(const fs::path& path) {
     return std::system(cmd.c_str()) == 0;
 }
 
-int mount_image_(const fs::path& img, const fs::path& mountpoint, const std::string& user) {
+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
 
@@ -285,7 +286,11 @@ locate_proot_(const fs::path& home_dir) {
 }
 
 std::vector<SandboxBind>
-sandbox_binds_(const fs::path& subos_dir, const fs::path& host_xlings_home, const std::string& user, StorageMode storage, const fs::path& mountpoint)
+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;
@@ -348,7 +353,12 @@ sandbox_binds_(const fs::path& subos_dir, const fs::path& host_xlings_home, cons
 }
 
 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)
+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.
@@ -444,7 +454,16 @@ std::string classify_bwrap_probe_error_(const std::string& output,
 }
 
 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, const fs::path& mountpoint, bool gpu, const std::string& cmd)
+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 = {
@@ -503,7 +522,8 @@ void maybe_show_bwrap_hint_(const fs::path& subos_dir) {
 }
 
 std::optional<BackendInfo>
-detect_backend_(const fs::path& home_dir, const fs::path& subos_dir) {
+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)
diff --git a/src/core/subos/sandbox.cppm b/src/core/subos/sandbox.cppm
index 4e8763be..2d4da1f3 100644
--- a/src/core/subos/sandbox.cppm
+++ b/src/core/subos/sandbox.cppm
@@ -58,8 +58,6 @@ namespace xlings::subos::sandbox {
 
 namespace fs = std::filesystem;
 
-nlohmann::json read_config_json_(const fs::path& path);
-
 // ── Storage mode (V6) ──────────────────────────────────────────────
 // Storage isolation mode for sandbox data. Set at subos creation time
 // via `--storage <mode>`, persisted in subos/.xlings.json["storage"].
@@ -94,13 +92,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);
-std::string make_etc_group_(const std::string& user, gid_t gid);
 inline constexpr std::string_view kEtcHosts =
     "127.0.0.1 localhost\n::1 localhost\n";
 inline constexpr std::string_view kEtcNsswitch =
@@ -170,14 +161,6 @@ 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);
-
 #endif // __linux__ / __APPLE__
 
 // ── Image storage helpers (V6) ────────────────────────────────────
@@ -188,43 +171,9 @@ 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);
 
-// 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 = {});
-
 // Unmount an image file.
 export int unmount_image_(const fs::path& mountpoint);
 
-
-// ─────────────────────────────────────────────────────────────────────
-// 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);
-
 // ── Unified bind list (shared by proot + bwrap) ──────────────────────
 //
 // Both backends use the SAME set of host-RO paths and sandbox-private
@@ -245,69 +194,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 = {});
-
-// 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 = "");
-
-// ── 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);
-
-// 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);
-
-// 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);
-
-// 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 = "");
-
 // ── Backend detection + auto-install ─────────────────────────────────
 
 enum class SandboxBackend { Bwrap, Proot };
@@ -317,38 +203,6 @@ 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::optional<BackendInfo>
-detect_backend_(const fs::path& home_dir,
-                const fs::path& subos_dir = {});
-
-// 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_();
-
 int auto_install_backend_(const fs::path& home_dir, EventStream& stream);
 
 
diff --git a/src/core/xim/catalog.cpp b/src/core/xim/catalog.cpp
index 5572769b..a03a1d4b 100644
--- a/src/core/xim/catalog.cpp
+++ b/src/core/xim/catalog.cpp
@@ -303,3 +303,398 @@ resolve_local_coordinate(const PackageCatalog& catalog,
 }
 
 }
+
+
+// ── 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 2294a64a..2acd398c 100644
--- a/src/core/xim/catalog.cppm
+++ b/src/core/xim/catalog.cppm
@@ -214,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.
     //
@@ -465,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
diff --git a/src/core/xim/extract.cppm b/src/core/xim/extract.cppm
index a5fadf3e..9007a012 100644
--- a/src/core/xim/extract.cppm
+++ b/src/core/xim/extract.cppm
@@ -74,31 +74,6 @@ constexpr int kWriteFlags =
 std::expected<std::string, std::string>
 check_safe_pathname_(const char* raw);
 
-std::string path_from_wide_(const wchar_t* raw);
-
-std::string entry_pathname_(archive_entry* entry);
-
-std::string entry_hardlink_(archive_entry* entry);
-
-std::string libarchive_error_(struct archive* a);
-
-// 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);
-la_int64_t const_root_lookup_gid_(void*, const char*, la_int64_t);
-
-// 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);
-
-void ensure_archive_locale_();
-
 } // namespace detail_
 
 std::expected<std::filesystem::path, ExtractError>
diff --git a/src/core/xim/index.cpp b/src/core/xim/index.cpp
index a97ae0b4..828dd5f3 100644
--- a/src/core/xim/index.cpp
+++ b/src/core/xim/index.cpp
@@ -163,3 +163,163 @@ CacheResult load_index_cache(const std::filesystem::path& cacheFile,
 }
 
 }
+
+
+// ── 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 ce84eef4..c1c8957b 100644
--- a/src/core/xim/index.cppm
+++ b/src/core/xim/index.cppm
@@ -16,10 +16,6 @@ namespace xlings::xim::cache_detail_ {
 
 constexpr int CACHE_FORMAT_VERSION = 2;
 
-int type_to_int(xpkg::PackageType t);
-
-xpkg::PackageType int_to_type(int v);
-
 bool save_index_cache(const xpkg::PackageIndex& index,
                       const std::filesystem::path& cacheFile,
                       const std::string& repoHeadHash,
@@ -48,178 +44,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 is_loaded() const { return loaded_; }
-    std::size_t size() const { return index_.entries.size(); }
+            bool forceRebuild = false);
+
+    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/indexfetch.cpp b/src/core/xim/indexfetch.cpp
index 75cd9ebe..3dc451b6 100644
--- a/src/core/xim/indexfetch.cpp
+++ b/src/core/xim/indexfetch.cpp
@@ -82,7 +82,9 @@ BaseOverride resolve_base_() {
     return b;
 }
 
-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) {
+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) {
@@ -674,3 +676,14 @@ void reconcile_index_temps(const std::filesystem::path& dataDir) {
 }
 
 }
+
+
+// ── 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 eaad950a..3da722ee 100644
--- a/src/core/xim/indexfetch.cppm
+++ b/src/core/xim/indexfetch.cppm
@@ -43,7 +43,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 +129,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,23 +193,6 @@ namespace xlings::xim {
 
 namespace detail_ {
 
-// Repo + tag are fixed discovery anchors; overridable for testing/mirrors.
-std::string index_repo_name_();
-std::string index_tag_();
-
-std::string lower_hex_(std::string 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);
-
 // 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).
@@ -217,21 +200,6 @@ struct BaseOverride {
     std::string base;                      // remote base, or empty
     std::optional<std::filesystem::path> local;  // local dir, if base is local
 };
-BaseOverride resolve_base_();
-
-// 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);
-
-// #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);
 
 } // namespace detail_
 
@@ -246,8 +214,6 @@ std::vector<IndexSnapshot> snapshots_of(const IndexManifest& manifest);
 
 namespace detail_ {
 
-std::string describe_requirement_(const IndexSnapshot& s);
-
 }  // namespace detail_
 
 std::expected<SnapshotChoice, std::string> choose_snapshot(
@@ -277,12 +243,7 @@ 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);
+}
 
 // Cached fetch of the COMBINED pointer file (xim-index-pointers.json): ONE raw
 // fetch per process covering ALL indexes (main + subs). One fetch (vs one per
diff --git a/src/core/xim/install_state.cpp b/src/core/xim/install_state.cpp
index f83f34f6..384fc96e 100644
--- a/src/core/xim/install_state.cpp
+++ b/src/core/xim/install_state.cpp
@@ -92,3 +92,46 @@ bool unverifiable_stamped_payload(const LedgerIndex& ledger,
 }
 
 }
+
+
+// ── 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 56abe983..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_;
diff --git a/src/core/xim/installer.cpp b/src/core/xim/installer.cpp
index 5834e9e8..acad40e9 100644
--- a/src/core/xim/installer.cpp
+++ b/src/core/xim/installer.cpp
@@ -1964,3 +1964,1323 @@ std::vector<std::string> unfulfilled_program_promises_(const InstallPlan& plan)
 }
 
 }
+
+
+// ── 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 929bd227..00bce070 100644
--- a/src/core/xim/installer.cppm
+++ b/src/core/xim/installer.cppm
@@ -376,21 +376,9 @@ class ScopedCurrentDir_ {
     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_();
@@ -484,8 +472,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
@@ -494,28 +482,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
@@ -528,897 +495,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.
     //
@@ -1438,378 +515,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
index 9d47dec0..04bac9de 100644
--- a/src/core/xim/inventory.cpp
+++ b/src/core/xim/inventory.cpp
@@ -610,3 +610,113 @@ std::vector<InstalledPackageRecord> collect_package_inventory(PackageCatalog& ca
 }
 
 }
+
+
+// ── 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 b890365b..4cc48991 100644
--- a/src/core/xim/inventory.cppm
+++ b/src/core/xim/inventory.cppm
@@ -84,110 +84,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 };
diff --git a/src/core/xim/libxpkg/types/type.cpp b/src/core/xim/libxpkg/types/type.cpp
new file mode 100644
index 00000000..5833e719
--- /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/xself.cppm b/src/core/xself.cppm
index 59f891eb..5e315f59 100644
--- a/src/core/xself.cppm
+++ b/src/core/xself.cppm
@@ -46,8 +46,6 @@ import xlings.cli.spec;
 
 namespace xlings::xself {
 
-static int cmd_help(EventStream& stream);
-
 export int run(int argc, char* argv[], EventStream& stream);
 
 } // namespace xlings::xself
diff --git a/src/core/xself/doctor.cpp b/src/core/xself/doctor.cpp
index c17234d6..df16ead9 100644
--- a/src/core/xself/doctor.cpp
+++ b/src/core/xself/doctor.cpp
@@ -2101,7 +2101,10 @@ void repair_other_subos_(const DoctorState& st, RepairReport& out) {
     }
 }
 
-void repair_payloads_(const DoctorState& st, const Scan& scan, const CoordinateProbe& probe, bool dryRun, RepairReport& out, const std::function<void(std::string_view)>& onStep) {
+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.
@@ -2226,7 +2229,9 @@ void repair_inactive_(const Scan& scan, const std::string& client,
     }
 }
 
-void repair_incomplete_(const Scan& scan, const CommandRunner& run, bool dryRun, RepairReport& out, const std::function<void(std::string_view)>& onStep) {
+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;
diff --git a/src/core/xself/doctor.cppm b/src/core/xself/doctor.cppm
index e5fb212f..93d42265 100644
--- a/src/core/xself/doctor.cppm
+++ b/src/core/xself/doctor.cppm
@@ -294,34 +294,6 @@ constexpr std::string_view shim_ext_ = ".exe";
 constexpr std::string_view shim_ext_ = "";
 #endif
 
-std::string shim_filename_(const std::string& name);
-
-DoctorState load_state_();
-
-// 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);
-
-// 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);
 
 // ── detection ────────────────────────────────────────────────────────
 
@@ -344,89 +316,6 @@ struct AuditSelection {
         onProgress;
 };
 
-fs::path audit_payload_dir_(const xim::PackageMatch& match);
-
-// 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);
-
-// 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);
-
-// 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);
-
-// 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);
-
 Scan detect_(const DoctorState& st, const CoordinateProbe& probe,
              const AuditSelection& audit);
 
@@ -456,108 +345,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);
-
-// 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);
-
-// 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);
-
-// ── 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 = {});
-
-// 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);
-
-// 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 = {});
-
-// 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);
-
 // ── render ───────────────────────────────────────────────────────────
 
 struct Counts {
@@ -576,11 +363,6 @@ struct Counts {
     }
 };
 
-Counts count_(const Scan& scan);
-
-void render_(const Scan& scan, const RepairReport& repair, bool fix,
-             bool dryRun, bool verbose, EventStream& stream);
-
 // ── the command ──────────────────────────────────────────────────────
 
 export int cmd_doctor(EventStream& stream, bool fix,
diff --git a/src/core/xself/init.cppm b/src/core/xself/init.cppm
index b14286a1..9cc47031 100644
--- a/src/core/xself/init.cppm
+++ b/src/core/xself/init.cppm
@@ -58,45 +58,6 @@ std::size_t ensure_subos_shims(const fs::path& target_bin_dir,
                                const fs::path& shim_src,
                                const fs::path& pkg_root);
 
-static void ensure_parent_dirs_(const fs::path& file);
-
-static void write_if_missing_(const fs::path& path, std::string_view 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);
-
-// 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);
-
-// 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);
-
-// 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);
-
 bool ensure_home_layout(const fs::path& home_dir);
 
 // `xlings self init` — bootstrap (or repair) the home directory layout.
diff --git a/src/core/xself/install.cppm b/src/core/xself/install.cppm
index f8c870b8..23c8e39b 100644
--- a/src/core/xself/install.cppm
+++ b/src/core/xself/install.cppm
@@ -17,69 +17,6 @@ namespace xlings::xself {
 
 namespace fs = std::filesystem;
 
-static std::string read_version_from_json(const fs::path& homeDir);
-
-static std::optional<std::string> normalize_mirror_(std::string mirror);
-
-static std::string read_mirror_from_json_(const fs::path& configPath);
-
-static std::optional<std::string> env_install_mirror_();
-
-static std::string detect_install_mirror_();
-
-static void set_mirror_fields_(nlohmann::json& json, const std::string& mirror);
-
-static void configure_install_mirror_(const fs::path& targetHome,
-                                      const std::string& existingMirror,
-                                      bool overwriteDataSubos);
-
-/// 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);
-
-static fs::path detect_source_dir();
-
-static fs::path detect_existing_home();
-
-static fs::path default_home();
-
-static void copy_directory_contents(const fs::path& src, const fs::path& dst);
-
-static void setup_shell_profiles(const fs::path& homeDir);
-
-// 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_();
-
-// `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_();
-
-// 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);
-
 export int cmd_install();
 
 } // namespace xlings::xself
diff --git a/src/core/xself/uninstall.cppm b/src/core/xself/uninstall.cppm
index 60477a44..7fde1fd3 100644
--- a/src/core/xself/uninstall.cppm
+++ b/src/core/xself/uninstall.cppm
@@ -34,40 +34,10 @@ 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);
-
-static std::string format_bytes_(std::uintmax_t bytes);
-
-// 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);
-
-// 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_();
-
 #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);
-#endif
-
-static int print_summary_(const fs::path& home,
-                          const UninstallOpts& opts,
-                          std::uintmax_t dataSize,
-                          std::uintmax_t totalSize);
 
-static bool prompt_yes_no_(const std::string& question);
-
-// 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);
+#endif
 
-static void emit_shell_advisory_(const fs::path& home);
 
 export int cmd_uninstall(UninstallOpts opts);
 
diff --git a/src/core/xvm/bindings.cpp b/src/core/xvm/bindings.cpp
index d9f06986..74d5266f 100644
--- a/src/core/xvm/bindings.cpp
+++ b/src/core/xvm/bindings.cpp
@@ -563,3 +563,20 @@ bool is_binding_root(const VersionDB& db,
 }
 
 }
+
+
+// ── 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 44ab447c..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.
@@ -169,39 +167,13 @@ BindingError binding_error_(BindingErrorKind kind,
                             const std::string& version,
                             std::string message);
 
-bool same_group_identity_(const BindingGroupRef& lhs,
-                          const BindingGroupRef& rhs);
-
-bool same_group_(const BindingGroupRef& lhs, const BindingGroupRef& rhs);
-
-bool supported_kind_(std::string_view kind);
-
-std::optional<std::string_view>
-canonical_manifest_path_(const VData& data);
-
 bool has_canonical_manifest_(const VData& data);
 
-BindingError metadata_integrity_error_(
-    const std::string& target,
-    const std::string& version,
-    std::string_view code,
-    std::string_view path);
-
 std::optional<BindingError>
 binding_integrity_error_(const VData& data,
                          const std::string& target,
                          const std::string& version);
 
-std::string json_pointer_token_(std::string_view token);
-
-std::optional<BindingError>
-root_content_integrity_error_(const VData& root,
-                              const std::string& target,
-                              const std::string& version);
-
-std::optional<std::string_view>
-invalid_group_identity_path_(const BindingGroupRef& group);
-
 std::optional<BindingError>
 group_identity_integrity_error_(const BindingGroupRef& group,
                                 const std::string& target,
diff --git a/src/core/xvm/inspect.cpp b/src/core/xvm/inspect.cpp
index 7dbb135d..a0860933 100644
--- a/src/core/xvm/inspect.cpp
+++ b/src/core/xvm/inspect.cpp
@@ -613,3 +613,24 @@ std::size_t apply_dangling_edge_pruning(VersionDB& db,
 }
 
 }
+
+
+// ── 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 55418a54..40675582 100644
--- a/src/core/xvm/inspect.cppm
+++ b/src/core/xvm/inspect.cppm
@@ -20,36 +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);
-
-// 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);
-
 }  // namespace xlings::xvm::detail_
 
 export namespace xlings::xvm {
@@ -205,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
@@ -269,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.
@@ -300,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.
diff --git a/src/core/xvm/lock.cpp b/src/core/xvm/lock.cpp
index 23dd8bfc..4ab03c91 100644
--- a/src/core/xvm/lock.cpp
+++ b/src/core/xvm/lock.cpp
@@ -64,3 +64,47 @@ std::expected<StateLock, std::string> acquire_state_lock(const std::filesystem::
 }
 
 }
+
+
+// ── 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 3bddc5f6..db245019 100644
--- a/src/core/xvm/lock.cppm
+++ b/src/core/xvm/lock.cppm
@@ -60,47 +60,23 @@ 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 };
diff --git a/src/core/xvm/owner.cpp b/src/core/xvm/owner.cpp
index f075a7ab..6782cfd7 100644
--- a/src/core/xvm/owner.cpp
+++ b/src/core/xvm/owner.cpp
@@ -118,3 +118,21 @@ owner_candidates(const VersionDB& db,
 }
 
 }
+
+
+// ── 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 58ed7a4e..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;
diff --git a/src/core/xvm/registration.cppm b/src/core/xvm/registration.cppm
index b76eb37a..f7fdfaa7 100644
--- a/src/core/xvm/registration.cppm
+++ b/src/core/xvm/registration.cppm
@@ -146,61 +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);
-
-bool same_registration_group_(
-    const BindingGroupRef& lhs,
-    const BindingGroupRef& rhs);
-
-RegistrationGroupIdentity registration_group_identity_(
-    const BindingGroupRef& group);
-
-// 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);
-
-std::string effective_source_name_(
-    const std::string& target,
-    const VInfo& info,
-    const VData& data,
-    std::string_view kind);
-
-std::string effective_destination_name_(
-    const std::string& target,
-    const VData& data,
-    std::string_view kind,
-    std::string_view sourceName);
-
-std::optional<std::string> legacy_payload_mismatch_(
-    const RegistrationNode& node,
-    const VInfo& info,
-    const VData& data);
-
-std::string registration_path_token_(std::string_view token);
-
-// 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);
-
-// Is `candidate` the same payload as `root`, or something inside it?
-bool payload_path_covers_(std::string_view root, std::string_view candidate);
-
-void erase_exact_registration_edges_(
-    VersionDB& db,
-    const std::set<RegistrationExactKey>& exactNodes);
-
 }  // namespace xlings::xvm::detail_
 
 namespace xlings::xvm {
diff --git a/src/core/xvm/switch_plan.cppm b/src/core/xvm/switch_plan.cppm
index 18ad1ebd..b0f9db0d 100644
--- a/src/core/xvm/switch_plan.cppm
+++ b/src/core/xvm/switch_plan.cppm
@@ -23,15 +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);
-
 }  // namespace xlings::xvm::detail_
 
 export namespace xlings::xvm {
diff --git a/src/interface.cpp b/src/interface.cpp
index 07cef718..07553e87 100644
--- a/src/interface.cpp
+++ b/src/interface.cpp
@@ -197,3 +197,107 @@ int run(const mcpplibs::cmdline::ParsedArgs& args,
 }
 
 }
+
+
+// ── 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 154aa260..b607dfac 100644
--- a/src/interface.cppm
+++ b/src/interface.cppm
@@ -36,107 +36,27 @@ std::string event_to_ndjson_line_(const Event& e);
 // 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() {
-        if (heartbeat_thread_.joinable()) heartbeat_thread_.request_stop();
-        if (stdin_thread_.joinable())     stdin_thread_.request_stop();
-    }
+    InterfaceSession(EventStream& stream, CancellationToken& token);
+
+    ~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);
-    }
-
-    bool saw_error() const { return saw_error_.load(std::memory_order_relaxed); }
-
-    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_event(const Event& e);
+
+    bool saw_error() const;
+
+    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 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 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 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 emit_raw_line_(std::string_view s);
+
+    void heartbeat_loop_(std::stop_token st);
+
+    void stdin_loop_(std::stop_token st);
+
+    void handle_stdin_line_(std::string_view line);
 
     EventStream& stream_;
     CancellationToken& token_;
diff --git a/src/libs/sha256.cpp b/src/libs/sha256.cpp
index b0156da1..fa89697a 100644
--- a/src/libs/sha256.cpp
+++ b/src/libs/sha256.cpp
@@ -31,3 +31,99 @@ std::optional<std::string> hex_file(const std::filesystem::path& path) {
 }
 
 }
+
+
+// ── 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 7fcddd0f..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]{};
diff --git a/src/libs/tinyhttps.cpp b/src/libs/tinyhttps.cpp
index b678d006..eb0e39a8 100644
--- a/src/libs/tinyhttps.cpp
+++ b/src/libs/tinyhttps.cpp
@@ -335,3 +335,37 @@ std::int64_t query_content_length(const std::string& url, int connectTimeoutSec)
 }
 
 }
+
+
+// ── 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 f628902f..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_;
diff --git a/src/platform.cpp b/src/platform.cpp
index 6ea5e87b..4a4d9330 100644
--- a/src/platform.cpp
+++ b/src/platform.cpp
@@ -15,10 +15,6 @@ module;
 module xlings.platform;
 
 import std;
-import :linux;
-import :macos;
-import :windows;
-import :unix;
 
 namespace xlings {
 
diff --git a/src/platform.cppm b/src/platform.cppm
index 446fa443..590fc58e 100644
--- a/src/platform.cppm
+++ b/src/platform.cppm
@@ -25,8 +25,6 @@ export import :unix;
 namespace xlings {
 namespace platform {
 
-    extern std::string gRundir;
-
     export using platform_impl::PATH_SEPARATOR;
     export using platform_impl::OS_NAME;
     export using platform_impl::clear_console;
diff --git a/src/platform/target.cpp b/src/platform/target.cpp
index f276e361..6073d77d 100644
--- a/src/platform/target.cpp
+++ b/src/platform/target.cpp
@@ -51,3 +51,12 @@ const Target& host() {
 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 880a8170..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
diff --git a/src/platform/unix.cpp b/src/platform/unix.cpp
index f7085590..4f2b3127 100644
--- a/src/platform/unix.cpp
+++ b/src/platform/unix.cpp
@@ -228,3 +228,68 @@ std::string home_for_user_(const std::string& name) {
  // 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 d1a8b47c..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;
-        }
-
-        void release() {
-            if (fd_ < 0) return;
-            ::flock(fd_, LOCK_UN);
-            ::close(fd_);
-            fd_ = -1;
-        }
+                     std::string& error);
+
+        void release();
 
     private:
         int fd_ { -1 };
@@ -116,12 +75,6 @@ namespace platform_impl {
     export std::string read_terminal_query_reply(int fd,
                                                  std::chrono::milliseconds timeout);
 
-    // 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_();
-
     // Query the controlling terminal for its background color via the
     // OSC-11 sequence (xterm spec, supported by xterm / iTerm2 / Alacritty
     // / Kitty / WezTerm / modern Windows Terminal). Returns std::nullopt
diff --git a/src/platform/windows.cpp b/src/platform/windows.cpp
index b6460619..0597b969 100644
--- a/src/platform/windows.cpp
+++ b/src/platform/windows.cpp
@@ -342,3 +342,66 @@ bool atomic_swap_paths(const std::filesystem::path& a,
 }
 
 #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 b1576d4c..70b103c3 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 };
diff --git a/src/runtime/cancellation.cpp b/src/runtime/cancellation.cpp
new file mode 100644
index 00000000..3f02b735
--- /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..53b51575
--- /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..0bb57a2d 100644
--- a/src/runtime/capability.cppm
+++ b/src/runtime/capability.cppm
@@ -25,9 +25,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 +33,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..f77e39d9
--- /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..48764a29
--- /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
index c94590bd..dd32628a 100644
--- a/src/ui/banner.cpp
+++ b/src/ui/banner.cpp
@@ -7,8 +7,6 @@ module;
 module xlings.ui;
 
 import std;
-import :theme;
-import :layout;
 
 namespace xlings::ui {
 
diff --git a/src/ui/info_panel.cpp b/src/ui/info_panel.cpp
index 47915409..8fcb36e1 100644
--- a/src/ui/info_panel.cpp
+++ b/src/ui/info_panel.cpp
@@ -8,8 +8,6 @@ module xlings.ui;
 
 import std;
 import xlings.core.palette;
-import :theme;
-import :layout;
 
 namespace xlings::ui {
 
diff --git a/src/ui/progress.cpp b/src/ui/progress.cpp
index f7056a46..387b6062 100644
--- a/src/ui/progress.cpp
+++ b/src/ui/progress.cpp
@@ -8,8 +8,6 @@ module xlings.ui;
 
 import std;
 import xlings.core.palette;
-import :theme;
-import :layout;
 
 namespace xlings::ui {
 
diff --git a/src/ui/selector.cpp b/src/ui/selector.cpp
index 37ab940b..6b897bf0 100644
--- a/src/ui/selector.cpp
+++ b/src/ui/selector.cpp
@@ -9,8 +9,6 @@ module xlings.ui;
 
 import std;
 import xlings.core.palette;
-import :theme;
-import :layout;
 
 namespace xlings::ui {
 
diff --git a/src/ui/table.cpp b/src/ui/table.cpp
index da883078..40578b9d 100644
--- a/src/ui/table.cpp
+++ b/src/ui/table.cpp
@@ -8,8 +8,6 @@ module;
 module xlings.ui;
 
 import std;
-import :theme;
-import :layout;
 
 namespace xlings::ui {
 

From b8e156678d2a60c12824e3a0987571d6726a68b0 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 09:53:52 +0800
Subject: [PATCH 05/19] fix(tools): outline.py must be idempotent, and
 out-of-line bodies need dedenting

Two defects in the phase-2 tool, both found by reading its output rather than
by a compiler.

**Re-running stacked copies.** outline.py appends its section to the .cpp. That
was fine while the generated files were untracked -- `git clean` removed them
between runs -- and silently wrong once they were committed: clean leaves a
tracked file, and split.py does not rewrite the ones outline.py creates itself.
Three regenerations left three definitions of `TaskManager::TaskManager` in
task.cpp and two of `UsageSkill::name`. It now truncates at its own banner
before writing, and regen.sh removes generated files by diffing the tree against
the base ref instead of trusting `git clean`.

**Indentation.** A member body carries the class's indentation, so 3,845 lines
of out-of-line definitions came out one level too deep with their closing brace
hanging in mid-air, and `.strip()` had eaten the space before the opening brace.
Bodies are now dedented by the member's own indent.

Verified on the regenerated tree: no duplicate banners, and the only repeated
declarator-ids are genuine overloads (`Config::display_path` on path and string,
`Installer::Installer` on IndexManager and PackageCatalog). Build clean.
---
 .agents/tools/module-split/outline.py |   53 +-
 .agents/tools/module-split/regen.sh   |   37 +
 src/agent/skills/contributing.cpp     |   12 +-
 src/agent/skills/skill.cpp            |   30 +-
 src/agent/skills/usage.cpp            |   36 +-
 src/capabilities.cpp                  |  900 +++++-----
 src/core/cmdprocessor.cpp             |   56 +-
 src/core/config.cpp                   | 1958 ++++++++++----------
 src/core/semver.cpp                   |    6 +-
 src/core/subos/graphics.cpp           |   42 +-
 src/core/xim/catalog.cpp              |  670 +++----
 src/core/xim/index.cpp                |  236 +--
 src/core/xim/indexfetch.cpp           |    6 +-
 src/core/xim/install_state.cpp        |   52 +-
 src/core/xim/installer.cpp            | 2362 ++++++++++++-------------
 src/core/xim/inventory.cpp            |  184 +-
 src/core/xim/libxpkg/types/type.cpp   |   16 +-
 src/core/xvm/bindings.cpp             |   14 +-
 src/core/xvm/inspect.cpp              |   20 +-
 src/core/xvm/lock.cpp                 |   62 +-
 src/core/xvm/owner.cpp                |   18 +-
 src/interface.cpp                     |  162 +-
 src/libs/sha256.cpp                   |  160 +-
 src/libs/tinyhttps.cpp                |   42 +-
 src/platform/target.cpp               |    4 +-
 src/platform/unix.cpp                 |   90 +-
 src/platform/windows.cpp              |   88 +-
 src/runtime/cancellation.cpp          |   64 +-
 src/runtime/capability.cpp            |   44 +-
 src/runtime/event_stream.cpp          |  126 +-
 src/runtime/task.cpp                  |  242 +--
 31 files changed, 3937 insertions(+), 3855 deletions(-)
 create mode 100644 .agents/tools/module-split/regen.sh

diff --git a/.agents/tools/module-split/outline.py b/.agents/tools/module-split/outline.py
index 33e3c2bb..2f6e126c 100644
--- a/.agents/tools/module-split/outline.py
+++ b/.agents/tools/module-split/outline.py
@@ -200,6 +200,35 @@ def qualify(head: str, cls: str, nested: set[str], fn: str) -> str:
     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))
@@ -255,10 +284,11 @@ def outline_class(cls_item: Item, ns: str, outer: str, out_impl: list,
             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()
-                    + init + it.body + it.tail))
+                            qual, nested, cname).strip() + ' '
+                    + dedent(init + it.body + it.tail, ind).lstrip(' ')))
                 stats['members'] += 1
                 stats['lines'] += it.body.count('\n')
                 keep = False
@@ -312,6 +342,12 @@ def group_by_namespace(out_impl: list) -> str:
     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
 
 
@@ -335,6 +371,16 @@ def process(path: str, write: bool):
         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
@@ -351,8 +397,7 @@ def process(path: str, write: bool):
                 head += '\n' + '\n'.join(imports) + '\n'
             open(cpp, 'w').write(head)
         with open(cpp, 'a') as fh:
-            fh.write('\n\n// ── out-of-line class members '
-                     '─────────────────────────────────\n\n')
+            fh.write('\n\n' + BANNER + '\n\n')
             fh.write(group_by_namespace(out_impl) + '\n')
     return stats['members'], stats['lines'], None
 
diff --git a/.agents/tools/module-split/regen.sh b/.agents/tools/module-split/regen.sh
new file mode 100644
index 00000000..68aea8b3
--- /dev/null
+++ b/.agents/tools/module-split/regen.sh
@@ -0,0 +1,37 @@
+#!/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
+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/src/agent/skills/contributing.cpp b/src/agent/skills/contributing.cpp
index 644f8042..a2849c1e 100644
--- a/src/agent/skills/contributing.cpp
+++ b/src/agent/skills/contributing.cpp
@@ -7,16 +7,16 @@ import std;
 import xlings.agent.skill;
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::agent::skills {
 
-auto ContributingSkill::name() const -> std::string_view{ return "contributing"; }
+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::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; }
+auto ContributingSkill::content() const -> std::string_view { return kContent; }
 
 } // namespace xlings::agent::skills
diff --git a/src/agent/skills/skill.cpp b/src/agent/skills/skill.cpp
index f0b925f3..8c4b35df 100644
--- a/src/agent/skills/skill.cpp
+++ b/src/agent/skills/skill.cpp
@@ -14,27 +14,27 @@ module xlings.agent.skill;
 import std;
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::agent {
 
-void SkillRegistry::add(std::unique_ptr<Skill> skill){
-        skills_.push_back(std::move(skill));
-    }
+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::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::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();
-    }
+auto SkillRegistry::count() const -> std::size_t {
+    return skills_.size();
+}
 
 } // namespace xlings::agent
diff --git a/src/agent/skills/usage.cpp b/src/agent/skills/usage.cpp
index 847f2e3a..6cbbaf58 100644
--- a/src/agent/skills/usage.cpp
+++ b/src/agent/skills/usage.cpp
@@ -8,26 +8,26 @@ import xlings.agent.skill;
 import xlings.cli.spec;
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── 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;
-    }
+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/capabilities.cpp b/src/capabilities.cpp
index 148f70fe..d9bbf22a 100644
--- a/src/capabilities.cpp
+++ b/src/capabilities.cpp
@@ -54,506 +54,506 @@ capability::Registry build_registry() {
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── 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::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 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::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) -> 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 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::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 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::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 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::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 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::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 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::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 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::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 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::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 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::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 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::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);
-            }
+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);
     }
+    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::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 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::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));
-            }
+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);
     }
+    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::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 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::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 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::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 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::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 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"}});
     }
-
-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,
-        };
+    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::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 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 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;
-                    }
+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,
-        };
-    }
+            }
+            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::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);
-        }
+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,
+    };
+}
 
-        // "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 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::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);
-    }
+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/core/cmdprocessor.cpp b/src/core/cmdprocessor.cpp
index a3f86e3c..e0678042 100644
--- a/src/core/cmdprocessor.cpp
+++ b/src/core/cmdprocessor.cpp
@@ -292,42 +292,42 @@ CommandProcessor create_processor() {
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── 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();
+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;
+}
 
-        std::string cmd = argv[1];
-        if (cmd == "help" || cmd == "--help" || cmd == "-h" || cmd == "--version") {
-            return print_help();
-        }
+int CommandProcessor::run(int argc, char* argv[]) {
+    if (argc <= 1) return print_help();
 
-        for (const auto& c : commands_) {
-            if (c.name == cmd) return c.func(argc, argv);
-        }
+    std::string cmd = argv[1];
+    if (cmd == "help" || cmd == "--help" || cmd == "-h" || cmd == "--version") {
+        return print_help();
+    }
 
-        log::error("Unknown command: {}", cmd);
-        std::println("Use 'xlings help' for usage information");
-        return 1;
+    for (const auto& c : commands_) {
+        if (c.name == cmd) return c.func(argc, argv);
     }
 
-int CommandProcessor::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;
+    log::error("Unknown command: {}", cmd);
+    std::println("Use 'xlings help' for usage information");
+    return 1;
+}
+
+int CommandProcessor::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;
+}
 
 } // namespace xlings::cmdprocessor
diff --git a/src/core/config.cpp b/src/core/config.cpp
index f9688519..473372f3 100644
--- a/src/core/config.cpp
+++ b/src/core/config.cpp
@@ -61,1166 +61,1166 @@ std::vector<IndexRepo> parse_index_repos_json(const nlohmann::json& json,
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings {
 
-void Config::override_home(const std::filesystem::path& home){
-        home_override_() = home;
-    }
+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::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} };
+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" } },
-        };
-    }
+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::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));
-            }
-        };
+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>());
-            }
+    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;
     }
+    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::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);
-            }
-        };
+                                                 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);
-        };
+    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"]);
-            }
+    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"]);
-            }
+    // 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("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("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"]);
-                    }
+        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;
+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"]);
         }
-        return {};
+    } 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_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;
-        }
+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::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);
-            }
+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;
     }
+    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_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_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_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_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::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::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::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_);
+[[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 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 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 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);
-    }
+    auto fallback = lookup_resource_servers_in_(default_resource_servers_(), "GLOBAL");
+    if (!fallback.empty()) return fallback;
+    return {};
+}
 
-[[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;
-            }
+[[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);
         }
-
-        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::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;
+}
 
-        {
-            std::scoped_lock lock(resourceServerMutex_);
-            selectedResourceServerCache_[key] = selected;
+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;
         }
-        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 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;
+            }
         }
-        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";
+    {
+        std::scoped_lock lock(resourceServerMutex_);
+        selectedResourceServerCache_[key] = selected;
     }
+    return selected;
+}
 
-Config::Config(){
-        namespace fs = std::filesystem;
+[[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};
+}
 
-        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; }
-                }
-            }
+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) {
-                paths_.homeDir       = candidate;
-                paths_.selfContained = true;
-            } else {
-                paths_.homeDir = fs::path(platform::get_home_dir()) / ".xlings";
+                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; }
             }
         }
-
-        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_);
+        if (isSelfContained) {
+            paths_.homeDir       = candidate;
+            paths_.selfContained = true;
         } 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_.homeDir = fs::path(platform::get_home_dir()) / ".xlings";
         }
-
-        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());
+    auto configPath = paths_.homeDir / ".xlings.json";
+    if (fs::exists(configPath)) {
         try {
-            auto content = platform::read_file_to_string(cfg.string());
-            auto json = nlohmann::json::parse(content, nullptr, false);
+            auto content = platform::read_file_to_string(configPath.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;
+                if (json.contains("activeSubos") && json["activeSubos"].is_string()) {
+                    auto val = json["activeSubos"].get<std::string>();
+                    if (!val.empty()) globalActiveSubos_ = val;
                 }
-                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);
-                    }
-                }
+                // 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));
+            }
+        }
+    }
 
-void Config::load_project_config_(){
-        namespace fs = std::filesystem;
-        std::error_code ec;
+    paths_.dataDir  = paths_.homeDir / "data";
+    update_effective_paths_();
 
-        fs::path startDir = fs::current_path(ec);
-        if (ec) return;
+    log::debug("config: home={}, selfContained={}", paths_.homeDir.string(), paths_.selfContained);
 
-        auto homeNorm = fs::weakly_canonical(paths_.homeDir, ec);
+    // 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_();
 
-        // 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-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;
                 }
-                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);
-                    }
+            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_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_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_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::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::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 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);
+}
 
-[[nodiscard]] std::vector<std::string> Config::workspace_install_targets(const xvm::Workspace& ws){
-        return workspace_targets_from_workspace_(ws);
+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;
-    }
+                                                        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;
-        }
+                                                         ProjectSubosMode mode) {
+    if (mode == ProjectSubosMode::Named) {
+        auto ws = projectWorkspace;
+        merge_workspace_into_(ws, projectSubosWorkspace);
+        return ws;
+    }
 
-        return globalWorkspace;
+    if (mode == ProjectSubosMode::Anonymous) {
+        auto ws = globalWorkspace;
+        merge_workspace_into_(ws, projectWorkspace);
+        merge_workspace_into_(ws, projectSubosWorkspace);
+        return ws;
     }
 
-void Config::reload_state(){ instance_().reload_state_(); }
+    return globalWorkspace;
+}
+
+void Config::reload_state() { instance_().reload_state_(); }
 
-[[nodiscard]] const Config::PathInfo& Config::paths(){ return instance_().paths_; }
+[[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();
-    }
+            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]] 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::mirror() { return instance_().mirror_; }
 
-[[nodiscard]] const std::string& Config::lang(){ return instance_().lang_; }
+[[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(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::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::resource_server(std::string_view mirror) {
+    return instance_().selected_resource_server_for_(mirror);
+}
 
-[[nodiscard]] std::string Config::index_base(){ return instance_().indexBase_; }
+[[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() {
+    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]] 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::global_versions() { return instance_().globalVersions_; }
 
-[[nodiscard]] const xvm::VersionDB& Config::project_versions(){ return instance_().projectVersions_; }
+[[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::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_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_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_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::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]] 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::global_index_repos() {
+    return instance_().globalIndexRepos_;
+}
 
-[[nodiscard]] const std::vector<IndexRepo>& Config::project_index_repos(){
-        return instance_().projectIndexRepos_;
-    }
+[[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]] 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;
-    }
+                                                            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);
+                                                                   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 {};
+        // 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();
+    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();
-    }
+    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();
-    }
+                                                   bool projectScope) {
+    return !resolve_repo_source(repo, projectScope).empty();
+}
 
-[[nodiscard]] const std::filesystem::path& Config::project_dir(){
-        return instance_().projectDir_;
-    }
+[[nodiscard]] const std::filesystem::path& Config::project_dir() {
+    return instance_().projectDir_;
+}
 
-[[nodiscard]] ProjectSubosMode Config::project_subos_mode(){
-        return instance_().projectSubosMode_;
-    }
+[[nodiscard]] ProjectSubosMode Config::project_subos_mode() {
+    return instance_().projectSubosMode_;
+}
 
-[[nodiscard]] const std::string& Config::project_subos_name(){
-        return instance_().projectSubosName_;
-    }
+[[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]] 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]] 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]] 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]] 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]] 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_; }
+[[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_();
-    }
+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::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;
-    }
+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_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::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]] std::filesystem::path Config::xvm_artifact_subos_dir() {
+    return instance_().resolve_subos_scope_().root;
+}
 
-[[nodiscard]] SubosScope Config::subos_scope(){
-        return instance_().resolve_subos_scope_();
-    }
+[[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::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;
     }
+    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(); }
-        }
+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_();
 
-        auto& versions = useGlobal ? self.globalVersions_ : self.projectVersions_;
-        json["versions"] = xvm::versions_to_json(versions);
-        platform::write_string_to_file(configPath.string(), json.dump(2));
+    if (!useGlobal) {
+        auto projectHomeDir = self.project_home_dir_();
+        if (!projectHomeDir.empty()) fs::create_directories(projectHomeDir);
     }
 
-[[nodiscard]] std::string Config::recorded_client_version(){
-        namespace fs = std::filesystem;
-        auto configPath = instance_().paths_.homeDir / ".xlings.json";
-        if (!fs::exists(configPath)) return {};
+    nlohmann::json 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() || !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));
+            json = nlohmann::json::parse(content, nullptr, false);
+            if (json.is_discarded()) json = nlohmann::json::object();
+        } catch (...) { json = nlohmann::json::object(); }
     }
 
-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";
-        }
+    auto& versions = useGlobal ? self.globalVersions_ : self.projectVersions_;
+    json["versions"] = xvm::versions_to_json(versions);
+    platform::write_string_to_file(configPath.string(), json.dump(2));
+}
 
-        // 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(); }
-        }
+[[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 {}; }
+}
 
-        // 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::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::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));
+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("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));
+}
+
 } // namespace xlings
diff --git a/src/core/semver.cpp b/src/core/semver.cpp
index 35a2968d..7fbe99e4 100644
--- a/src/core/semver.cpp
+++ b/src/core/semver.cpp
@@ -5,12 +5,12 @@ module xlings.core.semver;
 import std;
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::semver {
 
-Segment Segment::number(unsigned long long v){ return {true, v, {}}; }
+Segment Segment::number(unsigned long long v) { return {true, v, {}}; }
 
-Segment Segment::alpha(std::string t){ return {false, 0, std::move(t)}; }
+Segment Segment::alpha(std::string t) { return {false, 0, std::move(t)}; }
 
 } // namespace xlings::semver
diff --git a/src/core/subos/graphics.cpp b/src/core/subos/graphics.cpp
index f7fcc8ab..251758ff 100644
--- a/src/core/subos/graphics.cpp
+++ b/src/core/subos/graphics.cpp
@@ -280,34 +280,34 @@ std::string describe(const VendorWiring& v) {
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::subos::graphics {
 
-bool VendorWiring::is_broken() const{ return state == "broken"; }
+bool VendorWiring::is_broken() const { return state == "broken"; }
 
-bool VendorWiring::needs_transitive_consumer() const{
-        return state == "needs-transitive-consumer";
-    }
+bool VendorWiring::needs_transitive_consumer() const {
+    return state == "needs-transitive-consumer";
+}
 
-bool VendorWiring::is_ok() const{
-        return !stale && (state == "ok" || state == "native");
-    }
+bool VendorWiring::is_ok() const {
+    return !stale && (state == "ok" || state == "native");
+}
 
-bool GraphicsWiring::has_dispatch() const{ return status != WiringStatus::NoDispatch; }
+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(); }));
-    }
+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;
-    }
+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/xim/catalog.cpp b/src/core/xim/catalog.cpp
index a03a1d4b..aa60bcb8 100644
--- a/src/core/xim/catalog.cpp
+++ b/src/core/xim/catalog.cpp
@@ -305,396 +305,396 @@ resolve_local_coordinate(const PackageCatalog& catalog,
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── 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()) {
+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 = 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,
+                .dir = subDir,
                 .scope = PackageScope::Global,
-                .defaultNamespace = globalRepos[i].name,
+                .defaultNamespace = repo.name,
+                .subIndex = true,
             });
         }
+    }
 
-        // 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")) {
+    // 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 = "local",
-                .url = "",
-                .dir = localRepoDir,
-                .scope = PackageScope::Global,
-                .defaultNamespace = "local",
+                .name = repo.name,
+                .url = repo.url,
+                .dir = subDir,
+                .scope = PackageScope::Project,
+                .defaultNamespace = repo.name,
+                .subIndex = true,
             });
         }
-
-        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;
+    // 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",
+        });
     }
 
-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;
+    return specs;
+}
 
-        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;
+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::optional<std::string> matched;
-            if (state.index.find_entry(resolved)) {
-                matched = resolved;
-            } else {
-                matched = state.index.match_version(resolved);
-            }
-            if (!matched) continue;
+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;
 
-            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;
-                }
+    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;
+        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));
-                    }
+                                               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));
         }
+    };
+    collect(projectRepos_);
+    collect(globalRepos_);
 
-        // Merge: either explicit namespace or no primary match
-        for (auto& m : subMatches) {
-            primaryMatches.push_back(std::move(m));
-        }
+    // 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));
     }
 
-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));
-            }
-        }
+    // 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));
+}
 
-        loaded_ = !projectRepos_.empty() || !globalRepos_.empty();
-        if (!loaded_) {
-            return std::unexpected(loadWarnings_.empty()
-                ? std::string("no index repositories configured")
-                : loadWarnings_.front().error);
+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));
         }
-        return {};
     }
 
-bool PackageCatalog::is_loaded() const{ return loaded_; }
+    loaded_ = !projectRepos_.empty() || !globalRepos_.empty();
+    if (!loaded_) {
+        return std::unexpected(loadWarnings_.empty()
+            ? std::string("no index repositories configured")
+            : loadWarnings_.front().error);
+    }
+    return {};
+}
 
-const std::vector<RepoLoadWarning>& PackageCatalog::load_warnings() const{ return loadWarnings_; }
+bool PackageCatalog::is_loaded() const { return loaded_; }
 
-std::vector<PackageMatch> PackageCatalog::prefer_project_scope_(std::vector<PackageMatch> matches){
-        return detail_::prefer_project_scope_(std::move(matches));
-    }
+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());
+                            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;
-                }
+                   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));
-                        }
+        // 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));
-        };
+    append(projectRepos_);
+    append(globalRepos_);
+    return detail_::dedupe_matches_(std::move(results));
+}
 
-        auto result = match.scope == PackageScope::Project
-            ? load(projectRepos_) : load(globalRepos_);
-        if (result) packageCache_.emplace(key, *result);
-        return result;
+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;
     }
 
-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;
-                }
+    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_);
         }
+    };
+    if (match.scope == PackageScope::Project) {
+        update(projectRepos_);
+    } else {
+        update(globalRepos_);
     }
+}
 
 } // namespace xlings::xim
diff --git a/src/core/xim/index.cpp b/src/core/xim/index.cpp
index 828dd5f3..f6a974af 100644
--- a/src/core/xim/index.cpp
+++ b/src/core/xim/index.cpp
@@ -165,161 +165,161 @@ CacheResult load_index_cache(const std::filesystem::path& cacheFile,
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::xim {
 
-IndexManager::IndexManager(const std::filesystem::path& repoDir, std::string defaultNamespace): repoDir_(repoDir),
-          defaultNamespace_(std::move(defaultNamespace)) {}
+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;
+void IndexManager::set_repo_dir(const std::filesystem::path& dir) {
+    repoDir_ = dir;
+}
 
-        if (repoDir_.empty()) {
-            return std::unexpected("repo directory not set");
-        }
+void IndexManager::set_default_namespace(std::string defaultNamespace) {
+    defaultNamespace_ = std::move(defaultNamespace);
+}
 
-        if (!fs::exists(repoDir_ / "pkgs")) {
-            return std::unexpected(
-                std::format("pkgs/ directory not found in {}", repoDir_.string()));
-        }
+std::expected<void, std::string> IndexManager::rebuild() {
+    namespace fs = std::filesystem;
 
-        log::debug("building package index from {}", repoDir_.string());
+    if (repoDir_.empty()) {
+        return std::unexpected("repo directory not set");
+    }
 
-        auto result = xpkg::build_index(repoDir_, defaultNamespace_);
-        if (!result) {
-            return std::unexpected(
-                std::format("build_index failed: {}", result.error()));
-        }
+    if (!fs::exists(repoDir_ / "pkgs")) {
+        return std::unexpected(
+            std::format("pkgs/ directory not found in {}", repoDir_.string()));
+    }
 
-        index_ = std::move(*result);
-        loaded_ = true;
+    log::debug("building package index from {}", repoDir_.string());
 
-        log::debug("index built: {} entries", index_.entries.size());
-        return {};
+    auto result = xpkg::build_index(repoDir_, defaultNamespace_);
+    if (!result) {
+        return std::unexpected(
+            std::format("build_index failed: {}", result.error()));
     }
 
-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");
-        }
+    index_ = std::move(*result);
+    loaded_ = true;
 
-        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 {};
-            }
-        }
+    log::debug("index built: {} entries", index_.entries.size());
+    return {};
+}
 
-        // Cache miss or forced: full rebuild
-        auto result = rebuild();
-        if (!result) return result;
+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");
+    }
 
-        // Save cache (best effort)
-        if (!cache_detail_::save_index_cache(
-                index_, cacheFile, repoHeadHash, defaultNamespace_)) {
-            log::warn("failed to save index cache for {}", repoDir_.string());
+    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 {};
         }
+    }
 
-        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());
     }
 
-bool IndexManager::is_loaded() const{ return loaded_; }
+    return {};
+}
 
-std::size_t IndexManager::size() const{ return index_.entries.size(); }
+bool IndexManager::is_loaded() const { return loaded_; }
 
-std::vector<std::string> IndexManager::search(const std::string& keyword) const{
-        return xpkg::search(index_, keyword);
-    }
+std::size_t IndexManager::size() const { return index_.entries.size(); }
 
-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::vector<std::string> IndexManager::search(const std::string& keyword) const {
+    return xpkg::search(index_, keyword);
+}
 
-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::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::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::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::vector<std::string> IndexManager::mutex_packages(const std::string& name) const{
-        return xpkg::mutex_packages(index_, name);
+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::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);
-    }
+std::vector<std::string> IndexManager::mutex_packages(const std::string& name) const {
+    return xpkg::mutex_packages(index_, name);
+}
 
-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;
+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);
+}
 
-void IndexManager::mark_installed(const std::string& name, bool installed){
-        xpkg::set_installed(index_, name, installed);
-    }
+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::merge(xpkg::PackageIndex other, const std::string& ns){
-        index_ = xpkg::merge(std::move(index_), other, ns);
-    }
+void IndexManager::mark_installed(const std::string& name, bool installed) {
+    xpkg::set_installed(index_, name, installed);
+}
 
-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;
+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;
+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_; }
+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;
-    }
+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/indexfetch.cpp b/src/core/xim/indexfetch.cpp
index 3dc451b6..6138cfd7 100644
--- a/src/core/xim/indexfetch.cpp
+++ b/src/core/xim/indexfetch.cpp
@@ -678,12 +678,12 @@ void reconcile_index_temps(const std::filesystem::path& dataDir) {
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::xim {
 
-bool IndexRequirement::empty() const{ return min.empty() && max.empty(); }
+bool IndexRequirement::empty() const { return min.empty() && max.empty(); }
 
-bool ArtifactSource::forge() const{ return !server.empty(); }
+bool ArtifactSource::forge() const { return !server.empty(); }
 
 } // namespace xlings::xim
diff --git a/src/core/xim/install_state.cpp b/src/core/xim/install_state.cpp
index 384fc96e..443dd78d 100644
--- a/src/core/xim/install_state.cpp
+++ b/src/core/xim/install_state.cpp
@@ -94,44 +94,44 @@ bool unverifiable_stamped_payload(const LedgerIndex& ledger,
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::xim {
 
-[[nodiscard]] bool InstallStateReport::is_installed() const{
-        return state == InstallState::Installed;
-    }
+[[nodiscard]] bool InstallStateReport::is_installed() const {
+    return state == InstallState::Installed;
+}
 
-[[nodiscard]] bool InstallStateReport::is_incomplete() const{
-        return state == InstallState::Incomplete;
-    }
+[[nodiscard]] bool InstallStateReport::is_incomplete() const {
+    return state == InstallState::Incomplete;
+}
 
-[[nodiscard]] bool InstallStateReport::should_run_install_hook() const{
-        return state != InstallState::Installed;
-    }
+[[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));
-                }
+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),
-        });
-    }
+                                  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(); }
+[[nodiscard]] std::size_t LedgerIndex::size() const { return coords_.size(); }
 
 } // namespace xlings::xim
diff --git a/src/core/xim/installer.cpp b/src/core/xim/installer.cpp
index acad40e9..bfd014d1 100644
--- a/src/core/xim/installer.cpp
+++ b/src/core/xim/installer.cpp
@@ -1966,1321 +1966,1321 @@ std::vector<std::string> unfulfilled_program_promises_(const InstallPlan& plan)
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── 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_(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);
-    }
+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(IndexManager& index) : index_(&index) {}
 
-Installer::Installer(PackageCatalog& catalog): catalog_(&catalog) {}
+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::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){
+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;
-            }
+    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;
+        // 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);
-            }
+        // 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;
-            }
+        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);
-            }
+        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);
 
-            // Add remaining mirrors as fallbacks
-            if (!resource->mirrors.empty()) {
-                for (auto& [key, mirrorUrl] : resource->mirrors) {
-                    if (mirrorUrl != resource->url) {
-                        task.fallbackUrls.push_back(mirrorUrl);
-                    }
+        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));
         }
+        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);
+    std::unordered_map<std::string, DownloadResult> downloadResults;
 
-            for (auto& r : results) {
-                if (!r.success) {
-                    log::error("download failed for {}: {}", r.name, r.error);
-                } else {
-                    downloadResults[r.name] = r;
+    // 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;
-        };
+    // 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"));
-            }
+    // 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::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;
+                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());
-            }
+        auto& executor = *execResult;
+        executor.set_log_level(std::string(log::level_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);
+        // 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;
                 }
-                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);
+                auto depRoot = depNode.storeRoot.empty()
+                    ? (dataDir / "xpkgs") : depNode.storeRoot;
+                auto depInstallDir = depRoot
+                    / detail_::effective_store_name_(depNode) / depNode.version;
 
-                    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;
+                // 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) {
-                        e.libdirs.push_back((depInstallDir / d).string());
+                        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.deps_exports[dep_spec] = std::move(e);
-                    break;
                 }
-            }
+                ctx.resolved_deps[dep_spec] = std::move(r);
 
-            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" });
+                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;
                 }
-                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;
+                mcpplibs::xpkg::DepExport e;
+                if (!depNode.exports.loader.empty()) {
+                    e.loader = (depInstallDir / depNode.exports.loader).string();
                 }
-            }
-            // 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());
+                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;
             }
+        }
 
-            // 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;
+        auto planKey = detail_::plan_key_(node);
+        auto dlIt = downloadResults.find(planKey);
 
-            // 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.
+        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" });
             }
-            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;
+            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, "" });
                 }
-            }
-            // 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);
+                // 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());
                     }
-                    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);
+                    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.
 
-            // 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;
+        // 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);
                 }
             }
+        }
 
-            // 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);
+        // 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;
                 }
-                if (!setEnvKeys.empty()) {
-                    platform::set_env_variable("PATH", newPath);
+                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);
+            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, "");
-                    }
+            // 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;
+            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) });
                 }
-            } 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;
+                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;
             }
-
-            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;
+        } 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 && !detail_::normalize_file_install_(ctx.install_dir)) {
-                log::error("failed to normalize file install layout for {}", node.name);
+        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 normalize file install layout");
+                    "failed to stage extracted payload");
                 if (onStatus) {
                     onStatus({ node.name, InstallPhase::Failed, 0.0f,
-                               "failed to normalize file install layout" });
+                               "failed to stage extracted payload" });
                 }
                 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);
+        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;
+        }
 
-            // 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';
-                    }
+        // 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},
+                    });
                 }
-
-                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()));
+                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';
                 }
             }
 
-            // 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 (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()));
             }
+        }
 
-            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;
+        // 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);
                 }
-            } 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;
+                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;
             }
-
-            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;
+        } 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;
             }
-
-            // 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));
+        } 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;
             }
+        }
 
-            // 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 (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;
             }
+        }
 
-            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);
+        // 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 (onStatus) {
-                onStatus({ node.name, InstallPhase::Done, 1.0f,
-                           payloadInstalled ? "already installed" : "" });
+            if (rep.floor) {
+                log::warn("[{}@{}] {}", node.name, node.version,
+                          closurecheck::describe_floor(*rep.floor));
             }
-            if (payloadInstalled) {
-                log::debug("{}@{} mapping to current subos", node.name, node.version);
-            } else {
-                log::debug("{}@{} installed successfully", node.name, node.version);
+            if (rep.nonTransitive) {
+                log::warn("[{}@{}] {}", node.name, node.version,
+                          closurecheck::describe_non_transitive(
+                              *rep.nonTransitive));
             }
         }
 
-        // 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()));
+        // 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);
         }
 
-        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)};
-        };
+        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);
+        }
 
-        auto [targetName, requestedVersion] = parse_target(name);
-        if (requestedVersion.empty()) {
-            requestedVersion = xvm::get_active_version(Config::effective_workspace(), targetName);
+        if (onStatus) {
+            onStatus({ node.name, InstallPhase::Done, 1.0f,
+                       payloadInstalled ? "already installed" : "" });
         }
-        std::string resolvedTarget;
-        if (requestedVersion.empty()) {
-            resolvedTarget = targetName;
+        if (payloadInstalled) {
+            log::debug("{}@{} mapping to current subos", node.name, node.version);
         } else {
-            auto [ns, bareVersion] = xvm::parse_ns_version(requestedVersion);
-            if (ns.empty()) {
-                resolvedTarget = targetName + "@" + bareVersion;
-            } else {
-                resolvedTarget = ns + ":" + targetName + "@" + bareVersion;
+            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()));
+    }
 
-        std::filesystem::path pkgFile;
-        std::filesystem::path installDir;
-        std::optional<PackageMatch> resolvedMatch;
+    return {};
+}
 
-        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);
+std::expected<Installer::UninstallOutcome, std::string> Installer::uninstall(const std::string& name) {
+    auto platform = detect_platform_();
+    auto currentWorkspacePath = detail_::current_workspace_config_path_();
 
-        // 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);
+    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 {
-            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,
-            };
-        }
+            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 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 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()));
+    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));
+    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 {
-            // 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);
-                }
+        } 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;
         }
+        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;
+    // 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, executingProvider)) {
+                         mf::providers_named(*doc, detachTarget)) {
                     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);
+            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());
+                }
             }
         }
+    }
 
-        bool detachedByBatch = false;
-        for (const auto& removed : removalResult->removed) {
-            if (removed.target == detachTarget
-                && removed.version == detachVersion) {
-                detachedByBatch = true;
-            }
+    for (const auto& op : xvm_ops) {
+        if (op.op == "remove_headers") {
+            xvm::remove_headers(op.includedir, sysroot_include);
         }
-        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());
+    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);
+    }
 
-        // 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());
-            }
-        }
+    Config::save_versions();
+    Config::save_workspace();
 
-        log::debug("{} uninstalled", resolvedTarget);
-        return UninstallOutcome{
-            .detachedOnly = false,
-            .target       = detachTarget,
-            .version      = detachVersion,
-        };
+    if (catalog_) {
+        catalog_->mark_installed(*resolvedMatch, false);
+    } else {
+        index_->mark_installed(name, false);
     }
-
-std::string Installer::detect_platform_(){
-        #if defined(__linux__)
-            return "linux";
-        #elif defined(__APPLE__)
-            return "macosx";
-        #elif defined(_WIN32)
-            return "windows";
-        #else
-            return "unknown";
-        #endif
+    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/inventory.cpp b/src/core/xim/inventory.cpp
index 04bac9de..1074d86e 100644
--- a/src/core/xim/inventory.cpp
+++ b/src/core/xim/inventory.cpp
@@ -612,111 +612,111 @@ std::vector<InstalledPackageRecord> collect_package_inventory(PackageCatalog& ca
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── 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();
-            }
+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 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 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 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),
-        };
-    }
+        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/libxpkg/types/type.cpp b/src/core/xim/libxpkg/types/type.cpp
index 5833e719..c8ad546d 100644
--- a/src/core/xim/libxpkg/types/type.cpp
+++ b/src/core/xim/libxpkg/types/type.cpp
@@ -3,17 +3,17 @@ module xlings.core.xim.libxpkg.types.type;
 import std;
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::xim {
 
-bool InstallPlan::has_errors() const{ return !errors.empty(); }
+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;
-    }
+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/xvm/bindings.cpp b/src/core/xvm/bindings.cpp
index 74d5266f..78dfc579 100644
--- a/src/core/xvm/bindings.cpp
+++ b/src/core/xvm/bindings.cpp
@@ -565,18 +565,18 @@ bool is_binding_root(const VersionDB& db,
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::xvm {
 
-BindingSelectionResolver::BindingSelectionResolver(const VersionDB& db): db_(db) {}
+BindingSelectionResolver::BindingSelectionResolver(const VersionDB& db) : db_(db) {}
 
-[[nodiscard]] std::size_t BindingSelectionResolver::legacy_incoming_index_builds() const{
-        return legacyIncomingIndexBuilds_;
-    }
+[[nodiscard]] std::size_t BindingSelectionResolver::legacy_incoming_index_builds() const {
+    return legacyIncomingIndexBuilds_;
+}
 
-[[nodiscard]] bool LibraryPlacement::empty() const{ return source.empty(); }
+[[nodiscard]] bool LibraryPlacement::empty() const { return source.empty(); }
 
-[[nodiscard]] bool FilePlacement::empty() const{ return source.empty(); }
+[[nodiscard]] bool FilePlacement::empty() const { return source.empty(); }
 
 } // namespace xlings::xvm
diff --git a/src/core/xvm/inspect.cpp b/src/core/xvm/inspect.cpp
index a0860933..14799d1d 100644
--- a/src/core/xvm/inspect.cpp
+++ b/src/core/xvm/inspect.cpp
@@ -615,22 +615,22 @@ std::size_t apply_dangling_edge_pruning(VersionDB& db,
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::xvm {
 
-[[nodiscard]] bool SubosMetadataRepair::empty() const{ return entries.empty(); }
+[[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]] 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 MetadataReset::empty() const { return entries.empty(); }
 
-[[nodiscard]] bool DanglingEdgePruning::empty() const{ return edges.empty(); }
+[[nodiscard]] bool DanglingEdgePruning::empty() const { return edges.empty(); }
 
 } // namespace xlings::xvm
diff --git a/src/core/xvm/lock.cpp b/src/core/xvm/lock.cpp
index 4ab03c91..8339c63a 100644
--- a/src/core/xvm/lock.cpp
+++ b/src/core/xvm/lock.cpp
@@ -66,45 +66,45 @@ std::expected<StateLock, std::string> acquire_state_lock(const std::filesystem::
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── 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(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_(); }
+StateLock::~StateLock() { clear_marker_(); }
 
-[[nodiscard]] bool StateLock::held() const{ return held_; }
+[[nodiscard]] bool StateLock::held() const { return held_; }
 
-[[nodiscard]] bool StateLock::bypassed() const{ return bypassed_; }
+[[nodiscard]] bool StateLock::bypassed() const { return bypassed_; }
 
-[[nodiscard]] bool StateLock::inherited() const{ return inherited_; }
+[[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;
-    }
+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/owner.cpp b/src/core/xvm/owner.cpp
index 6782cfd7..8aab3255 100644
--- a/src/core/xvm/owner.cpp
+++ b/src/core/xvm/owner.cpp
@@ -120,19 +120,19 @@ owner_candidates(const VersionDB& db,
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::xvm {
 
-[[nodiscard]] bool InstallCoordinate::empty() const{ return package.empty(); }
+[[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::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());
-    }
+[[nodiscard]] std::string InstallCoordinate::install_command() const {
+    return std::format("xlings install {}", canonical());
+}
 
 } // namespace xlings::xvm
diff --git a/src/interface.cpp b/src/interface.cpp
index 07553e87..74ec1bd7 100644
--- a/src/interface.cpp
+++ b/src/interface.cpp
@@ -199,105 +199,105 @@ int run(const mcpplibs::cmdline::ParsedArgs& args,
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── 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(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();
-    }
+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);
-    }
+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); }
+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);
+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();
         }
-        emit_raw_line_(line.dump());
+        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::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::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){
+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
+    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;
-        while (!st.stop_requested() && std::getline(std::cin, line)) {
-            handle_stdin_line_(line);
-        }
-#endif
+        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}});
-        }
+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/libs/sha256.cpp b/src/libs/sha256.cpp
index fa89697a..665b6bca 100644
--- a/src/libs/sha256.cpp
+++ b/src/libs/sha256.cpp
@@ -33,97 +33,97 @@ std::optional<std::string> hex_file(const std::filesystem::path& path) {
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::sha256 {
 
-Hasher::Hasher(){ reset(); }
+Hasher::Hasher() { reset(); }
 
-void Hasher::reset(){
-        h_ = {0x6a09e667u, 0xbb67ae85u, 0x3c6ef372u, 0xa54ff53au,
-              0x510e527fu, 0x9b05688cu, 0x1f83d9abu, 0x5be0cd19u};
-        buflen_ = 0;
-        total_  = 0;
-    }
+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;
-            }
+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::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));
-    }
+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;
+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/tinyhttps.cpp b/src/libs/tinyhttps.cpp
index eb0e39a8..4bb47076 100644
--- a/src/libs/tinyhttps.cpp
+++ b/src/libs/tinyhttps.cpp
@@ -337,35 +337,35 @@ std::int64_t query_content_length(const std::string& url, int connectTimeoutSec)
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::tinyhttps {
 
-StallDetector::StallDetector(int limitBytes, int windowSec): limit_(limitBytes), window_(windowSec) {}
+StallDetector::StallDetector(int limitBytes, int windowSec) : limit_(limitBytes), window_(windowSec) {}
 
-bool StallDetector::enabled() const{ return limit_ > 0 && window_ > 0; }
+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.
+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/platform/target.cpp b/src/platform/target.cpp
index 6073d77d..ea487e25 100644
--- a/src/platform/target.cpp
+++ b/src/platform/target.cpp
@@ -53,10 +53,10 @@ bool is_emulated() { return build().arch != host().arch; }
 }
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::platform {
 
-std::string Target::str() const{ return os + "-" + arch; }
+std::string Target::str() const { return os + "-" + arch; }
 
 } // namespace xlings::platform
diff --git a/src/platform/unix.cpp b/src/platform/unix.cpp
index 4f2b3127..9a0d9849 100644
--- a/src/platform/unix.cpp
+++ b/src/platform/unix.cpp
@@ -230,65 +230,65 @@ std::string home_for_user_(const std::string& name) {
 #endif // defined(__linux__) || defined(__APPLE__)
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── 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(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::operator=(FileLock&& other) noexcept {
+    if (this != &other) {
+        release();
+        fd_ = std::exchange(other.fd_, -1);
+    }
+    return *this;
+}
 
-FileLock::~FileLock(){ release(); }
+FileLock::~FileLock() { release(); }
 
 bool FileLock::acquire(const std::filesystem::path& path,
                      std::chrono::milliseconds timeout,
                      const std::function<bool()>& cancelled,
-                     std::string& error){
+                     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();
-            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;
+            return false;
         }
-
-void FileLock::release(){
-            if (fd_ < 0) return;
-            ::flock(fd_, LOCK_UN);
-            ::close(fd_);
-            fd_ = -1;
+        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
 
diff --git a/src/platform/windows.cpp b/src/platform/windows.cpp
index 0597b969..489c3752 100644
--- a/src/platform/windows.cpp
+++ b/src/platform/windows.cpp
@@ -344,63 +344,63 @@ bool atomic_swap_paths(const std::filesystem::path& a,
 #endif // defined(_WIN32)
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── 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(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::operator=(FileLock&& other) noexcept {
+    if (this != &other) {
+        release();
+        handle_ = std::exchange(other.handle_, INVALID_HANDLE_VALUE);
+    }
+    return *this;
+}
 
-FileLock::~FileLock(){ release(); }
+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});
-            }
+                     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;
         }
-
-void FileLock::release(){
-            if (handle_ == INVALID_HANDLE_VALUE) return;
-            ::CloseHandle(handle_);
-            handle_ = INVALID_HANDLE_VALUE;
+        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
 
diff --git a/src/runtime/cancellation.cpp b/src/runtime/cancellation.cpp
index 3f02b735..b93ac28f 100644
--- a/src/runtime/cancellation.cpp
+++ b/src/runtime/cancellation.cpp
@@ -3,49 +3,49 @@ module xlings.runtime.cancellation;
 import std;
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings {
 
-CancelledException::CancelledException(): std::runtime_error("operation cancelled") {}
+CancelledException::CancelledException() : std::runtime_error("operation cancelled") {}
 
-PausedException::PausedException(): std::runtime_error("operation paused") {}
+PausedException::PausedException() : std::runtime_error("operation paused") {}
 
-void CancellationToken::pause(){
-        state_.store(1, std::memory_order_release);
-        cv_.notify_all();
-    }
+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::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::cancel() {
+    state_.store(2, std::memory_order_release);
+    cv_.notify_all();
+}
 
-void CancellationToken::reset(){
-        state_.store(0, std::memory_order_release);
-    }
+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_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_paused() const {
+    return state_.load(std::memory_order_acquire) == 1;
+}
 
-bool CancellationToken::is_cancelled() const{
-        return state_.load(std::memory_order_acquire) == 2;
-    }
+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{};
-    }
+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/capability.cpp b/src/runtime/capability.cpp
index 53b51575..90fe84a3 100644
--- a/src/runtime/capability.cpp
+++ b/src/runtime/capability.cpp
@@ -6,31 +6,31 @@ import xlings.runtime.event_stream;
 import xlings.runtime.cancellation;
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── 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;
+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/event_stream.cpp b/src/runtime/event_stream.cpp
index f77e39d9..44b0fb0d 100644
--- a/src/runtime/event_stream.cpp
+++ b/src/runtime/event_stream.cpp
@@ -5,88 +5,88 @@ import xlings.runtime.event;
 import xlings.runtime.cancellation;
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── 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;
-            }
+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::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::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();
-    }
+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;
+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);
-            }
+    // 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);
-            });
-        }
+    emit(Event{std::move(req)});
 
-        auto response = std::move(promptResponses_[id]);
-        promptResponses_.erase(id);
-        return response;
-    }
+    std::unique_lock lock(promptMutex_);
 
-void EventStream::respond(std::string_view promptId, std::string_view response){
-        {
-            std::lock_guard lock(promptMutex_);
-            promptResponses_[std::string(promptId)] = std::string(response);
+    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 "";
         }
-        promptCv_.notify_all();
+    } else {
+        promptCv_.wait(lock, [&] {
+            return promptResponses_.contains(id);
+        });
     }
 
-void EventStream::cancel_all_prompts(){
+    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_.clear();
-        promptCv_.notify_all();
+        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/task.cpp b/src/runtime/task.cpp
index 48764a29..02a9179c 100644
--- a/src/runtime/task.cpp
+++ b/src/runtime/task.cpp
@@ -6,87 +6,103 @@ import xlings.runtime.event_stream;
 import xlings.runtime.capability;
 
 
-// ── out-of-line class members ─────────────────────────────────
+// ── out-of-line class members ──────────────────────────────────
 
 namespace xlings::task {
 
-auto TaskManager::generate_id_() -> TaskId{
-        return "task_" + std::to_string(nextId_.fetch_add(1));
-    }
+auto TaskManager::generate_id_() -> TaskId {
+    return "task_" + std::to_string(nextId_.fetch_add(1));
+}
 
-TaskManager::TaskManager(capability::Registry& registry): registry_ { registry } {}
+TaskManager::TaskManager(capability::Registry& registry) : registry_ { registry } {}
 
-TaskManager::~TaskManager(){
-        for (auto& [_, state] : tasks_) {
-            if (state->thread.joinable()) {
-                state->thread.join();
-            }
+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 TaskManager::submit(std::string_view capabilityName, capability::Params params) -> TaskId {
+    auto* cap = registry_.get(capabilityName);
+    if (!cap) return "";
 
-        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);
-            }
-        });
+    auto id = generate_id_();
+    auto state = std::make_shared<TaskState>();
+    state->id = id;
+    state->capabilityName = std::string(capabilityName);
+    state->status.store(TaskStatus::pending);
 
-        std::lock_guard lock(tasksMutex_);
-        tasks_[id] = std::move(state);
-        return id;
-    }
+    // 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
+            });
+        }
 
-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);
+        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;
+}
+
+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);
-        return TaskInfo {
+        result.push_back(TaskInfo {
             .id = s->id,
             .capabilityName = s->capabilityName,
             .status = s->status.load(),
@@ -94,66 +110,50 @@ auto TaskManager::info(TaskId id) -> TaskInfo{
             .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 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;
+    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 (sinceIndex >= s->eventBuffer.size()) return {};
-        return {s->eventBuffer.begin() + sinceIndex, s->eventBuffer.end()};
+        if (s->pendingPromptCount > 0) s->pendingPromptCount--;
     }
-
-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);
-            }
+    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

From 1b515c19294565f964aea4da095945f02c6eb9d4 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 09:58:34 +0800
Subject: [PATCH 06/19] test: the CLI parity guard has to scan implementation
 units too

`test_cli_spec_parity.py`'s reverse pass reads the hand-written argv loops
looking for flag literals the spec does not publish. It named
`src/core/subos.cppm`, `src/core/xself.cppm` and `src/cli.cppm` -- and those
loops now live in the implementation units, so the pass matched **0** literals
instead of 64.

The guard failed loudly rather than reporting green on an empty scan, which is
the reason this was caught at all. It now names the modules by stem and reads
both sides, since an interface unit and its implementation unit are one module
and an argv loop can sit in either.

Verified: 240 option spellings executed, 64 parser literals checked.

Two other layout dependencies on `.cppm` were audited and still hold, because
`VERSION` is `static constexpr` and stays in the interface:
tools/linux_release.sh's version sed, and test_version_consistency.py.
test_windows_header_hygiene.py already globbed both extensions and reports
10 modules including <windows.h> with NOMINMAX first -- the generated
implementation units inherit the global module fragment intact.
---
 tests/scripts/test_cli_spec_parity.py | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

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)

From 7de587d830d71dce04d2f07381b1dd5fdda9aaa2 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 10:03:27 +0800
Subject: [PATCH 07/19] fix(tools): a dropped declaration must not take its doc
 comment with it

Moving a module-private declaration out of the interface deleted the comment
above it -- 230 comment lines across the tree, explaining helpers whose bodies
are still there. Counting comment lines before and after is what found it; the
compiler had nothing to say.

The lead comment now follows whichever side keeps the declaration: the interface
when it is still referenced there, the implementation unit when it is not.

Phase 1 now conserves comments (10,290 -> 10,543). The surplus is the comment
above an #if, which is emitted to both units along with the directive -- both
units need to know why the guard is there, and an unexplained `#if defined(_WIN32)`
in the implementation unit would be worse than a duplicated sentence.

Also adds the report skeleton: method, fan-out, the two ICEs, and what this run
does not verify (1,228 lines behind _WIN32/__APPLE__ guards, the musl toolchain,
e2e). Measurements are appended once both sides have run.
---
 .../2026-08-13-module-impl-split-report.md    | 173 ++++++++++++++++++
 .agents/tools/module-split/split.py           |  29 ++-
 2 files changed, 193 insertions(+), 9 deletions(-)
 create mode 100644 .agents/docs/2026-08-13-module-impl-split-report.md

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..4e8235af
--- /dev/null
+++ b/.agents/docs/2026-08-13-module-impl-split-report.md
@@ -0,0 +1,173 @@
+# 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, no behaviour changed, no product code was written. 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.
+
+Three 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.
+
+### Interface surface
+
+| | lines | share of original |
+|---|---|---|
+| interface before | 46,253 | 100% |
+| interface after | **14,819** | **32%** |
+| implementation after | 35,112 | |
+
+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.
+
+- **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 it must show no improvement. If it does, the measurement is noise
+rather than an effect.
+
+Harness: `.agents/tools/module-split/{cold.sh,incr.py}`, driver
+`build/bench/run_compare.sh`.
+
+## 4. Measurements
+
+*(filled in below from the runs)*
+
+## 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.
+
+## 7. What this run does not verify
+
+- **1,228 lines of the moved code sit behind `_WIN32` / `__APPLE__` guards** that
+  a Linux build never compiles — `platform/windows.cpp` (330),
+  `platform/macos.cpp` (181), `subos/sandbox.cpp` (121) and others. The macOS
+  and Windows CI jobs are the gate for those, not this report.
+- The release (musl static, `gcc@15.1.0-musl`) toolchain is a second compiler
+  this branch has not been through locally.
+- Runtime behaviour beyond the unit suite: the e2e block needs a release tarball
+  and network access.
+
+## 8. 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.
diff --git a/.agents/tools/module-split/split.py b/.agents/tools/module-split/split.py
index 67cda16a..5583b6ee 100644
--- a/.agents/tools/module-split/split.py
+++ b/.agents/tools/module-split/split.py
@@ -391,12 +391,18 @@ def decl_from_def(h: str) -> str:
 class Cand:
     """A module-private entity whose declaration may or may not be needed in
     the interface."""
-    __slots__ = ('ns', 'decl', 'name', 'impl_with_defaults', 'impl_no_defaults')
+    __slots__ = ('ns', 'decl', 'name', 'lead',
+                 'impl_with_defaults', 'impl_no_defaults')
 
-    def __init__(self, ns, decl, name, 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
 
@@ -468,7 +474,7 @@ def process_level(items: list[Item], out: Split, indent: str, in_class=False,
                 out.impl.append(no_def)
             else:
                 cid = str(len(out.cands))
-                out.cands.append(Cand(ns, decl, declared_name(it.head),
+                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)
@@ -491,7 +497,8 @@ def process_level(items: list[Item], out: Split, indent: str, in_class=False,
                 out.impl.append(defn)
             else:
                 cid = str(len(out.cands))
-                out.cands.append(Cand(ns, ext, declared_name(bare), defn, defn))
+                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
@@ -538,11 +545,15 @@ def resolve_candidates(iface: str, impl: str, cands: list):
     iface = IFACE_RE.sub(
         lambda m: cands[int(m.group(1))].decl if int(m.group(1)) in keep else '',
         iface)
-    impl = IMPL_RE.sub(
-        lambda m: (cands[int(m.group(1))].impl_no_defaults
-                   if int(m.group(1)) in keep
-                   else cands[int(m.group(1))].impl_with_defaults),
-        impl)
+    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
 
 

From 76765fe35c9b7b2d67909e8031f07d0fb2cff26c Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 10:06:10 +0800
Subject: [PATCH 08/19] tools: an export-surface invariant check for the split

Nothing about moving implementations may add or remove an export. This compares
the exported-name set of every interface unit against the pre-split tree:
961 identifiers before, 961 after, 0 lost, 0 gained.

The check has to be depth-aware, and the first version was not. A line-anchored
regex over an `export namespace` body also matches the LOCAL VARIABLES inside
the function bodies that live there, so it reported 914 "lost exports" whose
names were `1`, `a`, `acc`, `activeBin` -- an artefact of the bodies moving, not
a lost export. It now scans with the splitter's own item scanner and counts only
top-level declarators.
---
 .agents/tools/module-split/export-surface.py | 87 ++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 .agents/tools/module-split/export-surface.py

diff --git a/.agents/tools/module-split/export-surface.py b/.agents/tools/module-split/export-surface.py
new file mode 100644
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])

From 3bd0e41346e3c8fa0d51720ba9812320146c6270 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 10:13:11 +0800
Subject: [PATCH 09/19] build: move the musl release target to gcc 16, and
 regenerate with comments preserved
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI found what a local dev build cannot: `x86_64-linux-musl` (gcc@15.1.0-musl)
rejected `catalog.cpp`, where a `std::views::transform` pipeline moved into a
module implementation unit --

    use of 'constexpr auto std::ranges::views::__adaptor::operator|(...)'
    before deduction of 'auto'

-- while gcc@16.1.0 accepts the identical body. Reproduced locally with
`mcpp build --target x86_64-linux-musl`: exactly one error, one file.

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 these two
versions, so the two targets now share one compiler major rather than trading one
breakage for the other. `x86_64-linux-musl` + gcc 16.1.0 is already an installed,
supported combination, and aarch64-linux-musl was on 16.1.0 already.

Verified: `mcpp build --target x86_64-linux-musl` clean in 32.29s, and the
static binary runs (`xlings 2026.8.11.2`, ELF statically linked).

This needed no source exclusion, so the toolchain-skip hook added while
diagnosing it is removed rather than left behind empty.

Also regenerates the tree so dropped declarations keep their doc comments:
comment lines 10,316 -> 10,612. The surplus is the comment above an `#if`, which
goes to both units with the directive.

My own local loop was the gap, not CI: several rounds cleared only
`target/*/gcm.cache` and kept the object files, so a stale catalog.o hid this on
the dev toolchain too. A cold `rm -rf target` and the second target both have to
be built before believing a green build.
---
 mcpp.toml                     |  12 ++-
 src/agent/agent.cpp           |   2 +
 src/cli.cpp                   |  35 ++++++++
 src/core/cmdprocessor.cpp     |   5 ++
 src/core/log.cpp              |   5 ++
 src/core/profile.cpp          |   8 ++
 src/core/subos.cpp            |  93 +++++++++++++++++++
 src/core/subos/sandbox.cpp    |  87 ++++++++++++++++++
 src/core/xim/extract.cpp      |   9 ++
 src/core/xim/indexfetch.cpp   |  21 +++++
 src/core/xself/doctor.cpp     | 163 ++++++++++++++++++++++++++++++++++
 src/core/xself/init.cpp       |  25 ++++++
 src/core/xself/install.cpp    |  29 ++++++
 src/core/xself/uninstall.cpp  |  12 +++
 src/core/xvm/inspect.cpp      |  21 +++++
 src/core/xvm/registration.cpp |  10 +++
 src/core/xvm/switch_plan.cpp  |   5 ++
 src/platform/unix.cpp         |   5 ++
 18 files changed, 546 insertions(+), 1 deletion(-)

diff --git a/mcpp.toml b/mcpp.toml
index de9ea8db..4820c9e2 100644
--- a/mcpp.toml
+++ b/mcpp.toml
@@ -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
index 3cfa3c5a..586e81e8 100644
--- a/src/agent/agent.cpp
+++ b/src/agent/agent.cpp
@@ -19,6 +19,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";
@@ -30,6 +31,7 @@ void print_overview(const SkillRegistry& reg) {
     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) {
diff --git a/src/cli.cpp b/src/cli.cpp
index d4ad4fc2..74227be5 100644
--- a/src/cli.cpp
+++ b/src/cli.cpp
@@ -34,6 +34,7 @@ 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()) {
@@ -263,6 +264,7 @@ void dispatch_data_event(const DataEvent& e) {
     }
 }
 
+// ─── 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") {
@@ -287,6 +289,8 @@ void handle_prompt(EventStream& stream, const PromptEvent& p) {
     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;
@@ -349,6 +353,7 @@ xvm::Workspace parse_legacy_config_(const std::filesystem::path& configFile) {
     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) {
@@ -360,6 +365,23 @@ void generate_xlings_json_(const std::filesystem::path& dir, const xvm::Workspac
     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();
@@ -393,6 +415,7 @@ bool parse_target_spec_(const mcpplibs::cmdline::ParsedArgs& args,
     return true;
 }
 
+// Install packages from project .xlings.json workspace
 int install_from_project_config_(EventStream& stream) {
     namespace fs = std::filesystem;
     std::error_code ec;
@@ -471,6 +494,7 @@ void apply_global_opts_(const mcpplibs::cmdline::ParsedArgs& args) {
     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
@@ -589,6 +613,17 @@ int cmd_config_(const mcpplibs::cmdline::ParsedArgs& args, EventStream& stream)
     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();
diff --git a/src/core/cmdprocessor.cpp b/src/core/cmdprocessor.cpp
index e0678042..94160338 100644
--- a/src/core/cmdprocessor.cpp
+++ b/src/core/cmdprocessor.cpp
@@ -12,6 +12,11 @@ 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;
 
diff --git a/src/core/log.cpp b/src/core/log.cpp
index 4444627b..30f2ab1c 100644
--- a/src/core/log.cpp
+++ b/src/core/log.cpp
@@ -60,6 +60,11 @@ 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(); }
diff --git a/src/core/profile.cpp b/src/core/profile.cpp
index 97ac6aff..5f39448d 100644
--- a/src/core/profile.cpp
+++ b/src/core/profile.cpp
@@ -35,6 +35,12 @@ int next_gen_number_(const fs::path& gensDir) {
     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;
@@ -210,6 +216,8 @@ bool save_subos_workspace(const fs::path& subosRoot,
     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";
diff --git a/src/core/subos.cpp b/src/core/subos.cpp
index 441dd934..93ec2781 100644
--- a/src/core/subos.cpp
+++ b/src/core/subos.cpp
@@ -296,6 +296,43 @@ void update_current_symlink_(EventStream& stream,
     }
 }
 
+// ─────────────────────────────────────────────────────────────────────
+// 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();
@@ -597,6 +634,9 @@ PkgRef parse_pkg_spec_(const std::string& spec) {
     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;
@@ -660,6 +700,8 @@ int copy_tree_(const fs::path& src, const fs::path& dst,
     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);
@@ -828,6 +870,10 @@ int new_from(const std::string& name, const fs::path& customDir,
     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;
 
@@ -858,6 +904,41 @@ int use_global(const std::string& name, EventStream& stream) {
     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;
@@ -1215,6 +1296,18 @@ int run_list_(EventStream& stream) {
     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);
diff --git a/src/core/subos/sandbox.cpp b/src/core/subos/sandbox.cpp
index 482923c2..c952310a 100644
--- a/src/core/subos/sandbox.cpp
+++ b/src/core/subos/sandbox.cpp
@@ -59,6 +59,11 @@ 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
@@ -89,6 +94,10 @@ std::string make_etc_group_(const std::string& user, gid_t gid) {
         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)
@@ -170,6 +179,9 @@ bool is_mounted_(const fs::path& path) {
     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);
@@ -200,6 +212,30 @@ int unmount_image_(const fs::path& mountpoint) {
     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;
@@ -352,6 +388,9 @@ sandbox_binds_(const fs::path& subos_dir,
     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,
@@ -387,6 +426,17 @@ build_proot_argv_(const fs::path& proot_bin,
     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;
@@ -407,6 +457,10 @@ locate_bwrap_(const fs::path& home_dir) {
         "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())
@@ -415,6 +469,10 @@ probe_bwrap_(const fs::path& bwrap_bin) {
     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")
@@ -453,6 +511,11 @@ std::string classify_bwrap_probe_error_(const std::string& output,
     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,
@@ -512,6 +575,9 @@ build_bwrap_argv_(const fs::path& bwrap_bin,
     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;
@@ -542,6 +608,27 @@ detect_backend_(const fs::path& home_dir,
     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;
diff --git a/src/core/xim/extract.cpp b/src/core/xim/extract.cpp
index a47c1031..28f124b4 100644
--- a/src/core/xim/extract.cpp
+++ b/src/core/xim/extract.cpp
@@ -68,10 +68,19 @@ std::string libarchive_error_(struct archive* a) {
     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;
diff --git a/src/core/xim/indexfetch.cpp b/src/core/xim/indexfetch.cpp
index 6138cfd7..edc6c167 100644
--- a/src/core/xim/indexfetch.cpp
+++ b/src/core/xim/indexfetch.cpp
@@ -15,6 +15,7 @@ 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";
@@ -30,6 +31,13 @@ std::string lower_hex_(std::string s) {
     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) {
@@ -82,6 +90,11 @@ BaseOverride resolve_base_() {
     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) {
@@ -107,6 +120,9 @@ std::string obtain_file(const std::string& filename, std::vector<std::string> re
     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; }
@@ -422,6 +438,11 @@ std::vector<std::string> index_pointer_urls(std::string_view filename,
     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_();
diff --git a/src/core/xself/doctor.cpp b/src/core/xself/doctor.cpp
index df16ead9..72a14254 100644
--- a/src/core/xself/doctor.cpp
+++ b/src/core/xself/doctor.cpp
@@ -88,6 +88,16 @@ DoctorState load_state_() {
     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;
@@ -113,6 +123,16 @@ bool payload_has_any_executable_(const fs::path& dir) {
     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(' ');
@@ -132,6 +152,18 @@ fs::path audit_payload_dir_(const xim::PackageMatch& match) {
         / 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,
@@ -143,6 +175,27 @@ owning_coordinate_(const xvm::VersionDB& db,
     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) {
@@ -188,6 +241,16 @@ std::string activation_conflict_(const DoctorState& st,
     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,
@@ -471,6 +534,27 @@ std::vector<Finding> detect_subos_manifest_(const xvm::VersionDB& db,
     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();
@@ -1739,6 +1823,8 @@ Scan detect_(const DoctorState& st, const CoordinateProbe& probe,
     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();
@@ -1902,6 +1988,13 @@ void repair_local_(const DoctorState& st, const Scan& scan,
     }
 }
 
+// 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));
@@ -2052,6 +2145,13 @@ void repair_state_(RepairReport& out) {
     }
 }
 
+// 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);
@@ -2101,6 +2201,16 @@ void repair_other_subos_(const DoctorState& st, RepairReport& out) {
     }
 }
 
+// ── 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,
@@ -2191,6 +2301,25 @@ void repair_payloads_(const DoctorState& st, const Scan& scan,
     }
 }
 
+// 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) {
@@ -2229,6 +2358,19 @@ void repair_inactive_(const Scan& scan, const std::string& client,
     }
 }
 
+// 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 = {}) {
@@ -2275,6 +2417,27 @@ void repair_incomplete_(const Scan& scan, const CommandRunner& run,
     }
 }
 
+// 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;
diff --git a/src/core/xself/init.cpp b/src/core/xself/init.cpp
index a9e4387c..576dcb77 100644
--- a/src/core/xself/init.cpp
+++ b/src/core/xself/init.cpp
@@ -132,6 +132,9 @@ void write_if_missing_(const fs::path& path, std::string_view content) {
     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";
@@ -163,6 +166,10 @@ void ensure_subos_manifest_(const fs::path& subos_dir) {
     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);
@@ -182,6 +189,18 @@ std::string extract_profile_version_(std::string_view text) {
     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) {
@@ -203,6 +222,12 @@ void write_or_upgrade_profile_(const fs::path& path,
     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();
diff --git a/src/core/xself/install.cpp b/src/core/xself/install.cpp
index cae29161..b17d1dee 100644
--- a/src/core/xself/install.cpp
+++ b/src/core/xself/install.cpp
@@ -142,6 +142,8 @@ void configure_install_mirror_(const fs::path& targetHome,
     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
@@ -440,6 +442,10 @@ void setup_shell_profiles(const fs::path& homeDir) {
 #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
@@ -456,6 +462,16 @@ void warn_root_context_() {
     }
 }
 
+// `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 {};
@@ -468,6 +484,19 @@ fs::path explicit_home_() {
     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;
diff --git a/src/core/xself/uninstall.cpp b/src/core/xself/uninstall.cpp
index 51869bc6..9c28c6eb 100644
--- a/src/core/xself/uninstall.cpp
+++ b/src/core/xself/uninstall.cpp
@@ -8,6 +8,7 @@ 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;
@@ -34,6 +35,8 @@ std::string format_bytes_(std::uintmax_t bytes) {
     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);
@@ -69,6 +72,8 @@ bool home_dir_safe_to_remove_(const fs::path& home) {
     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
@@ -84,6 +89,9 @@ fs::path chdir_to_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
@@ -151,6 +159,10 @@ bool prompt_yes_no_(const std::string& question) {
     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"
diff --git a/src/core/xvm/inspect.cpp b/src/core/xvm/inspect.cpp
index 14799d1d..8ee9908e 100644
--- a/src/core/xvm/inspect.cpp
+++ b/src/core/xvm/inspect.cpp
@@ -8,6 +8,11 @@ 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) {
@@ -25,6 +30,22 @@ bool release_declares_file_assets_(const VersionDB& db,
     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,
diff --git a/src/core/xvm/registration.cpp b/src/core/xvm/registration.cpp
index 71670e2d..8f8a7172 100644
--- a/src/core/xvm/registration.cpp
+++ b/src/core/xvm/registration.cpp
@@ -42,6 +42,8 @@ RegistrationGroupIdentity registration_group_identity_(
     };
 }
 
+// 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) {
@@ -107,6 +109,13 @@ std::string registration_path_token_(std::string_view token) {
     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, '\\', '/');
@@ -114,6 +123,7 @@ std::string normalized_payload_path_(std::string_view path) {
     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;
diff --git a/src/core/xvm/switch_plan.cpp b/src/core/xvm/switch_plan.cpp
index 963a945c..ca4be19b 100644
--- a/src/core/xvm/switch_plan.cpp
+++ b/src/core/xvm/switch_plan.cpp
@@ -7,6 +7,11 @@ 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) {
diff --git a/src/platform/unix.cpp b/src/platform/unix.cpp
index 9a0d9849..35248b59 100644
--- a/src/platform/unix.cpp
+++ b/src/platform/unix.cpp
@@ -80,6 +80,11 @@ std::string read_terminal_query_reply(int fd,
         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")) {

From c94e1997ba858f692c8ad56cb79d5c56fa4b6964 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 10:24:50 +0800
Subject: [PATCH 10/19] fix: a module whose interface keeps a template keeps
 its declarations too

macOS CI failed on the phase-2 push having passed on the phase-1 one. Every TU
instantiating a zero-argument `log::` template died inside libc++'s <print>:

    formatter<basic_format_string<char, basic_string<char>>, char>
      -- call to deleted constructor

which is `std::print` no longer seeing its `FILE*` overload and treating
`stdout` as the format string. Traced to log.cppm:66 via
`log::info<>` at migrate.cpp:19 and `log::println<>` at uninstall.cpp:134.
The build stops on first failure, so two objects is a floor, not the scope.

The only delta to log.cppm in phase 2 was the module-private declaration rule
dropping three declarations -- `gFile_`, `gColor_`, `color_on_()`. A template
left in the interface is instantiated in the IMPORTER, and what that
instantiation can see depends on the interface's reachability set, which
dropping declarations changes in ways the standard leaves to the implementation.

So the rule now skips any module whose interface still holds a template. Six
files, none of them a build-time bottleneck: interface 14,819 -> 14,832 lines.

Honest about the evidence: I could not reproduce this locally. A minimal probe
with the same shape -- GMF <cstdio>, a template calling stream-less std::print,
zero-arg instantiation from another module's implementation unit -- compiles
clean under clang 20.1.7 on Linux, and the error trace runs through Xcode's
_stdio.h, so it needs macOS libc. CI is the only loop, and CI is what verifies
this.

Locally verified: cold gcc@16.1.0 build clean (24.21s), musl gcc@16.1.0 clean
(24.22s).
---
 .agents/tools/module-split/split.py | 21 +++++++++++++++++++++
 src/core/i18n.cppm                  |  2 ++
 src/core/log.cpp                    |  5 -----
 src/core/log.cppm                   | 11 +++++++++++
 4 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/.agents/tools/module-split/split.py b/.agents/tools/module-split/split.py
index 5583b6ee..fda16673 100644
--- a/.agents/tools/module-split/split.py
+++ b/.agents/tools/module-split/split.py
@@ -520,6 +520,12 @@ def declared_name(decl: str) -> str:
     return region[hits[-1].start():hits[-1].end()] if hits else ''
 
 
+def interface_has_template(iface: str) -> bool:
+    """Does anything left in the interface get instantiated in an importer?"""
+    return re.search(r'^[ \t]*(?:export\s+)?template\s*<', scrub(iface), re.M) \
+        is not None
+
+
 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
@@ -532,6 +538,21 @@ def resolve_candidates(iface: str, impl: str, cands: list):
     on IFACE_MARK."""
     if not cands:
         return IFACE_RE.sub('', iface), IMPL_RE.sub('', impl)
+    # A template left in the interface is instantiated in the IMPORTER, and what
+    # that instantiation can see depends on the interface's reachability set --
+    # which dropping declarations changes, in ways the standard leaves to the
+    # implementation.  clang 20 on macOS reads it differently from gcc 16 on
+    # Linux: after log.cppm lost three module-private declarations, every TU
+    # instantiating a zero-argument `log::` template failed inside libc++'s
+    # <print>, having stopped seeing the FILE* overload (xlings-ci-macos run
+    # 31660163438).  Neither gcc 16 nor clang 20 on Linux reproduces it, so this
+    # is conservative rather than clever: a module whose interface still holds a
+    # template keeps all of its declarations.  Six files, none of them a
+    # build-time bottleneck.
+    if interface_has_template(iface):
+        return (IFACE_RE.sub(lambda m: cands[int(m.group(1))].decl, iface),
+                IMPL_RE.sub(lambda m: cands[int(m.group(1))].impl_no_defaults,
+                            impl))
     # what the interface still says with every candidate declaration removed
     residue = IFACE_RE.sub('', iface)
     keep = set()
diff --git a/src/core/i18n.cppm b/src/core/i18n.cppm
index ab6828cb..678d380a 100644
--- a/src/core/i18n.cppm
+++ b/src/core/i18n.cppm
@@ -165,6 +165,8 @@ constexpr MsgEntry gMessages_[] = {
 static_assert(sizeof(gMessages_) / sizeof(gMessages_[0]) == MSG_COUNT,
               "gMessages_ size must match Msg enum count");
 
+extern std::string gLang_;
+
 export void set_language(const std::string& lang);
 
 export [[nodiscard]] const std::string& language();
diff --git a/src/core/log.cpp b/src/core/log.cpp
index 30f2ab1c..4444627b 100644
--- a/src/core/log.cpp
+++ b/src/core/log.cpp
@@ -60,11 +60,6 @@ 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(); }
diff --git a/src/core/log.cppm b/src/core/log.cppm
index a87af0c8..704460d1 100644
--- a/src/core/log.cppm
+++ b/src/core/log.cppm
@@ -19,6 +19,8 @@ export enum class Level {
 
 extern Level gLevel_;
 extern std::string gContext_;
+extern std::ofstream gFile_;
+extern bool gColor_;
 // Terminal output is suppressed when platform::is_tui_mode() is true
 
 export void set_level(Level level);
@@ -36,6 +38,13 @@ export void set_context(std::string ctx);
 export void clear_context();
 
 export void enable_color(bool 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_();
 bool color_on_err_();
 
 std::string colored_(palette::Rgb c, const char* text);
@@ -43,6 +52,8 @@ 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);
 
+std::string timestamp_();
+
 void write_to_file_(std::string_view prefix, std::string_view msg);
 
 export template<typename... Args>

From 4b44fe33e694be956e4bae77c1fd88712dc9108f Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 10:33:25 +0800
Subject: [PATCH 11/19] fix: an in-class body holding a stream-less std::print
 is the instantiation anchor

The previous fix was wrong. Restoring log.cppm's dropped declarations changed
nothing: macOS failed again on c94e199 with the identical error in the identical
two objects, so that hypothesis is disproved and its guard is reverted rather
than left in the tree unjustified.

The real anchor is `Config::print_paths()`, whose body carries seven
`std::println("...")` calls -- the overload that takes no stream. libc++
implements it as `print(stdout, fmt, args...)`, so the FILE* overload has to be
visible; when it is not, `stdout` is deduced AS the format string and you get a
deleted `formatter<basic_format_string<...>>`.

An in-class body is implicitly inline, so it IS in the BMI, and it can be the
only thing instantiating `std::print`/`std::println` for every importer of the
module. Outlining it moved that instantiation point out of the interface, and
clang 20 on macOS then stopped finding the FILE* overload in `migrate.cpp` and
`uninstall.cpp` -- both of which import `xlings.core.config`, both otherwise
untouched since the push macOS passed.

This is the same shape as the two gcc ICEs already recorded: moving a body moves
where a template is first instantiated, and the failure surfaces somewhere else
entirely, naming nothing that changed.

Phase 1 correctly does NOT carry this rule, and the asymmetry is the reason it
passed macOS while phase 2 did not: a non-inline namespace-scope body need not be
in the BMI at all, so it was never anchoring anything.

Cost: 3 members stay inline, interface 14,832 -> 14,853 lines.

Verified locally: cold gcc@16.1.0 clean (26.11s), musl gcc@16.1.0 clean, export
surface still 961 identifiers, 0 lost 0 gained. macOS remains CI-only.
---
 .agents/tools/module-split/outline.py | 23 +++++++++++++++++++++
 .agents/tools/module-split/split.py   | 21 -------------------
 src/core/cmdprocessor.cpp             | 27 -------------------------
 src/core/cmdprocessor.cppm            | 29 ++++++++++++++++++++++++---
 src/core/config.cpp                   | 13 ------------
 src/core/config.cppm                  | 13 +++++++++++-
 src/core/i18n.cppm                    |  2 --
 src/core/log.cpp                      |  5 +++++
 src/core/log.cppm                     | 11 ----------
 9 files changed, 66 insertions(+), 78 deletions(-)

diff --git a/.agents/tools/module-split/outline.py b/.agents/tools/module-split/outline.py
index 2f6e126c..35dd89b5 100644
--- a/.agents/tools/module-split/outline.py
+++ b/.agents/tools/module-split/outline.py
@@ -229,6 +229,28 @@ def indent_of(lead: str, head: str) -> int:
     return len(m.group(0).expandtabs(4))
 
 
+# `std::print("...")` / `std::println("...")` -- the overload that takes no
+# stream.  libc++ implements it by calling `print(stdout, fmt, args...)`, so the
+# FILE* overload has to be visible; when it is not, `stdout` is deduced AS the
+# format string and the error is a deleted `formatter<basic_format_string<...>>`.
+STREAMLESS_PRINT = re.compile(r'std::print(?:ln)?\s*\(\s*(?!stderr\b|stdout\b)')
+
+
+def anchors_streamless_print(body: str) -> bool:
+    """An in-class body is implicitly inline, so it IS in the BMI, and it can be
+    the only thing that instantiates `std::print`/`std::println` for every
+    importer of the module.  Move it out and that instantiation point moves with
+    it -- after which clang 20 on macOS stops finding the FILE* overload in TUs
+    that were compiling before and are otherwise untouched
+    (`Config::print_paths()` took `migrate.cpp` and `uninstall.cpp` down this
+    way; xlings-ci-macos runs 31660163438 and 31660753235).
+
+    Phase 1 is not subject to this and does not carry the rule: a non-inline
+    namespace-scope body need not be in the BMI at all, so it was never anchoring
+    anything -- which is why phase 1 passed macOS and phase 2 did not."""
+    return STREAMLESS_PRINT.search(scrub(body)) is not None
+
+
 def member_name(decl: str) -> str:
     """The declarator-id of a member function head."""
     m = mask_operator(scrub(decl))
@@ -279,6 +301,7 @@ def outline_class(cls_item: Item, ns: str, outer: str, out_impl: list,
                 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 not anchors_streamless_print(it.body)
                 and (LIMIT[0] is None or stats['members'] < LIMIT[0])
             )
             if movable:
diff --git a/.agents/tools/module-split/split.py b/.agents/tools/module-split/split.py
index fda16673..5583b6ee 100644
--- a/.agents/tools/module-split/split.py
+++ b/.agents/tools/module-split/split.py
@@ -520,12 +520,6 @@ def declared_name(decl: str) -> str:
     return region[hits[-1].start():hits[-1].end()] if hits else ''
 
 
-def interface_has_template(iface: str) -> bool:
-    """Does anything left in the interface get instantiated in an importer?"""
-    return re.search(r'^[ \t]*(?:export\s+)?template\s*<', scrub(iface), re.M) \
-        is not None
-
-
 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
@@ -538,21 +532,6 @@ def resolve_candidates(iface: str, impl: str, cands: list):
     on IFACE_MARK."""
     if not cands:
         return IFACE_RE.sub('', iface), IMPL_RE.sub('', impl)
-    # A template left in the interface is instantiated in the IMPORTER, and what
-    # that instantiation can see depends on the interface's reachability set --
-    # which dropping declarations changes, in ways the standard leaves to the
-    # implementation.  clang 20 on macOS reads it differently from gcc 16 on
-    # Linux: after log.cppm lost three module-private declarations, every TU
-    # instantiating a zero-argument `log::` template failed inside libc++'s
-    # <print>, having stopped seeing the FILE* overload (xlings-ci-macos run
-    # 31660163438).  Neither gcc 16 nor clang 20 on Linux reproduces it, so this
-    # is conservative rather than clever: a module whose interface still holds a
-    # template keeps all of its declarations.  Six files, none of them a
-    # build-time bottleneck.
-    if interface_has_template(iface):
-        return (IFACE_RE.sub(lambda m: cands[int(m.group(1))].decl, iface),
-                IMPL_RE.sub(lambda m: cands[int(m.group(1))].impl_no_defaults,
-                            impl))
     # what the interface still says with every candidate declaration removed
     residue = IFACE_RE.sub('', iface)
     keep = set()
diff --git a/src/core/cmdprocessor.cpp b/src/core/cmdprocessor.cpp
index 94160338..2e4d882a 100644
--- a/src/core/cmdprocessor.cpp
+++ b/src/core/cmdprocessor.cpp
@@ -308,31 +308,4 @@ CommandProcessor& CommandProcessor::add(std::string name, std::string descriptio
     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("Use 'xlings help' for usage information");
-    return 1;
-}
-
-int CommandProcessor::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;
-}
-
 } // namespace xlings::cmdprocessor
diff --git a/src/core/cmdprocessor.cppm b/src/core/cmdprocessor.cppm
index beb4ea7c..5f389104 100644
--- a/src/core/cmdprocessor.cppm
+++ b/src/core/cmdprocessor.cppm
@@ -26,9 +26,32 @@ public:
                           std::function<int(int argc, char* argv[])> func,
                           std::string usage = "");
 
-    int run(int argc, char* argv[]);
-
-    int print_help() const;
+    int 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("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;
+    }
 
 private:
     std::vector<CommandInfo> commands_;
diff --git a/src/core/config.cpp b/src/core/config.cpp
index 473372f3..9ec2d340 100644
--- a/src/core/config.cpp
+++ b/src/core/config.cpp
@@ -1210,17 +1210,4 @@ void Config::save_workspace() {
     platform::write_string_to_file(subosConfigPath.string(), json.dump(2));
 }
 
-void Config::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));
-}
-
 } // namespace xlings
diff --git a/src/core/config.cppm b/src/core/config.cppm
index aa1729bc..ebdcfc30 100644
--- a/src/core/config.cppm
+++ b/src/core/config.cppm
@@ -446,7 +446,18 @@ public:
     // Save current subos workspace (project-local if project config exists)
     static void save_workspace();
 
-    static void print_paths();
+    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));
+    }
 };
 
 } // namespace xlings
diff --git a/src/core/i18n.cppm b/src/core/i18n.cppm
index 678d380a..ab6828cb 100644
--- a/src/core/i18n.cppm
+++ b/src/core/i18n.cppm
@@ -165,8 +165,6 @@ constexpr MsgEntry gMessages_[] = {
 static_assert(sizeof(gMessages_) / sizeof(gMessages_[0]) == MSG_COUNT,
               "gMessages_ size must match Msg enum count");
 
-extern std::string gLang_;
-
 export void set_language(const std::string& lang);
 
 export [[nodiscard]] const std::string& language();
diff --git a/src/core/log.cpp b/src/core/log.cpp
index 4444627b..30f2ab1c 100644
--- a/src/core/log.cpp
+++ b/src/core/log.cpp
@@ -60,6 +60,11 @@ 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(); }
diff --git a/src/core/log.cppm b/src/core/log.cppm
index 704460d1..a87af0c8 100644
--- a/src/core/log.cppm
+++ b/src/core/log.cppm
@@ -19,8 +19,6 @@ export enum class Level {
 
 extern Level gLevel_;
 extern std::string gContext_;
-extern std::ofstream gFile_;
-extern bool gColor_;
 // Terminal output is suppressed when platform::is_tui_mode() is true
 
 export void set_level(Level level);
@@ -38,13 +36,6 @@ export void set_context(std::string ctx);
 export void clear_context();
 
 export void enable_color(bool 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_();
 bool color_on_err_();
 
 std::string colored_(palette::Rgb c, const char* text);
@@ -52,8 +43,6 @@ 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);
 
-std::string timestamp_();
-
 void write_to_file_(std::string_view prefix, std::string_view msg);
 
 export template<typename... Args>

From d88d223ce953104e40329be5df4d9bebbcd30792 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 10:50:41 +0800
Subject: [PATCH 12/19] fix: name the stream in interface templates, and give
 implementation units <cstdio>

Root cause, found with a local clang loop instead of 13-minute CI cycles: the
fragile construct is the STREAM-LESS `std::print` / `std::println` overload inside
a template that stays in the interface.

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 in an interface that point is in the IMPORTER. Once enough
bodies leave the interface, clang 20 stops picking it: `stdout` is deduced AS the
format string and the error is a deleted `formatter<basic_format_string<...>>`,
reported against files that did not change (migrate.cpp, uninstall.cpp).

Two mechanical rules replace the two guesses that came before, both of which are
reverted:
- 23 call sites across 6 interfaces name their stream. [print.fun] defines the
  two-argument form AS `print(stdout, ...)`, so this changes no behaviour and
  removes the deduction entirely. Bodies that move to an implementation unit are
  left alone -- nothing instantiates those from another TU.
- an implementation unit whose text ends up naming `stdout`/`stderr`/`FILE` gets
  `<cstdio>` in its global module fragment. `Config::print_paths()` lands in
  config.cpp, whose interface has no fragment at all.

With those, no member needs an exclusion for this: the print-anchor rule and the
template-reachability guard are both gone, and the 3 members the anchor rule had
pinned are outlined again (interface back to 14,819 lines).

**The local loop is the real lesson.** clang 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. A minimal probe of the same shape does NOT
reproduce it; it needs the whole project. `build/bench/clang_variant.sh` builds
any variant with clang in an isolated copy, and `clang_bisect.sh` binary-searches
a file's members.

One of my own bugs is worth recording: `open(f,'w').write(ensure_cstdio(open(f).read()))`
truncates the file before the read runs, so every unit taking that path came out
empty -- surfacing as undefined symbols at link time, never as an error in the
file that was emptied.

Verified: gcc@16.1.0 clean, musl gcc@16.1.0 clean, clang@20.1.7 clean, export
surface 961 identifiers with 0 lost and 0 gained.
---
 .agents/tools/module-split/outline.py | 32 +++++------------
 .agents/tools/module-split/split.py   | 51 +++++++++++++++++++++++++--
 src/cli.cpp                           |  2 ++
 src/core/cmdprocessor.cpp             | 30 ++++++++++++++++
 src/core/cmdprocessor.cppm            | 29 ++-------------
 src/core/config.cpp                   | 16 +++++++++
 src/core/config.cppm                  | 13 +------
 src/core/log.cppm                     | 16 ++++-----
 src/platform/linux.cppm               |  2 +-
 src/platform/macos.cppm               |  2 +-
 src/platform/windows.cppm             |  2 +-
 11 files changed, 120 insertions(+), 75 deletions(-)

diff --git a/.agents/tools/module-split/outline.py b/.agents/tools/module-split/outline.py
index 35dd89b5..f18b08f4 100644
--- a/.agents/tools/module-split/outline.py
+++ b/.agents/tools/module-split/outline.py
@@ -28,7 +28,7 @@ class scope — but the RETURN TYPE comes before it and is not, so a return
 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,
-                   CONSTEXPR, TYPE_HEAD, NS_HEAD)
+                   ensure_cstdio, CONSTEXPR, TYPE_HEAD, NS_HEAD)
 
 CLASS_HEAD = re.compile(
     r'^\s*(?:export\s+)?(?P<kw>struct|class)\s+(?P<name>\w+)'
@@ -229,28 +229,6 @@ def indent_of(lead: str, head: str) -> int:
     return len(m.group(0).expandtabs(4))
 
 
-# `std::print("...")` / `std::println("...")` -- the overload that takes no
-# stream.  libc++ implements it by calling `print(stdout, fmt, args...)`, so the
-# FILE* overload has to be visible; when it is not, `stdout` is deduced AS the
-# format string and the error is a deleted `formatter<basic_format_string<...>>`.
-STREAMLESS_PRINT = re.compile(r'std::print(?:ln)?\s*\(\s*(?!stderr\b|stdout\b)')
-
-
-def anchors_streamless_print(body: str) -> bool:
-    """An in-class body is implicitly inline, so it IS in the BMI, and it can be
-    the only thing that instantiates `std::print`/`std::println` for every
-    importer of the module.  Move it out and that instantiation point moves with
-    it -- after which clang 20 on macOS stops finding the FILE* overload in TUs
-    that were compiling before and are otherwise untouched
-    (`Config::print_paths()` took `migrate.cpp` and `uninstall.cpp` down this
-    way; xlings-ci-macos runs 31660163438 and 31660753235).
-
-    Phase 1 is not subject to this and does not carry the rule: a non-inline
-    namespace-scope body need not be in the BMI at all, so it was never anchoring
-    anything -- which is why phase 1 passed macOS and phase 2 did not."""
-    return STREAMLESS_PRINT.search(scrub(body)) is not None
-
-
 def member_name(decl: str) -> str:
     """The declarator-id of a member function head."""
     m = mask_operator(scrub(decl))
@@ -301,7 +279,6 @@ def outline_class(cls_item: Item, ns: str, outer: str, out_impl: list,
                 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 not anchors_streamless_print(it.body)
                 and (LIMIT[0] is None or stats['members'] < LIMIT[0])
             )
             if movable:
@@ -422,6 +399,13 @@ def process(path: str, write: bool):
         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
 
 
diff --git a/.agents/tools/module-split/split.py b/.agents/tools/module-split/split.py
index 5583b6ee..fa4359b2 100644
--- a/.agents/tools/module-split/split.py
+++ b/.agents/tools/module-split/split.py
@@ -565,6 +565,53 @@ def impl_for(m):
 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)
@@ -611,8 +658,8 @@ def split_file(path: str, qualify_partition_import=False):
     # 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 (iface, impl.rstrip() + '\n', out.moved, out.moved_lines,
-            mod + part), None
+    return (name_the_stream(iface), ensure_cstdio(impl.rstrip() + '\n'),
+            out.moved, out.moved_lines, mod + part), None
 
 
 def main():
diff --git a/src/cli.cpp b/src/cli.cpp
index 74227be5..fc62fcd4 100644
--- a/src/cli.cpp
+++ b/src/cli.cpp
@@ -3,6 +3,8 @@ module;
 #include "ftxui/component/event.hpp"
 #include "ftxui/component/mouse.hpp"
 
+#include <cstdio>
+
 module xlings.cli;
 
 import std;
diff --git a/src/core/cmdprocessor.cpp b/src/core/cmdprocessor.cpp
index 2e4d882a..1cd20cb4 100644
--- a/src/core/cmdprocessor.cpp
+++ b/src/core/cmdprocessor.cpp
@@ -1,3 +1,6 @@
+module;
+#include <cstdio>
+
 module xlings.core.cmdprocessor;
 
 import std;
@@ -308,4 +311,31 @@ CommandProcessor& CommandProcessor::add(std::string name, std::string descriptio
     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 5f389104..beb4ea7c 100644
--- a/src/core/cmdprocessor.cppm
+++ b/src/core/cmdprocessor.cppm
@@ -26,32 +26,9 @@ public:
                           std::function<int(int argc, char* argv[])> func,
                           std::string usage = "");
 
-    int 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("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 run(int argc, char* argv[]);
+
+    int print_help() const;
 
 private:
     std::vector<CommandInfo> commands_;
diff --git a/src/core/config.cpp b/src/core/config.cpp
index 9ec2d340..c0d95ed5 100644
--- a/src/core/config.cpp
+++ b/src/core/config.cpp
@@ -1,3 +1,6 @@
+module;
+#include <cstdio>
+
 module xlings.core.config;
 
 import std;
@@ -1210,4 +1213,17 @@ void Config::save_workspace() {
     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 ebdcfc30..aa1729bc 100644
--- a/src/core/config.cppm
+++ b/src/core/config.cppm
@@ -446,18 +446,7 @@ public:
     // Save current subos workspace (project-local if project config exists)
     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/log.cppm b/src/core/log.cppm
index a87af0c8..e6cecded 100644
--- a/src/core/log.cppm
+++ b/src/core/log.cppm
@@ -50,9 +50,9 @@ 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);
     }
@@ -63,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);
     }
@@ -104,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);
     }
 }
@@ -113,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/platform/linux.cppm b/src/platform/linux.cppm
index 4672d350..18179897 100644
--- a/src/platform/linux.cppm
+++ b/src/platform/linux.cppm
@@ -72,7 +72,7 @@ namespace platform_impl {
     }
 
     export inline void println(const std::string& msg) {
-        std::println("{}", msg);
+        std::println(stdout, "{}", msg);
     }
 
     export int get_pid();
diff --git a/src/platform/macos.cppm b/src/platform/macos.cppm
index 5bc65cc7..0207b44e 100644
--- a/src/platform/macos.cppm
+++ b/src/platform/macos.cppm
@@ -74,7 +74,7 @@ namespace platform_impl {
     }
 
     export inline void println(const std::string& msg) {
-        std::println("{}", msg);
+        std::println(stdout, "{}", msg);
     }
 
     export int get_pid();
diff --git a/src/platform/windows.cppm b/src/platform/windows.cppm
index 70b103c3..029b2f2c 100644
--- a/src/platform/windows.cppm
+++ b/src/platform/windows.cppm
@@ -93,7 +93,7 @@ namespace platform_impl {
     }
 
     export inline void println(const std::string& msg) {
-        std::println("{}", msg);
+        std::println(stdout, "{}", msg);
     }
 
     export int get_pid();

From 40b42e95f8682f06de635c1d7a1606028f80bacd Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 10:57:58 +0800
Subject: [PATCH 13/19] docs+tools: the split report, and drop a dead parameter
 from classify()

`classify()` took an `in_class` argument it never read, and its docstring listed
five return values when there are six. Removed and spelled out; regenerating
afterwards reproduces the committed tree byte for byte, which is the check that
the cleanup changed no behaviour -- and incidentally that regen.sh is
deterministic.

The report carries method before numbers: how each measurement is taken and why
(a plain `touch` of a .cppm does not work -- mcpp preserves a BMI's timestamp
when a recompile is byte-identical, so it would skip every downstream unit and
flatter the before-picture), the probe set spanning both fan-out and the two
kinds of body, and `compare_segment` as a control that must NOT improve.

It also corrects a number from the previous commit message: the stream naming is
11 sites across 4 interfaces, not 23 across 6. The 23 was the count of
stream-less prints in the pre-split .cppm set, and 12 of those belong to bodies
that moved to a .cpp and were never normalised.

Section 8 records what each of the four toolchains rejected, including the two
wrong fixes and why they are reverted rather than left in, and section 9 is the
gate this work should have started with: a cold `rm -rf target`, the musl target,
and clang -- all runnable locally in under a minute each.
---
 .../2026-08-13-module-impl-split-report.md    | 153 ++++++++++++++++--
 .agents/tools/module-split/split.py           |  15 +-
 2 files changed, 155 insertions(+), 13 deletions(-)

diff --git a/.agents/docs/2026-08-13-module-impl-split-report.md b/.agents/docs/2026-08-13-module-impl-split-report.md
index 4e8235af..4d60e96f 100644
--- a/.agents/docs/2026-08-13-module-impl-split-report.md
+++ b/.agents/docs/2026-08-13-module-impl-split-report.md
@@ -37,7 +37,12 @@ Three things left the interface:
 |---|---|---|
 | interface before | 46,253 | 100% |
 | interface after | **14,819** | **32%** |
-| implementation after | 35,112 | |
+| 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.
@@ -102,7 +107,7 @@ refs, so it must show no improvement. If it does, the measurement is noise
 rather than an effect.
 
 Harness: `.agents/tools/module-split/{cold.sh,incr.py}`, driver
-`build/bench/run_compare.sh`.
+`build/bench/measure_side.sh`.
 
 ## 4. Measurements
 
@@ -151,18 +156,148 @@ 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.
 
-## 7. What this run does not verify
+## 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. `build/bench/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 build/bench/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
 
 - **1,228 lines of the moved code sit behind `_WIN32` / `__APPLE__` guards** that
   a Linux build never compiles — `platform/windows.cpp` (330),
-  `platform/macos.cpp` (181), `subos/sandbox.cpp` (121) and others. The macOS
-  and Windows CI jobs are the gate for those, not this report.
-- The release (musl static, `gcc@15.1.0-musl`) toolchain is a second compiler
-  this branch has not been through locally.
+  `platform/macos.cpp` (181), `subos/sandbox.cpp` (121) and others. The macOS and
+  Windows CI jobs are the gate; Windows and aarch64 are green, macOS is what the
+  latest push tests.
 - Runtime behaviour beyond the unit suite: the e2e block needs a release tarball
-  and network access.
+  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.
 
-## 8. An mcpp observation
+## 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
diff --git a/.agents/tools/module-split/split.py b/.agents/tools/module-split/split.py
index fa4359b2..d1d6c6a4 100644
--- a/.agents/tools/module-split/split.py
+++ b/.agents/tools/module-split/split.py
@@ -275,8 +275,15 @@ def is_qualified_definition(h: str) -> bool:
     return '::' in decl.split()[-1] if decl.split() else False
 
 
-def classify(it: Item, in_class: bool) -> str:
-    """Return 'stay' | 'namespace' | 'both' | 'split-fn' | 'split-var'."""
+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':
@@ -431,10 +438,10 @@ 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, in_class=False,
+def process_level(items: list[Item], out: Split, indent: str,
                   ns: str = '', exported: bool = False):
     for it in items:
-        cls = classify(it, in_class)
+        cls = classify(it)
         if cls == 'both':
             out.iface.append(it.lead + it.head)
             out.impl.append(it.lead + it.head)

From 4c254fdd1b20dadd92eef99ab25070f5f46ad3e9 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 11:58:50 +0800
Subject: [PATCH 14/19] refactor: move the imports the bodies took with them,
 and fix three tool defects review found

Self-review of the PR, and it found real things.

**The split copied imports instead of moving them.** split.py duplicates the
interface's import list into the implementation unit -- correct for the
implementation, wrong for the interface, which was left importing modules only
the moved bodies used. 153 of 554 interface import edges (28%) named nothing in
the interface, and each one makes the interface's BMI depend on a module it does
not use, so an edit there recompiles this interface for nothing. That caps the
benefit the split exists to deliver. trim-imports.py is phase 3 and runs last,
because deciding this needs every interface in its final form. Interface
14,819 -> 14,666 lines.

It took one compiler-driven iteration. An aggregator module declares nothing and
only `export import`s -- `xlings.runtime` re-exports event/event_stream/
capability -- so its export set read as empty and its importers were over-trimmed:
`interface.cppm` lost `Event`, `EventStream` and `CancellationToken`. The export
sets are now closed over re-exports, partitions included.

**cold.sh has never run from where it was committed.** Its root was
`dirname/../..`, which was right in build/bench and points at `.agents/` from
`.agents/tools/module-split/`. Broken since the first commit of this branch, and
the report cites it.

**The report cited two scripts that are not in the repo.** `clang_variant.sh` and
`measure_side.sh` lived in build/, which is gitignored, so the local gate the
report documents could not be run. Both are now committed as
`clang-variant.sh` / `measure-side.sh` with their paths corrected; logs still go
to build/. The tools are 755 like the rest of .agents/tools.

**The unverified surface was overstated by 69%.** "1,228 lines behind
_WIN32/__APPLE__ guards" is really 728: the old counter flagged any block whose
condition mentioned those macros, including `#if !defined(_WIN32)`, which is true
on Linux -- 208 of the miscount was platform/unix.cpp's POSIX code. Recomputed by
evaluating the conditions.

**And a correction to the report's own reasoning.** It claimed the control probe
"must show no improvement". It improves 2.5x, because the downstream interfaces it
still rebuilds are smaller. The control separates rebuild-cost from rebuild-set;
the moved probes get both and land at 4.6-12.1x. The gap is what the move bought.

Verified after the trim: gcc@16.1.0 clean, musl gcc@16.1.0 clean, llvm@20.1.7
clean, export surface still 961 identifiers with 0 lost and 0 gained, and 1,262
function definitions conserved exactly. Unit suite re-running.
---
 .../2026-08-13-module-impl-split-report.md    | 132 +++++++++++--
 .agents/tools/module-split/analyze.py         |   0
 .agents/tools/module-split/bisect-member.sh   |   0
 .agents/tools/module-split/clang-bisect.sh    |  24 +++
 .agents/tools/module-split/clang-variant.sh   |  42 ++++
 .agents/tools/module-split/cold.sh            |   3 +-
 .agents/tools/module-split/export-surface.py  |   0
 .agents/tools/module-split/incr.py            |   0
 .agents/tools/module-split/measure-side.sh    |  68 +++++++
 .agents/tools/module-split/outline.py         |   0
 .agents/tools/module-split/regen.sh           |   3 +
 .agents/tools/module-split/split.py           |   0
 .agents/tools/module-split/trim-imports.py    | 184 ++++++++++++++++++
 src/agent/text_renderer.cppm                  |   1 -
 src/capabilities.cppm                         |  11 --
 src/cli.cppm                                  |  17 --
 src/core/closure_check.cppm                   |   1 -
 src/core/cmdprocessor.cppm                    |   3 -
 src/core/common.cppm                          |   2 -
 src/core/compact/xself.cppm                   |   1 -
 src/core/config.cppm                          |   3 -
 src/core/entry_binary.cppm                    |   3 -
 src/core/home_config.cppm                     |   1 -
 src/core/i18n.cppm                            |   1 -
 src/core/mirror/adaptive.cppm                 |   1 -
 src/core/mirror/expand.cppm                   |   3 -
 src/core/mirror/registry.cppm                 |   3 -
 src/core/profile.cppm                         |   4 -
 src/core/subos.cppm                           |   2 -
 src/core/subos/keeper.cppm                    |   1 -
 src/core/subos/manifest.cppm                  |   1 -
 src/core/subos/sandbox.cppm                   |   4 -
 src/core/xim/commands.cppm                    |   9 -
 src/core/xim/downloader.cppm                  |   4 -
 src/core/xim/index.cppm                       |   3 -
 src/core/xim/index_cmd.cppm                   |   3 -
 src/core/xim/indexfetch.cppm                  |   4 -
 src/core/xim/installer.cppm                   |   2 -
 src/core/xim/inventory.cppm                   |   2 -
 src/core/xim/libxpkg/types/script.cppm        |   2 -
 src/core/xim/libxpkg/types/subos.cppm         |   3 -
 src/core/xim/payload.cppm                     |   1 -
 src/core/xim/repo.cppm                        |   4 -
 src/core/xim/resolver.cppm                    |   2 -
 src/core/xself.cppm                           |   2 -
 src/core/xself/clean.cppm                     |   3 -
 src/core/xself/config.cppm                    |   2 -
 src/core/xself/doctor.cppm                    |   4 -
 src/core/xself/init.cppm                      |   3 -
 src/core/xself/install.cppm                   |   8 -
 src/core/xself/migrate.cppm                   |   5 -
 src/core/xself/repair.cppm                    |   2 -
 src/core/xself/uninstall.cppm                 |   2 -
 src/core/xself/update.cppm                    |   2 -
 src/core/xvm/commands.cppm                    |   5 -
 src/core/xvm/lock.cppm                        |   2 -
 src/core/xvm/removal.cppm                     |   1 -
 src/core/xvm/shim.cppm                        |   3 -
 src/interface.cppm                            |   2 -
 src/runtime/capability.cppm                   |   1 -
 src/ui/layout.cppm                            |   1 -
 src/ui/progress.cppm                          |   1 -
 src/ui/selector.cppm                          |   1 -
 src/ui/theme.cppm                             |   1 -
 64 files changed, 443 insertions(+), 166 deletions(-)
 mode change 100644 => 100755 .agents/tools/module-split/analyze.py
 mode change 100644 => 100755 .agents/tools/module-split/bisect-member.sh
 create mode 100755 .agents/tools/module-split/clang-bisect.sh
 create mode 100755 .agents/tools/module-split/clang-variant.sh
 mode change 100644 => 100755 .agents/tools/module-split/cold.sh
 mode change 100644 => 100755 .agents/tools/module-split/export-surface.py
 mode change 100644 => 100755 .agents/tools/module-split/incr.py
 create mode 100755 .agents/tools/module-split/measure-side.sh
 mode change 100644 => 100755 .agents/tools/module-split/outline.py
 mode change 100644 => 100755 .agents/tools/module-split/regen.sh
 mode change 100644 => 100755 .agents/tools/module-split/split.py
 create mode 100755 .agents/tools/module-split/trim-imports.py

diff --git a/.agents/docs/2026-08-13-module-impl-split-report.md b/.agents/docs/2026-08-13-module-impl-split-report.md
index 4d60e96f..3f68d122 100644
--- a/.agents/docs/2026-08-13-module-impl-split-report.md
+++ b/.agents/docs/2026-08-13-module-impl-split-report.md
@@ -71,6 +71,11 @@ 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
@@ -103,15 +108,109 @@ the split only helped the second kind, the first kind's numbers would say so.
 | `compare_segment` | `xlings.core.semver` | 23 | **control** — `inline`, unmoved |
 
 `compare_segment` is the control: it stays `inline` in `semver.cppm` on **both**
-refs, so it must show no improvement. If it does, the measurement is noise
-rather than an effect.
+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
-`build/bench/measure_side.sh`.
+`.agents/tools/module-split/measure-side.sh`.
 
 ## 4. Measurements
 
-*(filled in below from the runs)*
+### Cold build — every project TU recompiled
+
+| ref | runs (s) | median |
+|---|---|---|
+| `main` @ b1563fe | 67.17 / 55.27 / 56.40 | **56.40** |
+| this branch | 36.97 / 27.28 / 26.85 | **27.28** |
+
+**2.07× 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× |
+
+**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
+2.5× is the interfaces downstream simply being smaller to recompile; the gap
+between 2.5× and 12× is what moving the body out actually bought.
+
+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` — where the split LOSES
+
+| ref | wall clock | result |
+|---|---|---|
+| `main` | **953.81s** | 38 passed, 0 failed |
+| this branch | 1104.83s (**1.16× slower**) | 38 passed, 0 failed |
+
+This is the one measurement that goes the wrong way, and the mechanism is not a
+guess. Per test binary:
+
+| ref | min | median | max | sum over 38 |
+|---|---|---|---|---|
+| `main` | 20.86s | 21.18s | 41.16s | 832.5s |
+| this branch | 23.96s | 24.92s | 45.53s | 1011.7s |
+
+**+4.72s per binary, and 38 × 4.72 = +179s is the entire gap.** The overhead is
+near-constant across binaries regardless of the test file's own size — min +3.10,
+median +3.74, max +4.37. A compile-side cost would scale with the file being
+compiled; a link-side cost would not. Each test binary now links roughly 202
+object files instead of 112.
+
+So: **the split trades link time for compile time.** Compilation gets much
+faster; linking gets slower, and `mcpp test` is link-dominated because it links
+39 large static binaries. A workflow that links once (`mcpp build`) wins 2×; a
+workflow that links 39 times loses 16%.
+
+The obvious follow-up is on the test harness rather than the split: 38 binaries
+each statically linking the whole project is what makes link cost dominate, and
+one binary (or a shared library) would remove it. That is out of scope here.
+
+The branch figure carries a ~27s pessimism: `src/` was regenerated part-way
+through that run, forcing a module rebuild the main-side run did not pay. It
+biases against the branch, so the 1.16× is if anything slightly overstated.
 
 ## 5. Two gcc@16.1.0 internal compiler errors
 
@@ -156,6 +255,10 @@ 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
@@ -257,8 +360,8 @@ reproduces the macOS failure exactly — main builds clean, the split does not 
 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. `build/bench/clang_variant.sh` builds any variant with clang
-in an isolated copy; `clang_bisect.sh` binary-searches one file's members.
+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
 
@@ -275,7 +378,7 @@ 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 build/bench/clang_variant.sh check --all      # llvm@20.1.7  (macOS family)
+bash .agents/tools/module-split/clang-variant.sh check --all      # llvm@20.1.7  (macOS family)
 python3 .agents/tools/module-split/export-surface.py
 ```
 
@@ -286,11 +389,16 @@ Windows (`llvm@20.1.7`, MSVC-flavoured) and real macOS remain CI-only.
 
 ## 10. What this report does not verify
 
-- **1,228 lines of the moved code sit behind `_WIN32` / `__APPLE__` guards** that
-  a Linux build never compiles — `platform/windows.cpp` (330),
-  `platform/macos.cpp` (181), `subos/sandbox.cpp` (121) and others. The macOS and
-  Windows CI jobs are the gate; Windows and aarch64 are green, macOS is what the
-  latest push tests.
+- **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
diff --git a/.agents/tools/module-split/analyze.py b/.agents/tools/module-split/analyze.py
old mode 100644
new mode 100755
diff --git a/.agents/tools/module-split/bisect-member.sh b/.agents/tools/module-split/bisect-member.sh
old mode 100644
new mode 100755
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
old mode 100644
new mode 100755
index d4f9a11d..e7de98ee
--- a/.agents/tools/module-split/cold.sh
+++ b/.agents/tools/module-split/cold.sh
@@ -5,10 +5,11 @@
 # 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)"
+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
diff --git a/.agents/tools/module-split/export-surface.py b/.agents/tools/module-split/export-surface.py
old mode 100644
new mode 100755
diff --git a/.agents/tools/module-split/incr.py b/.agents/tools/module-split/incr.py
old mode 100644
new mode 100755
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
old mode 100644
new mode 100755
diff --git a/.agents/tools/module-split/regen.sh b/.agents/tools/module-split/regen.sh
old mode 100644
new mode 100755
index 68aea8b3..3fef7bee
--- a/.agents/tools/module-split/regen.sh
+++ b/.agents/tools/module-split/regen.sh
@@ -29,6 +29,9 @@ 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))
diff --git a/.agents/tools/module-split/split.py b/.agents/tools/module-split/split.py
old mode 100644
new mode 100755
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/src/agent/text_renderer.cppm b/src/agent/text_renderer.cppm
index 0b2f941b..3234d186 100644
--- a/src/agent/text_renderer.cppm
+++ b/src/agent/text_renderer.cppm
@@ -8,7 +8,6 @@ export module xlings.agent.text_renderer;
 
 import std;
 
-import xlings.libs.json;
 import xlings.runtime.event;
 
 namespace xlings::agent {
diff --git a/src/capabilities.cppm b/src/capabilities.cppm
index ed184934..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 {
 
diff --git a/src/cli.cppm b/src/cli.cppm
index 4e04317b..3ec33d6a 100644
--- a/src/cli.cppm
+++ b/src/cli.cppm
@@ -10,28 +10,11 @@ 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;
 
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.cppm b/src/core/cmdprocessor.cppm
index beb4ea7c..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;
diff --git a/src/core/common.cppm b/src/core/common.cppm
index 1567c979..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 {
 
diff --git a/src/core/compact/xself.cppm b/src/core/compact/xself.cppm
index 42192745..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;
 
diff --git a/src/core/config.cppm b/src/core/config.cppm
index aa1729bc..e6896edf 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;
diff --git a/src/core/entry_binary.cppm b/src/core/entry_binary.cppm
index 95514877..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 {
 
diff --git a/src/core/home_config.cppm b/src/core/home_config.cppm
index f7623092..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`.
diff --git a/src/core/i18n.cppm b/src/core/i18n.cppm
index ab6828cb..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 {
 
diff --git a/src/core/mirror/adaptive.cppm b/src/core/mirror/adaptive.cppm
index 9f5f872d..9f3ba52e 100644
--- a/src/core/mirror/adaptive.cppm
+++ b/src/core/mirror/adaptive.cppm
@@ -24,7 +24,6 @@ export module xlings.core.mirror.adaptive;
 
 import std;
 
-import xlings.core.log;
 import xlings.libs.tinyhttps;
 
 namespace xlings::mirror::adaptive { // anonymous namespace
diff --git a/src/core/mirror/expand.cppm b/src/core/mirror/expand.cppm
index 8df43bc2..4261415b 100644
--- a/src/core/mirror/expand.cppm
+++ b/src/core/mirror/expand.cppm
@@ -10,9 +10,6 @@ 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;
diff --git a/src/core/mirror/registry.cppm b/src/core/mirror/registry.cppm
index 34ac2ac2..72bf84b8 100644
--- a/src/core/mirror/registry.cppm
+++ b/src/core/mirror/registry.cppm
@@ -13,9 +13,6 @@ 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 {
diff --git a/src/core/profile.cppm b/src/core/profile.cppm
index c3034904..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;
 
diff --git a/src/core/subos.cppm b/src/core/subos.cppm
index 51b0e8e9..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;
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.cppm b/src/core/subos/manifest.cppm
index 772335bb..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`.
 //
diff --git a/src/core/subos/sandbox.cppm b/src/core/subos/sandbox.cppm
index 2d4da1f3..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
 
diff --git a/src/core/xim/commands.cppm b/src/core/xim/commands.cppm
index 4ff8e92b..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.
diff --git a/src/core/xim/downloader.cppm b/src/core/xim/downloader.cppm
index c2e6633c..2a3396e8 100644
--- a/src/core/xim/downloader.cppm
+++ b/src/core/xim/downloader.cppm
@@ -7,14 +7,10 @@ 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;
 
diff --git a/src/core/xim/index.cppm b/src/core/xim/index.cppm
index c1c8957b..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;
diff --git a/src/core/xim/index_cmd.cppm b/src/core/xim/index_cmd.cppm
index d9517107..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.
diff --git a/src/core/xim/indexfetch.cppm b/src/core/xim/indexfetch.cppm
index 3da722ee..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 {
 
diff --git a/src/core/xim/installer.cppm b/src/core/xim/installer.cppm
index 00bce070..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;
diff --git a/src/core/xim/inventory.cppm b/src/core/xim/inventory.cppm
index 4cc48991..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.
 //
diff --git a/src/core/xim/libxpkg/types/script.cppm b/src/core/xim/libxpkg/types/script.cppm
index 9c5ebaa8..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;
diff --git a/src/core/xim/libxpkg/types/subos.cppm b/src/core/xim/libxpkg/types/subos.cppm
index 40bd9760..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.
diff --git a/src/core/xim/payload.cppm b/src/core/xim/payload.cppm
index 9ac32e51..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 {
diff --git a/src/core/xim/repo.cppm b/src/core/xim/repo.cppm
index 1f6616a2..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;
diff --git a/src/core/xim/resolver.cppm b/src/core/xim/resolver.cppm
index a172ebf2..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 {
diff --git a/src/core/xself.cppm b/src/core/xself.cppm
index 5e315f59..eeeaca6f 100644
--- a/src/core/xself.cppm
+++ b/src/core/xself.cppm
@@ -37,12 +37,10 @@ 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 {
 
diff --git a/src/core/xself/clean.cppm b/src/core/xself/clean.cppm
index f281d444..566a7a39 100644
--- a/src/core/xself/clean.cppm
+++ b/src/core/xself/clean.cppm
@@ -2,9 +2,6 @@ export module xlings.core.xself.clean;
 
 import std;
 
-import xlings.core.config;
-import xlings.core.log;
-import xlings.core.profile;
 
 namespace xlings::xself {
 
diff --git a/src/core/xself/config.cppm b/src/core/xself/config.cppm
index 8f5d8ea9..08e2e6f3 100644
--- a/src/core/xself/config.cppm
+++ b/src/core/xself/config.cppm
@@ -2,8 +2,6 @@ export module xlings.core.xself.config;
 
 import std;
 
-import xlings.core.config;
-import xlings.libs.json;
 import xlings.runtime;
 
 namespace xlings::xself {
diff --git a/src/core/xself/doctor.cppm b/src/core/xself/doctor.cppm
index 93d42265..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;
diff --git a/src/core/xself/init.cppm b/src/core/xself/init.cppm
index 9cc47031..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;
diff --git a/src/core/xself/install.cppm b/src/core/xself/install.cppm
index 23c8e39b..c7cbc1d8 100644
--- a/src/core/xself/install.cppm
+++ b/src/core/xself/install.cppm
@@ -4,14 +4,6 @@ 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 {
 
diff --git a/src/core/xself/migrate.cppm b/src/core/xself/migrate.cppm
index 1fab2f6e..cdec280f 100644
--- a/src/core/xself/migrate.cppm
+++ b/src/core/xself/migrate.cppm
@@ -2,11 +2,6 @@ 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 {
 
diff --git a/src/core/xself/repair.cppm b/src/core/xself/repair.cppm
index c30f02cc..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`.
 //
diff --git a/src/core/xself/uninstall.cppm b/src/core/xself/uninstall.cppm
index 7fde1fd3..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]`
 //
diff --git a/src/core/xself/update.cppm b/src/core/xself/update.cppm
index 9296fb3e..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 {
 
diff --git a/src/core/xvm/commands.cppm b/src/core/xvm/commands.cppm
index 99923021..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;
diff --git a/src/core/xvm/lock.cppm b/src/core/xvm/lock.cppm
index db245019..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.
 //
diff --git a/src/core/xvm/removal.cppm b/src/core/xvm/removal.cppm
index fb3262a9..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;
diff --git a/src/core/xvm/shim.cppm b/src/core/xvm/shim.cppm
index 9d3fa14f..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;
 
diff --git a/src/interface.cppm b/src/interface.cppm
index b607dfac..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 {
diff --git a/src/runtime/capability.cppm b/src/runtime/capability.cppm
index 0bb57a2d..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;
 
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.cppm b/src/ui/progress.cppm
index a2dfae22..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;
 
diff --git a/src/ui/selector.cppm b/src/ui/selector.cppm
index 0f61f009..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;
 
diff --git a/src/ui/theme.cppm b/src/ui/theme.cppm
index a1a58f5f..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;
 

From 95ca3ae6aac19442800d9404c0698f51b85b7937 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 12:01:23 +0800
Subject: [PATCH 15/19] docs: the measurements, including the one where the
 split loses
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`main`'s baseline is in, so the report carries numbers instead of intentions.

Cold build 56.40s -> 27.28s, a 2.07x median-to-median win, and the direction was
not a given: translation units roughly doubled. One implementation edit goes
4.6-12.1x depending on fan-out, and on main such an edit cost about as much as
building the whole project from scratch -- 54-63s against a 56.40s cold build,
because before the split every body edit WAS an interface edit.

**`mcpp test` is 1.16x SLOWER**, 953.81s -> 1104.83s, and that is the honest
headline the rest of the report has to be read against. The mechanism is pinned,
not guessed: +4.72s per test binary, 38 x 4.72 = the entire 179s gap, and the
overhead is near-constant regardless of the test file's own size (min +3.10,
median +3.74, max +4.37). A compile-side cost would scale with the file; a
link-side cost would not. Each test binary now links ~202 objects instead of ~112.

So the split trades link time for compile time. Link once and you win 2x; link 39
large static binaries and you lose 16%. The follow-up belongs to the test harness
-- 38 binaries each statically linking the whole project -- not to the split.

Also records what the self-review found (§12), all of which built green first:
the copied imports, cold.sh never running from its committed path, two cited
scripts that were not in the repo, the 69% overstatement of the unverified
surface, the backwards control-probe claim, and a closure bug in the new tool.
Plus the five invariants it checked and found clean, as numbers.

Binary size +0.10% at -O0, which is the measured answer to the inline trade-off
rather than an assumption about it.
---
 .../2026-08-13-module-impl-split-report.md    | 36 +++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/.agents/docs/2026-08-13-module-impl-split-report.md b/.agents/docs/2026-08-13-module-impl-split-report.md
index 3f68d122..da9a549b 100644
--- a/.agents/docs/2026-08-13-module-impl-split-report.md
+++ b/.agents/docs/2026-08-13-module-impl-split-report.md
@@ -20,7 +20,7 @@ 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.
 
-Three things left the interface:
+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
@@ -30,13 +30,19 @@ Three things left the interface:
    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 | **14,819** | **32%** |
+| interface after phases 1–3 | **14,666** | **32%** |
 | implementation after | 35,655 | |
 
 110 interface units, 92 implementation units (90 generated + `main.cpp` +
@@ -414,3 +420,29 @@ p4.m.gcm`), verified on a throwaway project — but its check pass does not expa
 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×, 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 |

From 29d1902ff04451251534d52cf59f8de7ebda5f97 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 12:16:53 +0800
Subject: [PATCH 16/19] docs: the trim reverses the test regression, and
 falsifies my explanation for it

Re-measured on the final tree. `mcpp test` was the one number going the wrong
way -- 1.16x slower than main -- and phase 3 turns it into 1.03x FASTER:
953.81s on main, 1104.83s before the trim, 921.73s after.

Per test binary: main median 21.18s, branch 24.92s before the trim (+3.74s), and
21.07s after (-0.11s). The penalty did not shrink, it disappeared.

**And that falsifies what I wrote about the cause.** I called it link cost: the
overhead was near-constant per binary regardless of the test file's size, and each
binary now links ~202 objects instead of ~112. That argument does not separate the
two candidates, because BMI loading is ALSO near-constant per TU -- it depends on
the import closure, not on the file being compiled.

Phase 3 is the controlled experiment. It changes only interface import edges; the
object count each binary links is identical before and after. Had linking been the
cause the penalty would have survived. So the cause was every test TU loading BMIs
for modules nothing in the interfaces named -- 28% more edges than needed. The
split does not meaningfully trade link time for compile time; it was carrying a
defect that looked exactly like that trade.

Everything else improved with it too: cold build median 27.28s -> 26.09s (2.16x
against main), `parse_sudo_env` 4.46/4.60 -> 4.39/4.35 (12.4x), and the control
17.24/17.54 -> 15.31/15.24, which is the same effect one level down -- the
downstream interfaces it still rebuilds now carry smaller closures.

All six CI workflows green on the trim commit.
---
 .../2026-08-13-module-impl-split-report.md    | 109 +++++++++++-------
 1 file changed, 70 insertions(+), 39 deletions(-)

diff --git a/.agents/docs/2026-08-13-module-impl-split-report.md b/.agents/docs/2026-08-13-module-impl-split-report.md
index da9a549b..d9c0c008 100644
--- a/.agents/docs/2026-08-13-module-impl-split-report.md
+++ b/.agents/docs/2026-08-13-module-impl-split-report.md
@@ -14,11 +14,32 @@ implementation. Each is now a standard-conforming pair:
 | interface unit | `X.cppm` | `export module M;` | yes |
 | implementation unit | `X.cpp` | `module M;` | **no** |
 
-No directories moved, no behaviour changed, no product code was written. 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.
+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:
 
@@ -136,9 +157,10 @@ Harness: `.agents/tools/module-split/{cold.sh,incr.py}`, driver
 | ref | runs (s) | median |
 |---|---|---|
 | `main` @ b1563fe | 67.17 / 55.27 / 56.40 | **56.40** |
-| this branch | 36.97 / 27.28 / 26.85 | **27.28** |
+| 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.07× faster**, and the direction was not a given: translation units roughly
+**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
@@ -171,6 +193,12 @@ the mean, so one outlier would move it silently.
 | `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,
@@ -184,39 +212,42 @@ 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` — where the split LOSES
-
-| ref | wall clock | result |
-|---|---|---|
-| `main` | **953.81s** | 38 passed, 0 failed |
-| this branch | 1104.83s (**1.16× slower**) | 38 passed, 0 failed |
-
-This is the one measurement that goes the wrong way, and the mechanism is not a
-guess. Per test binary:
+### `mcpp test` — and the finding that changed the conclusion
 
-| ref | min | median | max | sum over 38 |
-|---|---|---|---|---|
-| `main` | 20.86s | 21.18s | 41.16s | 832.5s |
-| this branch | 23.96s | 24.92s | 45.53s | 1011.7s |
-
-**+4.72s per binary, and 38 × 4.72 = +179s is the entire gap.** The overhead is
-near-constant across binaries regardless of the test file's own size — min +3.10,
-median +3.74, max +4.37. A compile-side cost would scale with the file being
-compiled; a link-side cost would not. Each test binary now links roughly 202
-object files instead of 112.
-
-So: **the split trades link time for compile time.** Compilation gets much
-faster; linking gets slower, and `mcpp test` is link-dominated because it links
-39 large static binaries. A workflow that links once (`mcpp build`) wins 2×; a
-workflow that links 39 times loses 16%.
-
-The obvious follow-up is on the test harness rather than the split: 38 binaries
-each statically linking the whole project is what makes link cost dominate, and
-one binary (or a shared library) would remove it. That is out of scope here.
-
-The branch figure carries a ~27s pessimism: `src/` was regenerated part-way
-through that run, forcing a module rebuild the main-side run did not pay. It
-biases against the branch, so the 1.16× is if anything slightly overstated.
+| 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
 

From 8fd028bc831f2fc8dd290e3f831b99848a407198 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 12:37:11 +0800
Subject: [PATCH 17/19] release: 2026.8.13.1

Both version sites, since the release workflow reads only config.cppm while
mcpp.toml drifts -- `tests/scripts/test_version_consistency.py` fails the PR
when they disagree.

`YYYY.M.D.N` with N starting at 1; `.0` is reserved for a milestone release.

Verified against the binary the bump actually produces, not the one at the path
I already had: a version change moves the mcpp fingerprint, so
target/67501c87.../bin/xlings kept reporting 2026.8.11.2 while the new build sat
at target/466b5e30.../bin/xlings. Contract scripts re-run against the new one --
cli parity 240 spellings / 64 literals, generated command reference, docs
examples, windows header hygiene.
---
 mcpp.toml            | 2 +-
 src/core/config.cppm | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/mcpp.toml b/mcpp.toml
index 4820c9e2..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"
diff --git a/src/core/config.cppm b/src/core/config.cppm
index e6896edf..fbd9839c 100644
--- a/src/core/config.cppm
+++ b/src/core/config.cppm
@@ -10,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";
 };
 

From 122a073778560360fc781af8b52b55489137cb48 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 12:41:46 +0800
Subject: [PATCH 18/19] docs: release notes for 2026.8.13.1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follows the house shape: 一句话 first, then the premises this round overturned,
recorded rather than quietly corrected. Three of them were mine:

- "TU count doubles so the cold build gets slower" -- it got 2.16x FASTER
- "the test-suite regression is link cost" -- falsified by phase 3, which
  changes only import edges and left the object count per binary identical
- "the control probe must not improve" -- it improves 2.9%, and that is exactly
  what makes it useful: it separates rebuild-set from rebuild-cost

Also the four toolchains and what each rejected, the invariants as numbers, and
the one thing deliberately left alone (1,953 lines of `inline` bodies, which
main's own tree carries identically).
---
 .../2026-08-13-release-2026.8.13.1-notes.md   | 104 ++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 .agents/docs/2026-08-13-release-2026.8.13.1-notes.md

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..60b23ce9
--- /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.5×,而这才是它有用的地方**
+
+`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` 反复变动的原因。本轮没动,留给维护者定。

From 2b76ef8cdb4d25967d1f7458d727b0635939c17b Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Thu, 13 Aug 2026 12:42:35 +0800
Subject: [PATCH 19/19] docs: say which tree each control ratio comes from

The control probe reads 2.5x on the phase-1-2 tree (43.58 -> 17.24) and 2.9x on
the final one (43.58 -> 15.24). Both were in the docs with neither labelled, so
the two looked like a contradiction. The ratio that carries the argument -- the
gap between the control and the moved probes -- is unchanged either way.
---
 .agents/docs/2026-08-13-module-impl-split-report.md  | 10 +++++++---
 .agents/docs/2026-08-13-release-2026.8.13.1-notes.md |  2 +-
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/.agents/docs/2026-08-13-module-impl-split-report.md b/.agents/docs/2026-08-13-module-impl-split-report.md
index d9c0c008..e90eccfe 100644
--- a/.agents/docs/2026-08-13-module-impl-split-report.md
+++ b/.agents/docs/2026-08-13-module-impl-split-report.md
@@ -205,8 +205,12 @@ 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
-2.5× is the interfaces downstream simply being smaller to recompile; the gap
-between 2.5× and 12× is what moving the body out actually bought.
+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
@@ -463,7 +467,7 @@ build is not evidence that a refactor is complete or that a report is true.
 | **`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×, because the interfaces it still rebuilds are smaller | comparing the claim against the measurement |
+| **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 |
 
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
index 60b23ce9..01429f3b 100644
--- 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
@@ -37,7 +37,7 @@ phase 3(裁剪残留 import)成了对照实验:它**只**改接口的 import 边
 
 真因是:每个测试 TU 都在加载接口里根本没提到的模块的 BMI。
 
-### 2.3 「对照探针必须不改善」→ **改善 2.5×,而这才是它有用的地方**
+### 2.3 「对照探针必须不改善」→ **改善 2.9×,而这才是它有用的地方**
 
 `compare_segment` 在两个分支上都是 `semver.cppm` 里的 `inline`,所以我写"它必须
 不变"。它变快了。原因是:编辑接口时两侧重编的**模块集合**相同,但分支上那些下游