fix(build): macOS test binaries link the toolchain's own libc++ (A1 root fix)

TestBinary previously linked the SYSTEM -lc++ while compiling against the
toolchain's libc++ HEADERS — a header/dylib version split that detonated
when libc++ 22 moved string hashing out of line (__hash_memory undefined
against Apple's older dylib; every gtest link on macOS+llvm-22.1.8 failed).

Tests are host-only by definition, so an rpath into the toolchain registry
is acceptable for them in a way it isn't for distributables. ldStdlibTest
becomes: -nostdlib++ -L<llvm>/lib -lc++ -lc++abi -Wl,-rpath,<llvm>/lib
(when the toolchain ships a libc++ dylib; system -lc++ fallback otherwise).
Same-version headers and dylib by construction — future libc++
out-of-lining is self-consistent. Dynamic teardown also dissolves the
static-destruction SIGABRT that originally motivated the system-lib
exception. Distributables keep the static -load_hidden LLVM libc++.

ci-macos returns to latest-first llvm install (the 20.1.7 pin's exit
criterion): the job now PROVES each new llvm default self-consistent.
New e2e 94_macos_test_stdlib (requires: macos): unordered_map<string>
hashing under mcpp test + otool -L asserts no /usr/lib/libc++ reference.

Design: .agents/docs/2026-07-08-root-cause-remediation-design.md A1.

Author: Sunrisepeak

.github/workflows/ci-macos.yml

@@ -58,10 +58,10 @@ jobs:
 
       - name: Install LLVM via xlings
         run: |
-          # Pin 20.1.7: llvm 22.1.8's libc++ headers reference __hash_memory,
-          # absent from the libc++ the link resolves on macOS (ld64.lld
-          # undefined symbol; hermetic-link follow-up tracks the real fix).
-          xlings install llvm@20.1.7 -y || xlings install llvm -y
+          # latest-first: test binaries now link the toolchain's own libc++
+          # (A1 root fix in flags.cppm), so new llvm releases are
+          # self-consistent — this job is the proof for each new default.
+          xlings install llvm -y || xlings install llvm@20.1.7 -y
           # Verify clang++ is available
           LLVM_ROOT=$(find "$HOME/.xlings" -path "*/xpkgs/xim-x-llvm/*/bin/clang++" | head -1 | xargs dirname | xargs dirname)
           echo "LLVM_ROOT=$LLVM_ROOT"

src/build/flags.cppm

@@ -35,10 +35,11 @@ struct CompileFlags {
     std::string linkage;  // "static" or ""
     // macOS per-unit C++ stdlib link (appended via unit_ldflags):
     // distributable targets get the static LLVM libc++ (portable across
-    // macOS versions), TestBinary targets get the system -lc++ — they
-    // only ever run on the build host, and statically linked libc++
-    // SIGABRTs during static destruction unless the entry point guards
-    // with _Exit (mcpp/xlings do; gtest main does not). Empty on other
+    // macOS versions); TestBinary targets get the toolchain's own libc++
+    // DYNAMICALLY (-L + -lc++ + rpath into the toolchain) — host-only
+    // binaries, so the rpath is fine, and it keeps headers and dylib the
+    // same version (the system -lc++ they used before was a version split
+    // that broke on libc++ 22's out-of-line __hash_memory). Empty on other
     // platforms (stdlib handled by their existing paths).
     std::string ldStdlibDefault;
     std::string ldStdlibTest;
@@ -385,6 +386,27 @@ CompileFlags compute_flags(const BuildPlan& plan) {
                   + " -Wl,-load_hidden," + escape_path(libcxxAbiA);
             }
         }
+        // TestBinary: link the toolchain's OWN libc++, dynamically. Tests
+        // previously took the SYSTEM -lc++ while compiling against the
+        // toolchain's libc++ HEADERS — a header/dylib version split that
+        // detonated when libc++ 22 moved string hashing out of line
+        // (undefined __hash_memory against Apple's older dylib, 2026-07-08).
+        // Tests are host-only by definition, so an rpath into the toolchain
+        // registry is fine here in a way it isn't for distributables:
+        // same-version headers and dylib by construction, and dynamic
+        // teardown avoids the static-destruction SIGABRT that motivated the
+        // system-lib exception in the first place (gtest's main has no _Exit
+        // guard). Falls back to the system -lc++ when the toolchain ships no
+        // dylib. Design: .agents/docs/2026-07-08-root-cause-remediation-design.md A1.
+        if (!llvmRootForStdlib.empty()) {
+            auto libDir = llvmRootForStdlib / "lib";
+            if (std::filesystem::exists(libDir / "libc++.dylib")
+                || std::filesystem::exists(libDir / "libc++.1.dylib")) {
+                f.ldStdlibTest = " -nostdlib++ -L" + escape_path(libDir)
+                               + " -lc++ -lc++abi"
+                               + " -Wl,-rpath," + escape_path(libDir);
+            }
+        }
         std::string version_min;
         if (!macosDeploymentTarget.empty()) {
             version_min = " -mmacosx-version-min=" + macosDeploymentTarget;

tests/e2e/94_macos_test_stdlib.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# requires: macos
+# 94_macos_test_stdlib.sh — A1 regression: test binaries must link the
+# TOOLCHAIN's libc++, not the system one. The old system -lc++ exception
+# split headers (toolchain libc++) from the dylib (Apple's older libc++)
+# and broke on libc++ 22's out-of-line __hash_memory — exercised here via
+# std::unordered_map<std::string,...> string hashing.
+# Design: .agents/docs/2026-07-08-root-cause-remediation-design.md A1.
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+cd "$TMP"
+
+"$MCPP" new hashapp > /dev/null
+cd hashapp
+
+mkdir -p tests
+cat > tests/hash_test.cpp <<'EOF'
+// Forces the string-hash path (__hash_memory-class symbols on libc++ >= 22).
+import std;
+
+int main() {
+    std::unordered_map<std::string, int> m;
+    for (int i = 0; i < 100; ++i) m["key" + std::to_string(i)] = i;
+    return (m.size() == 100 && m.at("key42") == 42) ? 0 : 1;
+}
+EOF
+
+"$MCPP" test > test.log 2>&1 || { cat test.log; echo "FAIL: mcpp test failed"; exit 1; }
+grep -q "1 passed" test.log
+
+# The link assertion only applies to clang/llvm toolchains (gcc on macOS is
+# not a supported config; if resolution picked something else, the behavior
+# test above already covered the regression).
+TEST_BIN=$(find target -path "*/bin/hash_test" | head -1)
+test -x "$TEST_BIN"
+if grep -q "Resolved llvm@" test.log || otool -L "$TEST_BIN" | grep -q "libc++"; then
+    echo "otool -L:"
+    otool -L "$TEST_BIN"
+    if otool -L "$TEST_BIN" | grep -q "/usr/lib/libc++"; then
+        echo "FAIL: test binary links the SYSTEM libc++ (header/dylib split)"
+        exit 1
+    fi
+    # Either the toolchain's dylib (rpath link) or no libc++ dylib at all
+    # (static fallback) is acceptable — never Apple's.
+fi
+
+echo "PASS 94_macos_test_stdlib"

tests/e2e/run_all.sh

@@ -58,7 +58,7 @@ case "$OS" in
         fi
         ;;
     Darwin)
-        CAPS+=(unix-shell fresh-sandbox)
+        CAPS+=(unix-shell fresh-sandbox macos)
         # macOS g++ is Apple Clang, not real GCC — don't add gcc capability.
         # Tests requiring gcc need actual GNU GCC (modules, gcm.cache, etc.)
         ;;