refactor(server, tests): improve error feedback, logging, and test infrastructure

Replace silent null returns with proper LSP errors (kota::fail) for
feature requests on closed documents, failed compilations, invalid
positions, and unresolvable hierarchy items. Add client notifications
(window/logMessage) for key failures so integration tests can observe
errors without reading server logs. Expand logging coverage in
compilation pipeline (compile args, compilation phases, worker results).

Improve test infrastructure: conditional log dump on failure, yield-based
workspace fixture with post-test cleanup, named timing constants replacing
hardcoded sleeps, and log message capture/assertion helpers.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.github/actions/setup-pixi/action.yml

@@ -13,7 +13,7 @@ runs:
     - name: Setup Pixi
       uses: prefix-dev/setup-pixi@v0.9.3
       with:
-        pixi-version: v0.62.0
+        pixi-version: v0.67.0
         environments: ${{ inputs.environments }}
         activate-environment: true
         cache: true

.github/workflows/benchmark.yml

@@ -21,7 +21,7 @@ jobs:
 
       - name: Build scan_benchmark
         run: |
-          pixi run cmake-config RelWithDebInfo ON "-DCLICE_ENABLE_BENCHMARK=ON"
+          pixi run cmake-config RelWithDebInfo ON -- -DCLICE_ENABLE_BENCHMARK=ON
           cmake --build build/RelWithDebInfo --target scan_benchmark
 
       - name: Clone LLVM

.github/workflows/build-llvm.yml

@@ -1,6 +1,22 @@
 name: build llvm
 
 on:
+  workflow_dispatch:
+    inputs:
+      llvm_version:
+        description: "LLVM version to build (e.g., 21.1.8)"
+        required: true
+        type: string
+      skip_upload:
+        description: "Skip upload and PR creation (build-only mode)"
+        required: false
+        type: boolean
+        default: false
+      skip_pr:
+        description: "Skip PR creation (upload only, no PR)"
+        required: false
+        type: boolean
+        default: false
   pull_request:
     # if you want to run this workflow, change the branch name to main,
     # if you want to turn off it, change it to non existent branch.
@@ -12,9 +28,7 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - os: windows-2025
-            llvm_mode: Debug
-            lto: OFF
+          # Native builds
           - os: windows-2025
             llvm_mode: RelWithDebInfo
             lto: OFF
@@ -39,6 +53,42 @@ jobs:
           - os: macos-15
             llvm_mode: RelWithDebInfo
             lto: ON
+
+          # Cross-compilation builds
+          # macOS x64 (from arm64 macos-15)
+          - os: macos-15
+            llvm_mode: RelWithDebInfo
+            lto: OFF
+            target_triple: x86_64-apple-darwin
+          - os: macos-15
+            llvm_mode: RelWithDebInfo
+            lto: ON
+            target_triple: x86_64-apple-darwin
+
+          # Linux aarch64 (from x64 ubuntu-24.04)
+          - os: ubuntu-24.04
+            llvm_mode: RelWithDebInfo
+            lto: OFF
+            target_triple: aarch64-linux-gnu
+            pixi_env: cross-linux-aarch64
+          - os: ubuntu-24.04
+            llvm_mode: RelWithDebInfo
+            lto: ON
+            target_triple: aarch64-linux-gnu
+            pixi_env: cross-linux-aarch64
+
+          # Windows arm64 (from x64 windows-2025)
+          - os: windows-2025
+            llvm_mode: RelWithDebInfo
+            lto: OFF
+            target_triple: aarch64-pc-windows-msvc
+            pixi_env: cross-windows-arm64
+          - os: windows-2025
+            llvm_mode: RelWithDebInfo
+            lto: ON
+            target_triple: aarch64-pc-windows-msvc
+            pixi_env: cross-windows-arm64
+
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout repository
@@ -67,49 +117,91 @@ jobs:
           free -h
           df -h
 
-      - name: Setup Pixi
-        uses: prefix-dev/setup-pixi@v0.9.3
+      - uses: ./.github/actions/setup-pixi
         with:
-          pixi-version: v0.59.0
-          environments: package
-          activate-environment: true
-          cache: true
-          locked: true
+          environments: ${{ matrix.pixi_env || 'package' }}
 
-      - name: Clone llvm-project (21.1.4)
+      - name: Clone llvm-project
         shell: bash
         run: |
-          git clone --branch llvmorg-21.1.4 --depth 1 https://github.com/llvm/llvm-project.git .llvm
+          VERSION="${{ inputs.llvm_version || '21.1.8' }}"
+          echo "Cloning LLVM ${VERSION}..."
+          git clone --branch "llvmorg-${VERSION}" --depth 1 https://github.com/llvm/llvm-project.git .llvm
+
+      - name: Validate distribution components
+        shell: bash
+        run: |
+          python3 scripts/validate-llvm-components.py \
+            --llvm-src=.llvm \
+            --components-file=scripts/llvm-components.json
 
       - name: Build LLVM (install-distribution)
         shell: bash
         run: |
-          pixi run build-llvm --llvm-src=.llvm --mode="${{ matrix.llvm_mode }}" --lto="${{ matrix.lto }}" --build-dir=build
+          ENV="${{ matrix.pixi_env || 'package' }}"
+          EXTRA_ARGS=""
+          if [[ -n "${{ matrix.target_triple }}" ]]; then
+            EXTRA_ARGS="--target-triple=${{ matrix.target_triple }}"
+          fi
+          pixi run -e "$ENV" build-llvm \
+            --llvm-src=.llvm \
+            --mode="${{ matrix.llvm_mode }}" \
+            --lto="${{ matrix.lto }}" \
+            --build-dir=build \
+            ${EXTRA_ARGS}
 
       - name: Build clice using installed LLVM
+        if: ${{ !matrix.target_triple }}
         shell: bash
         run: |
-          cmake -B build -G Ninja \
-            -DCMAKE_BUILD_TYPE=${{ matrix.llvm_mode }} \
-            -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain.cmake \
-            -DCLICE_ENABLE_TEST=ON \
-            -DCLICE_CI_ENVIRONMENT=ON \
-            -DCLICE_ENABLE_LTO=${{ matrix.lto }} \
-            -DLLVM_INSTALL_PATH=".llvm/build-install"
-          cmake --build build
+          pixi run cmake-config ${{ matrix.llvm_mode }} ON -- \
+            "-DCLICE_ENABLE_LTO=${{ matrix.lto }}" \
+            "-DLLVM_INSTALL_PATH=.llvm/build-install"
+          pixi run cmake-build ${{ matrix.llvm_mode }}
+
+      - name: Build clice using installed LLVM (cross-compile)
+        if: ${{ matrix.target_triple }}
+        shell: bash
+        run: |
+          ENV="${{ matrix.pixi_env || 'package' }}"
+          pixi run -e "$ENV" cmake-config ${{ matrix.llvm_mode }} ON -- \
+            "-DCLICE_ENABLE_LTO=${{ matrix.lto }}" \
+            "-DCLICE_TARGET_TRIPLE=${{ matrix.target_triple }}" \
+            "-DLLVM_INSTALL_PATH=.llvm/build-install"
+          pixi run -e "$ENV" cmake-build ${{ matrix.llvm_mode }}
+
+      - name: Verify cross-compiled binary architecture
+        if: ${{ matrix.target_triple && runner.os != 'Windows' }}
+        shell: bash
+        run: |
+          BINARY="build/${{ matrix.llvm_mode }}/bin/clice"
+          echo "Binary info:"
+          file "$BINARY"
+          case "${{ matrix.target_triple }}" in
+            aarch64-linux-gnu)   file "$BINARY" | grep -q "aarch64" ;;
+            x86_64-apple-darwin) file "$BINARY" | grep -q "x86_64" ;;
+          esac
+
+      - name: Upload cross-compiled clice for functional test
+        if: ${{ matrix.target_triple && matrix.lto == 'OFF' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: cross-clice-${{ matrix.target_triple }}-${{ matrix.llvm_mode }}
+          path: |
+            build/${{ matrix.llvm_mode }}/bin/
+            build/${{ matrix.llvm_mode }}/lib/
+          if-no-files-found: error
+          retention-days: 1
 
       - name: Run tests
+        if: ${{ !matrix.target_triple }}
         shell: bash
-        run: |
-          EXE_EXT=""
-          if [[ "${{ runner.os }}" == "Windows" ]]; then
-            EXE_EXT=".exe"
-          fi
-          ./build/bin/unit_tests${EXE_EXT} --test-dir="./tests/data"
-          uv run --project tests pytest -s --log-cli-level=INFO tests/integration --executable=./build/bin/clice${EXE_EXT}
+        run: pixi run test ${{ matrix.llvm_mode }}
 
+      # Prune is only supported for native builds (requires linking clice to test).
+      # Cross-compiled targets reuse the native prune manifest of the same OS.
       - name: Prune LLVM static libraries (Debug/RelWithDebInfo no LTO)
-        if: matrix.llvm_mode == 'Debug' || (matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'OFF')
+        if: (!matrix.target_triple) && (matrix.llvm_mode == 'Debug' || (matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'OFF'))
         shell: bash
         run: |
           MANIFEST="pruned-libs-${{ matrix.os }}.json"
@@ -117,13 +209,13 @@ jobs:
           python3 scripts/prune-llvm-bin.py \
             --action discover \
             --install-dir ".llvm/build-install/lib" \
-            --build-dir "build" \
+            --build-dir "build/${{ matrix.llvm_mode }}" \
             --max-attempts 60 \
             --sleep-seconds 60 \
             --manifest "${MANIFEST}"
 
       - name: Upload pruned-libs manifest
-        if: matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'OFF'
+        if: (!matrix.target_triple) && matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'OFF'
         uses: actions/upload-artifact@v4
         with:
           name: llvm-pruned-libs-${{ matrix.os }}
@@ -131,8 +223,8 @@ jobs:
           if-no-files-found: error
           compression-level: 0
 
-      - name: Apply pruned-libs manifest (RelWithDebInfo + LTO)
-        if: matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'ON'
+      - name: Apply pruned-libs manifest (RelWithDebInfo + LTO, native only)
+        if: (!matrix.target_triple) && matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'ON'
         shell: bash
         env:
           GH_TOKEN: ${{ github.token }}
@@ -142,7 +234,27 @@ jobs:
             --action apply \
             --manifest "${MANIFEST}" \
             --install-dir ".llvm/build-install/lib" \
-            --build-dir "build" \
+            --build-dir "build/${{ matrix.llvm_mode }}" \
+            --gh-run-id "${{ github.run_id }}" \
+            --gh-artifact "llvm-pruned-libs-${{ matrix.os }}" \
+            --gh-download-dir "artifacts" \
+            --max-attempts 60 \
+            --sleep-seconds 60
+
+      # For cross-compiled LTO builds, apply the native prune manifest.
+      # The unused library set is arch-independent (same API surface).
+      - name: Apply pruned-libs manifest (cross-compile + LTO)
+        if: matrix.target_triple && matrix.lto == 'ON'
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          MANIFEST="pruned-libs-${{ matrix.os }}.json"
+          python3 scripts/prune-llvm-bin.py \
+            --action apply \
+            --manifest "${MANIFEST}" \
+            --install-dir ".llvm/build-install/lib" \
+            --build-dir "build/${{ matrix.llvm_mode }}" \
             --gh-run-id "${{ github.run_id }}" \
             --gh-artifact "llvm-pruned-libs-${{ matrix.os }}" \
             --gh-download-dir "artifacts" \
@@ -157,23 +269,35 @@ jobs:
             MODE_TAG="debug"
           fi
 
-          ARCH="x64"
-          PLATFORM="linux"
-          TOOLCHAIN="gnu"
-          if [[ "${{ matrix.os }}" == windows-* ]]; then
-            PLATFORM="windows"
-            TOOLCHAIN="msvc"
-          elif [[ "${{ matrix.os }}" == macos-* ]]; then
-            ARCH="arm64"
-            PLATFORM="macos"
-            TOOLCHAIN="clang"
+          # Determine arch/platform/toolchain from target triple or runner OS
+          if [[ -n "${{ matrix.target_triple }}" ]]; then
+            case "${{ matrix.target_triple }}" in
+              x86_64-apple-darwin)
+                ARCH="x64"; PLATFORM="macos"; TOOLCHAIN="clang" ;;
+              aarch64-linux-gnu)
+                ARCH="aarch64"; PLATFORM="linux"; TOOLCHAIN="gnu" ;;
+              aarch64-pc-windows-msvc)
+                ARCH="aarch64"; PLATFORM="windows"; TOOLCHAIN="msvc" ;;
+            esac
+          else
+            ARCH="x64"
+            PLATFORM="linux"
+            TOOLCHAIN="gnu"
+            if [[ "${{ matrix.os }}" == windows-* ]]; then
+              PLATFORM="windows"
+              TOOLCHAIN="msvc"
+            elif [[ "${{ matrix.os }}" == macos-* ]]; then
+              ARCH="arm64"
+              PLATFORM="macos"
+              TOOLCHAIN="clang"
+            fi
           fi
 
           SUFFIX=""
           if [[ "${{ matrix.lto }}" == "ON" ]]; then
             SUFFIX="-lto"
           fi
-          if [[ "${{ matrix.llvm_mode }}" == "Debug" ]]; then
+          if [[ "${{ matrix.llvm_mode }}" == "Debug" && "${{ matrix.os }}" != windows-* ]]; then
             SUFFIX="${SUFFIX}-asan"
           fi
 
@@ -189,3 +313,134 @@ jobs:
           name: ${{ env.LLVM_INSTALL_ARCHIVE }}
           path: ${{ env.LLVM_INSTALL_ARCHIVE }}
           if-no-files-found: error
+
+  test-cross:
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-15-intel
+            llvm_mode: RelWithDebInfo
+            target_triple: x86_64-apple-darwin
+          - os: ubuntu-24.04-arm
+            llvm_mode: RelWithDebInfo
+            target_triple: aarch64-linux-gnu
+          - os: windows-11-arm
+            llvm_mode: RelWithDebInfo
+            target_triple: aarch64-pc-windows-msvc
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - uses: ./.github/actions/setup-pixi
+        with:
+          environments: test-run
+
+      - name: Download cross-compiled clice
+        uses: actions/download-artifact@v4
+        with:
+          name: cross-clice-${{ matrix.target_triple }}-${{ matrix.llvm_mode }}
+          path: build/${{ matrix.llvm_mode }}/
+
+      - name: Make binaries executable
+        if: runner.os != 'Windows'
+        run: chmod +x build/${{ matrix.llvm_mode }}/bin/*
+
+      - name: Run tests
+        run: pixi run -e test-run test ${{ matrix.llvm_mode }}
+
+  upload:
+    needs: build
+    if: ${{ !cancelled() && inputs.llvm_version && !inputs.skip_upload }}
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download all build artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: scripts/download-llvm.sh "${{ github.run_id }}"
+
+      - name: Upload to clice-llvm
+        env:
+          GH_TOKEN: ${{ secrets.UPLOAD_LLVM }}
+          TARGET_REPO: clice-io/clice-llvm
+        run: python3 scripts/upload-llvm.py "${{ inputs.llvm_version }}" "${TARGET_REPO}" "${{ github.run_id }}"
+
+      - name: Save manifest for update-clice job
+        uses: actions/upload-artifact@v4
+        with:
+          name: llvm-manifest-final
+          path: artifacts/llvm-manifest.json
+          if-no-files-found: error
+          compression-level: 0
+
+  update-clice:
+    needs: upload
+    if: ${{ !inputs.skip_pr }}
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download manifest
+        uses: actions/download-artifact@v4
+        with:
+          name: llvm-manifest-final
+          path: .
+
+      - name: Update manifest and version
+        run: |
+          python3 scripts/update-llvm-version.py \
+            --version "${{ inputs.llvm_version }}" \
+            --manifest-src llvm-manifest.json \
+            --manifest-dest config/llvm-manifest.json \
+            --package-cmake cmake/package.cmake
+
+      - name: Create or update PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          VERSION="${{ inputs.llvm_version }}"
+          BRANCH="chore/update-llvm-${VERSION}"
+          RUN_URL="https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          RELEASE_URL="https://github.com/clice-io/clice-llvm/releases/tag/${VERSION}"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "${BRANCH}"
+          git add config/llvm-manifest.json cmake/package.cmake
+          git commit -m "chore: update LLVM to ${VERSION}"
+          git push --force-with-lease origin "${BRANCH}"
+
+          # Check if PR already exists for this branch
+          EXISTING_PR=$(gh pr list --head "${BRANCH}" --json number --jq '.[0].number // empty')
+
+          BODY="$(cat <<EOF
+          ## Summary
+          - Update LLVM prebuilt binaries to version ${VERSION}
+          - Updated \`config/llvm-manifest.json\` with new SHA256 hashes
+          - Updated \`cmake/package.cmake\` version string
+
+          **Artifacts:** [clice-llvm release](${RELEASE_URL})
+          **Build:** [workflow run](${RUN_URL})
+
+          > Auto-generated by build-llvm workflow
+          EOF
+          )"
+
+          if [[ -n "${EXISTING_PR}" ]]; then
+            echo "Updating existing PR #${EXISTING_PR}"
+            gh pr edit "${EXISTING_PR}" --body "${BODY}"
+          else
+            gh pr create \
+              --title "chore: update LLVM to ${VERSION}" \
+              --body "${BODY}" \
+              --base main
+          fi

.github/workflows/check-format.yml

@@ -14,6 +14,12 @@ jobs:
         with:
           environments: format
 
+      - name: Validate update-llvm-version.py can still patch package.cmake
+        run: |
+          python3 scripts/update-llvm-version.py --check \
+            --manifest-dest config/llvm-manifest.json \
+            --package-cmake cmake/package.cmake
+
       - name: Run formatter
         run: pixi run format
         continue-on-error: true

.github/workflows/main.yml

@@ -7,6 +7,10 @@ on:
   pull_request:
     branches: [main]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
 jobs:
   changes:
     if: ${{ !startsWith(github.ref, 'refs/tags/') }}

.github/workflows/publish-clice.yml

@@ -9,6 +9,7 @@ jobs:
       fail-fast: false
       matrix:
         include:
+          # Native builds
           - os: windows-2025
             artifact_name: clice.zip
             asset_name: clice-x64-windows-msvc.zip
@@ -27,6 +28,31 @@ jobs:
             symbol_artifact_name: clice-symbol.tar.gz
             symbol_asset_name: clice-arm64-macos-darwin-symbol.tar.gz
 
+          # Cross-compilation builds
+          - os: macos-15
+            target_triple: x86_64-apple-darwin
+            pixi_env: cross-macos-x64
+            artifact_name: clice.tar.gz
+            asset_name: clice-x86_64-macos-darwin.tar.gz
+            symbol_artifact_name: clice-symbol.tar.gz
+            symbol_asset_name: clice-x86_64-macos-darwin-symbol.tar.gz
+
+          - os: ubuntu-24.04
+            target_triple: aarch64-linux-gnu
+            pixi_env: cross-linux-aarch64
+            artifact_name: clice.tar.gz
+            asset_name: clice-aarch64-linux-gnu.tar.gz
+            symbol_artifact_name: clice-symbol.tar.gz
+            symbol_asset_name: clice-aarch64-linux-gnu-symbol.tar.gz
+
+          - os: windows-2025
+            target_triple: aarch64-pc-windows-msvc
+            pixi_env: cross-windows-arm64
+            artifact_name: clice.zip
+            asset_name: clice-aarch64-windows-msvc.zip
+            symbol_artifact_name: clice-symbol.zip
+            symbol_asset_name: clice-aarch64-windows-msvc-symbol.zip
+
     runs-on: ${{ matrix.os }}
 
     defaults:
@@ -39,11 +65,20 @@ jobs:
 
       - uses: ./.github/actions/setup-pixi
         with:
-          environments: package
+          environments: ${{ matrix.pixi_env || 'package' }}
 
-      - name: Package
+      - name: Package (native)
+        if: ${{ !matrix.target_triple }}
         run: pixi run package
 
+      - name: Package (cross-compile)
+        if: ${{ matrix.target_triple }}
+        run: |
+          ENV="${{ matrix.pixi_env }}"
+          pixi run -e "$ENV" package-config -- \
+            "-DCLICE_TARGET_TRIPLE=${{ matrix.target_triple }}"
+          pixi run -e "$ENV" cmake-build
+
       - name: Upload Main Package to Release
         if: startsWith(github.ref, 'refs/tags/v')
         uses: svenstaro/upload-release-action@v2

.github/workflows/test-cmake.yml

@@ -17,53 +17,154 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [windows-2025, ubuntu-24.04, macos-15]
-        build_type: [Debug, RelWithDebInfo]
+        include:
+          # Native builds
+          - os: windows-2025
+            build_type: RelWithDebInfo
+          - os: ubuntu-24.04
+            build_type: Debug
+          - os: ubuntu-24.04
+            build_type: RelWithDebInfo
+          - os: macos-15
+            build_type: Debug
+          - os: macos-15
+            build_type: RelWithDebInfo
+          # Cross-compile (build only; tests run on native runners)
+          - os: macos-15
+            build_type: RelWithDebInfo
+            target_triple: x86_64-apple-darwin
+            build_only: true
+          - os: ubuntu-24.04
+            build_type: RelWithDebInfo
+            target_triple: aarch64-linux-gnu
+            build_only: true
+            pixi_env: cross-linux-aarch64
+          - os: windows-2025
+            build_type: RelWithDebInfo
+            target_triple: aarch64-pc-windows-msvc
+            build_only: true
+            pixi_env: cross-windows-arm64
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
       - uses: ./.github/actions/setup-pixi
+        with:
+          environments: ${{ matrix.pixi_env || 'default' }}
 
       - name: Restore compiler cache
         uses: actions/cache@v4
         with:
           path: ${{ runner.os == 'Windows' && '.cache/sccache' || '.cache/ccache' }}
-          key: ${{ runner.os }}-${{ matrix.build_type }}-ccache-${{ github.sha }}
+          key: ${{ runner.os }}-${{ matrix.build_type }}-${{ matrix.target_triple || 'native' }}-ccache-${{ github.sha }}
           restore-keys: |
-            ${{ runner.os }}-${{ matrix.build_type }}-ccache-
+            ${{ runner.os }}-${{ matrix.build_type }}-${{ matrix.target_triple || 'native' }}-ccache-
 
       - name: Zero cache stats
         run: |
+          ENV="${{ matrix.pixi_env || 'default' }}"
           if [ "$RUNNER_OS" = "Windows" ]; then
-            pixi run -- sccache --stop-server || true
-            pixi run -- sccache --zero-stats || true
+            pixi run -e "$ENV" -- sccache --stop-server || true
+            pixi run -e "$ENV" -- sccache --zero-stats || true
           else
-            pixi run -- ccache --zero-stats || true
+            pixi run -e "$ENV" -- ccache --zero-stats || true
           fi
         shell: bash
 
-      - name: Build
+      - name: Build (native)
+        if: ${{ !matrix.target_triple }}
         run: pixi run build ${{ matrix.build_type }} ON
 
-      - name: Unit Test
+      - name: Build (cross-compile)
+        if: ${{ matrix.target_triple }}
+        shell: bash
+        run: |
+          ENV="${{ matrix.pixi_env || 'default' }}"
+          pixi run -e "$ENV" cmake-config ${{ matrix.build_type }} OFF -- \
+            "-DCLICE_TARGET_TRIPLE=${{ matrix.target_triple }}"
+          pixi run -e "$ENV" cmake-build ${{ matrix.build_type }}
+
+      - name: Upload cross-compiled binaries
+        if: ${{ matrix.build_only }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: cross-build-${{ matrix.target_triple }}
+          path: |
+            build/${{ matrix.build_type }}/bin/
+            build/${{ matrix.build_type }}/lib/
+          if-no-files-found: error
+          retention-days: 1
+
+      - name: Unit tests
+        if: ${{ !matrix.build_only }}
+        timeout-minutes: 5
         run: pixi run unit-test ${{ matrix.build_type }}
 
-      - name: Integration Test
+      - name: Integration tests
+        if: ${{ !matrix.build_only }}
+        timeout-minutes: 20
         run: pixi run integration-test ${{ matrix.build_type }}
 
-      - name: Smoke Test
-        if: success() || failure()
+      - name: Smoke tests
+        if: ${{ !matrix.build_only }}
+        timeout-minutes: 15
         run: pixi run smoke-test ${{ matrix.build_type }}
 
       - name: Print cache stats and stop server
         if: always()
         run: |
+          ENV="${{ matrix.pixi_env || 'default' }}"
           if [ "$RUNNER_OS" = "Windows" ]; then
-            pixi run -- sccache --show-stats
-            pixi run -- sccache --stop-server || true
+            pixi run -e "$ENV" -- sccache --show-stats
+            pixi run -e "$ENV" -- sccache --stop-server || true
           else
-            pixi run -- ccache --show-stats
+            pixi run -e "$ENV" -- ccache --show-stats
           fi
         shell: bash
+
+  test-cross:
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-15-intel
+            build_type: RelWithDebInfo
+            target_triple: x86_64-apple-darwin
+          - os: ubuntu-24.04-arm
+            build_type: RelWithDebInfo
+            target_triple: aarch64-linux-gnu
+          - os: windows-11-arm
+            build_type: RelWithDebInfo
+            target_triple: aarch64-pc-windows-msvc
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - uses: ./.github/actions/setup-pixi
+        with:
+          environments: test-run
+
+      - name: Download cross-compiled binaries
+        uses: actions/download-artifact@v4
+        with:
+          name: cross-build-${{ matrix.target_triple }}
+          path: build/${{ matrix.build_type }}/
+
+      - name: Make binaries executable
+        if: runner.os != 'Windows'
+        run: chmod +x build/${{ matrix.build_type }}/bin/*
+
+      - name: Unit tests
+        timeout-minutes: 5
+        run: pixi run -e test-run unit-test ${{ matrix.build_type }}
+
+      - name: Integration tests
+        timeout-minutes: 20
+        run: pixi run -e test-run integration-test ${{ matrix.build_type }}
+
+      - name: Smoke tests
+        timeout-minutes: 10
+        run: pixi run -e test-run smoke-test ${{ matrix.build_type }}

CMakeLists.txt

@@ -127,9 +127,16 @@ endif()
 set(FBS_SCHEMA_FILE "${PROJECT_SOURCE_DIR}/src/index/schema.fbs")
 set(GENERATED_HEADER "${PROJECT_BINARY_DIR}/generated/schema_generated.h")
 
+if(CMAKE_CROSSCOMPILING)
+    find_program(FLATC_EXECUTABLE flatc REQUIRED)
+    set(FLATC_CMD "${FLATC_EXECUTABLE}")
+else()
+    set(FLATC_CMD "$<TARGET_FILE:flatc>")
+endif()
+
 add_custom_command(
     OUTPUT "${GENERATED_HEADER}"
-    COMMAND $<TARGET_FILE:flatc> --cpp -o "${PROJECT_BINARY_DIR}/generated" "${FBS_SCHEMA_FILE}"
+    COMMAND ${FLATC_CMD} --cpp -o "${PROJECT_BINARY_DIR}/generated" "${FBS_SCHEMA_FILE}"
     DEPENDS "${FBS_SCHEMA_FILE}"
     COMMENT "Generating C++ header from ${FBS_SCHEMA_FILE}"
 )

benchmarks/scan_benchmark.cpp

@@ -26,7 +26,7 @@
 #include "support/path_pool.h"
 #include "syntax/dependency_graph.h"
 
-#include "kota/codec/json/serializer.h"
+#include "kota/codec/json/json.h"
 #include "kota/deco/deco.h"
 #include "llvm/Support/FileSystem.h"
 

cmake/llvm.cmake

@@ -25,6 +25,22 @@ function(setup_llvm LLVM_VERSION)
         list(APPEND LLVM_SETUP_ARGS "--offline")
     endif()
 
+    if(DEFINED CLICE_TARGET_TRIPLE)
+        if(CLICE_TARGET_TRIPLE MATCHES "linux")
+            list(APPEND LLVM_SETUP_ARGS "--target-platform" "Linux")
+        elseif(CLICE_TARGET_TRIPLE MATCHES "darwin")
+            list(APPEND LLVM_SETUP_ARGS "--target-platform" "macosx")
+        elseif(CLICE_TARGET_TRIPLE MATCHES "windows")
+            list(APPEND LLVM_SETUP_ARGS "--target-platform" "Windows")
+        endif()
+
+        if(CLICE_TARGET_TRIPLE MATCHES "^aarch64")
+            list(APPEND LLVM_SETUP_ARGS "--target-arch" "arm64")
+        elseif(CLICE_TARGET_TRIPLE MATCHES "^x86_64")
+            list(APPEND LLVM_SETUP_ARGS "--target-arch" "x64")
+        endif()
+    endif()
+
     execute_process(
         COMMAND "${Python3_EXECUTABLE}" "${LLVM_SETUP_SCRIPT}" ${LLVM_SETUP_ARGS}
         RESULT_VARIABLE LLVM_SETUP_RESULT

cmake/package.cmake

@@ -1,7 +1,7 @@
 include_guard()
 
 include(${CMAKE_CURRENT_LIST_DIR}/llvm.cmake)
-setup_llvm("21.1.4+r1")
+setup_llvm("21.1.8")
 
 # install dependencies
 include(FetchContent)

cmake/toolchain.cmake

@@ -1,5 +1,29 @@
 cmake_minimum_required(VERSION 3.30)
 
+# Cross-compilation support via CLICE_TARGET_TRIPLE.
+# Examples:
+#   -DCLICE_TARGET_TRIPLE=x86_64-apple-darwin      (macOS x64 from arm64)
+#   -DCLICE_TARGET_TRIPLE=aarch64-linux-gnu         (Linux arm64 from x64)
+#   -DCLICE_TARGET_TRIPLE=aarch64-pc-windows-msvc   (Windows arm64 from x64)
+if(DEFINED CLICE_TARGET_TRIPLE)
+    if(CLICE_TARGET_TRIPLE MATCHES "^x86_64-apple-darwin")
+        set(CMAKE_OSX_ARCHITECTURES "x86_64" CACHE STRING "")
+    elseif(CLICE_TARGET_TRIPLE MATCHES "^aarch64-.*linux")
+        set(CMAKE_SYSTEM_NAME Linux)
+        set(CMAKE_SYSTEM_PROCESSOR aarch64)
+        set(CMAKE_C_COMPILER_TARGET "aarch64-linux-gnu" CACHE STRING "")
+        set(CMAKE_CXX_COMPILER_TARGET "aarch64-linux-gnu" CACHE STRING "")
+        if(DEFINED ENV{CONDA_PREFIX} AND NOT DEFINED CMAKE_SYSROOT)
+            set(CMAKE_SYSROOT "$ENV{CONDA_PREFIX}/aarch64-conda-linux-gnu/sysroot" CACHE PATH "")
+        endif()
+    elseif(CLICE_TARGET_TRIPLE MATCHES "^aarch64-.*-windows")
+        set(CMAKE_SYSTEM_NAME Windows)
+        set(CMAKE_SYSTEM_PROCESSOR ARM64)
+        set(CMAKE_C_COMPILER_TARGET "aarch64-pc-windows-msvc" CACHE STRING "")
+        set(CMAKE_CXX_COMPILER_TARGET "aarch64-pc-windows-msvc" CACHE STRING "")
+    endif()
+endif()
+
 set(CMAKE_C_COMPILER clang CACHE STRING "")
 set(CMAKE_CXX_COMPILER clang++ CACHE STRING "")
 

config/llvm-manifest.json

@@ -1,83 +1,142 @@
 [
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
+    "filename": "aarch64-linux-gnu-releasedbg-lto.tar.xz",
+    "sha256": "f3444ee840b50933c23656cbee7c4d010e752ac55ca66095b97f7c0e997b13b5",
+    "lto": true,
+    "asan": false,
+    "platform": "linux",
+    "arch": "arm64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
+    "filename": "aarch64-linux-gnu-releasedbg.tar.xz",
+    "sha256": "b9012bf059e4d8673fb564b5780e5fc78c6a2e47f5cc6a39f444d1879b42dd2a",
+    "lto": false,
+    "asan": false,
+    "platform": "linux",
+    "arch": "arm64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
+    "filename": "aarch64-windows-msvc-releasedbg-lto.tar.xz",
+    "sha256": "8870d16141ba7f9ea12f5147b8d91329abbbaa4376cd4576667dd323d896dd08",
+    "lto": true,
+    "asan": false,
+    "platform": "windows",
+    "arch": "arm64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
+    "filename": "aarch64-windows-msvc-releasedbg.tar.xz",
+    "sha256": "ad394e79ec85dd40f942671bb0342ffe54a103eb2baabacb773999d57d80134b",
+    "lto": false,
+    "asan": false,
+    "platform": "windows",
+    "arch": "arm64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
     "filename": "arm64-macos-clang-debug-asan.tar.xz",
-    "sha256": "7da4b7d63edefecaf11773e7e701c575140d1a07329bbbb038673b6ee4516ff5",
+    "sha256": "b02d20e4f7294ee33f49a09dfdd765b3b44135e003ef50e3a760aeee39e3f993",
     "lto": false,
     "asan": true,
     "platform": "macosx",
+    "arch": "arm64",
     "build_type": "Debug"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "arm64-macos-clang-releasedbg-lto.tar.xz",
-    "sha256": "300455b169448f9f01ae95e3bc269f489558a4ca3955e3032171cc75feca0e30",
+    "sha256": "e40c21eb0d0b91d9d4ab31212a5cb01ea46707f5c29839414567857e4147604d",
     "lto": true,
     "asan": false,
     "platform": "macosx",
+    "arch": "arm64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "arm64-macos-clang-releasedbg.tar.xz",
-    "sha256": "9abfc6cd65b957d734ffb97610a634fb4a66d3fbe0fcfb5a1c9124ef693c1495",
+    "sha256": "e1b01de34f0edfd41c118e4981a93afb35556ae369597e864f4a393db623b926",
     "lto": false,
     "asan": false,
     "platform": "macosx",
+    "arch": "arm64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "x64-linux-gnu-debug-asan.tar.xz",
-    "sha256": "c1ad3ec476911596a842ac67dd9c9c9475ce9f0a77b81101d3c801840292e7bc",
+    "sha256": "76bb82d822b5377fb5e0fac8abcfba125142e6a0acc02bb36d1fa1532a268646",
     "lto": false,
     "asan": true,
     "platform": "linux",
+    "arch": "x64",
     "build_type": "Debug"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "x64-linux-gnu-releasedbg-lto.tar.xz",
-    "sha256": "8a869c2184d139dbba704e2d712e7a68336458ad2d70622b3eb906c3e3511e54",
+    "sha256": "32f5edddec1e689124f045b586fb402ae30febc05203af7391b088bc8494cd53",
     "lto": true,
     "asan": false,
     "platform": "linux",
+    "arch": "x64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "x64-linux-gnu-releasedbg.tar.xz",
-    "sha256": "552bab86f715d4f2c027f07eaaf5b3d6b8e430af0b74b470142f3f00da4feec6",
+    "sha256": "8ba3c84f23a2a81a86c54780754a61adf99048aa2ac0dc9b9708d0f842d553de",
     "lto": false,
     "asan": false,
     "platform": "linux",
+    "arch": "x64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
-    "filename": "x64-windows-msvc-debug-asan.tar.xz",
-    "sha256": "093667a493d336c22ff3c604c5f1fea2a7d2c927c1179cec44e9a03726906ac1",
-    "lto": false,
-    "asan": true,
-    "platform": "windows",
-    "build_type": "Debug"
+    "version": "21.1.8",
+    "filename": "x64-macos-clang-releasedbg-lto.tar.xz",
+    "sha256": "97e81d6296896d7237f118f728d05291707b9e4e5791e07ce4be8aee0517505d",
+    "lto": true,
+    "asan": false,
+    "platform": "macosx",
+    "arch": "x64",
+    "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
+    "filename": "x64-macos-clang-releasedbg.tar.xz",
+    "sha256": "53c13f8e1082fa2fe2f9c05303de48cb3133bf5f24271f4b3062f1dec578159c",
+    "lto": false,
+    "asan": false,
+    "platform": "macosx",
+    "arch": "x64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
     "filename": "x64-windows-msvc-releasedbg-lto.tar.xz",
-    "sha256": "010539e85621dc3c6ecf359d899feb4075aeca5d0bba6625cdbec0e570e79129",
+    "sha256": "16bcf0e4cbc3d2b1204edd619a3837004dacea28eeff0a101c8d0212f936427d",
     "lto": true,
     "asan": false,
     "platform": "windows",
+    "arch": "x64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "x64-windows-msvc-releasedbg.tar.xz",
-    "sha256": "f473c09fbea10053fac00be409d75dc228d4a38bcbc5e4aeb58b56a4b0dde78e",
+    "sha256": "81d31fad05e200726c8178314b0b2045c947483dddd8cb974f4c376ae5f441fa",
     "lto": false,
     "asan": false,
     "platform": "windows",
+    "arch": "x64",
     "build_type": "RelWithDebInfo"
   }
 ]

pixi.toml

@@ -14,17 +14,24 @@ readme = "README.md"
 documentation = "https://docs.clice.io/clice/"
 repository = "https://github.com/clice-io/clice"
 channels = ["conda-forge"]
-platforms = ["win-64", "linux-64", "osx-arm64"]
+platforms = ["win-64", "linux-64", "osx-arm64", "osx-64", "linux-aarch64", "win-arm64"]
 
 [environments]
 default = ["build", "test"]
 package = ["build", "test", "package"]
+cross-macos-x64 = ["build", "package", "cross-macos-x64"]
+cross-linux-aarch64 = ["build", "package", "cross-linux-aarch64"]
+cross-windows-arm64 = ["build", "package", "cross-windows-arm64"]
 node = ["node"]
 format = ["format"]
+test-run = ["test"]
 
 # ============================================================================== #
 #                                  DEPENDENCIES                                  #
 # ============================================================================== #
+[feature.build]
+platforms = ["win-64", "linux-64", "osx-arm64", "osx-64", "linux-aarch64"]
+
 [feature.build.dependencies]
 python = ">=3.13"
 cmake = ">=3.30"
@@ -35,6 +42,7 @@ lld = "==20.1.8"
 llvm-tools = "==20.1.8"
 clang-tools = "==20.1.8"
 compiler-rt = "==20.1.8"
+flatbuffers = "==25.9.23"
 
 [feature.build.target.win-64.dependencies]
 sccache = "*"
@@ -54,24 +62,69 @@ scripts = ["scripts/activate_linux.sh"]
 [feature.build.target.win-64.activation]
 scripts = ["scripts/activate_asan.bat"]
 
+# macOS x64 (from arm64): clang natively supports cross-arch, no extra deps.
+[feature.cross-macos-x64.target.osx-arm64.dependencies]
+
+[feature.cross-macos-x64.target.osx-arm64.activation]
+scripts = ["scripts/activate_cross_macos.sh"]
+
+# Linux aarch64 (from x64): needs aarch64 sysroot and cross gcc for libstdc++.
+[feature.cross-linux-aarch64.target.linux-64.dependencies]
+sysroot_linux-aarch64 = "==2.17"
+gcc_linux-aarch64 = "==14.2.0"
+gxx_linux-aarch64 = "==14.2.0"
+
+[feature.cross-linux-aarch64.target.linux-64.activation]
+scripts = ["scripts/activate_cross_linux.sh"]
+
+# Windows arm64 (from x64): Windows SDK on CI already includes ARM64 libs.
+[feature.cross-windows-arm64.target.win-64.dependencies]
+
+[feature.cross-windows-arm64.target.win-64.activation]
+scripts = ["scripts/activate_cross_windows.bat"]
+
+[feature.test.dependencies]
+python = ">=3.13"
+
+# On macOS, the system Apple clang emits vendor-specific flags that upstream
+# LLVM cannot parse.  Providing upstream clang + lld in PATH prevents
+# fallback to /usr/bin/clang++ and satisfies toolchain.cmake's -fuse-ld=lld.
+[feature.test.target.osx-64.dependencies]
+clang = "==20.1.8"
+clangxx = "==20.1.8"
+lld = "==20.1.8"
+
+[feature.test.target.osx-arm64.dependencies]
+clang = "==20.1.8"
+clangxx = "==20.1.8"
+lld = "==20.1.8"
+
 [feature.test.pypi-dependencies]
 pytest = "*"
 pytest-asyncio = ">=1.1.0"
+pytest-timeout = "*"
 pygls = ">=2.0.0"
 lsprotocol = ">=2024.0.0"
 
 [feature.package.dependencies]
 xz = ">=5.8.1,<6"
 
-[feature.package.tasks.package]
+[feature.package.tasks.package-config]
+args = [{ arg = "type", default = "RelWithDebInfo" }]
 cmd = """
-cmake -B build/RelWithDebInfo -G Ninja \
-    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+cmake -B build/{{ type }} -G Ninja \
+    -DCMAKE_BUILD_TYPE={{ type }} \
     -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain.cmake \
-    -DCLICE_RELEASE=ON && \
-cmake --build build/RelWithDebInfo
+    -DCLICE_RELEASE=ON
 """
 
+[feature.package.tasks.package]
+args = [{ arg = "type", default = "RelWithDebInfo" }]
+depends-on = [
+    { task = "package-config", args = ["{{ type }}"] },
+    { task = "cmake-build", args = ["{{ type }}"] },
+]
+
 # ============================================================================== #
 #                                   CMAKE                                        #
 # ============================================================================== #
@@ -79,14 +132,13 @@ cmake --build build/RelWithDebInfo
 args = [
     { arg = "type", default = "RelWithDebInfo" },
     { arg = "ci", default = "OFF" },
-    { arg = "extra", default = "" },
 ]
 cmd = """
 cmake -B build/{{ type }} -G Ninja \
     -DCMAKE_BUILD_TYPE={{ type }} \
     -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain.cmake \
     -DCLICE_ENABLE_TEST=ON \
-    -DCLICE_CI_ENVIRONMENT={{ ci }} {{extra}} \
+    -DCLICE_CI_ENVIRONMENT={{ ci }}
 """
 
 [feature.build.tasks.cmake-build]
@@ -97,10 +149,9 @@ cmd = "cmake --build build/{{ type }}"
 args = [
     { arg = "type", default = "RelWithDebInfo" },
     { arg = "ci", default = "OFF" },
-    { arg = "extra", default = "" },
 ]
 depends-on = [
-    { task = "cmake-config", args = ["{{ type }}", "{{ ci }}", "{{extra}}"] },
+    { task = "cmake-config", args = ["{{ type }}", "{{ ci }}"] },
     { task = "cmake-build", args = ["{{ type }}"] },
 ]
 
@@ -108,15 +159,15 @@ depends-on = [
 args = [{ arg = "type", default = "RelWithDebInfo" }]
 depends-on = [{ task = "lint-cpp", args = ["{{ type }}"] }]
 
-[feature.build.tasks.unit-test]
+[feature.test.tasks.unit-test]
 args = [{ arg = "type", default = "RelWithDebInfo" }]
 cmd = './build/{{ type }}/bin/unit_tests --test-dir="./tests/data"'
 
 [feature.test.tasks.integration-test]
 args = [{ arg = "type", default = "RelWithDebInfo" }]
 cmd = """
-pytest -s --log-cli-level=INFO tests/integration \
-    --executable=./build/{{ type }}/bin/clice
+pytest -s --log-cli-level=INFO --timeout=300 --timeout-method=thread \
+    tests/integration --executable=./build/{{ type }}/bin/clice
 """
 
 [feature.test.tasks.smoke-test]
@@ -131,6 +182,7 @@ args = [{ arg = "type", default = "RelWithDebInfo" }]
 depends-on = [
     { task = "unit-test", args = ["{{ type }}"] },
     { task = "integration-test", args = ["{{ type }}"] },
+    { task = "smoke-test", args = ["{{ type }}"] },
 ]
 
 # ============================================================================== #
@@ -152,9 +204,14 @@ gh workflow run upload-llvm.yml \
 args = ["file_name"]
 cmd = ["scripts/delete-artifacts.bash", "{{ file_name }}"]
 
+[dependencies]
+
 # ============================================================================== #
 #                             DOCS & VSCODE EXTENSION                            #
 # ============================================================================== #
+[feature.node]
+platforms = ["win-64", "linux-64", "osx-arm64", "osx-64", "linux-aarch64"]
+
 [feature.node.dependencies]
 nodejs = ">=20"
 pnpm = "*"
@@ -180,6 +237,9 @@ outputs = ["editors/vscode/node_modules/.modules.yaml"]
 # ============================================================================== #
 #                                    FORMAT                                      #
 # ============================================================================== #
+[feature.format]
+platforms = ["win-64", "linux-64", "osx-arm64", "osx-64", "linux-aarch64"]
+
 [feature.format.dependencies]
 ruff = "*"
 tombi = "*"

scripts/activate_cross_linux.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+# Clear conda cross-gcc flags so host x86_64 paths don't leak into the
+# aarch64 build. conda's gcc_linux-aarch64 activation sets
+# CFLAGS/CXXFLAGS/CPPFLAGS/LDFLAGS with -isystem/-L pointing at $CONDA_PREFIX
+# (x86_64 host paths). LIBRARY_PATH from ld_impl_linux-64 likewise points at
+# host libs. Empty-string export reliably overrides conda-installed values
+# regardless of whether pixi sources or calls this script.
+export CFLAGS=
+export CXXFLAGS=
+export CPPFLAGS=
+export LDFLAGS=
+export LIBRARY_PATH=

scripts/activate_cross_macos.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+# Clear conda host flags so arm64 host paths don't leak into the x86_64-macos
+# cross build. See scripts/activate_cross_linux.sh for rationale.
+export CFLAGS=
+export CXXFLAGS=
+export CPPFLAGS=
+export LDFLAGS=
+export LIBRARY_PATH=

scripts/activate_cross_windows.bat

@@ -0,0 +1,8 @@
+@echo off
+REM Clear conda host flags so host x64 paths don't leak into the aarch64-windows
+REM cross build. See scripts/activate_cross_linux.sh for rationale.
+set "CFLAGS="
+set "CXXFLAGS="
+set "CPPFLAGS="
+set "LDFLAGS="
+set "LIBRARY_PATH="

scripts/build-llvm.py

@@ -4,6 +4,7 @@ import subprocess
 import shutil
 import argparse
 import os
+import json
 from pathlib import Path
 
 
@@ -22,6 +23,66 @@ def normalize_mode(value: str) -> str:
     )
 
 
+def build_native_tools(project_root: Path, build_dir: Path) -> Path:
+    """Build native host tablegen tools for cross-compilation.
+
+    When cross-compiling LLVM, build tools like llvm-tblgen must run on the
+    host but would otherwise be compiled for the target architecture.  This
+    function performs a minimal native build and returns the bin directory
+    containing host-runnable executables.
+    """
+    native_dir = build_dir.parent / f"{build_dir.name}-native-tools"
+    native_dir.mkdir(exist_ok=True)
+    source_dir = project_root / "llvm"
+
+    cmake_args = [
+        "-G",
+        "Ninja",
+        "-DCMAKE_BUILD_TYPE=Release",
+        "-DLLVM_ENABLE_PROJECTS=clang;clang-tools-extra",
+        "-DLLVM_TARGETS_TO_BUILD=Native",
+        "-DLLVM_DISABLE_ASSEMBLY_FILES=ON",
+        "-DCMAKE_C_FLAGS=-w",
+        "-DCMAKE_CXX_FLAGS=-w",
+    ]
+
+    if sys.platform == "win32":
+        cmake_args += [
+            "-DCMAKE_C_COMPILER=clang-cl",
+            "-DCMAKE_CXX_COMPILER=clang-cl",
+        ]
+    else:
+        cmake_args += [
+            "-DCMAKE_C_COMPILER=clang",
+            "-DCMAKE_CXX_COMPILER=clang++",
+        ]
+
+    print(f"\nConfiguring native host tools in {native_dir}...")
+    subprocess.check_call(
+        ["cmake", "-S", str(source_dir), "-B", str(native_dir)] + cmake_args
+    )
+
+    required_tools = ["llvm-tblgen", "llvm-min-tblgen", "clang-tblgen"]
+    optional_tools = ["clang-tidy-confusable-chars-gen"]
+
+    for tool in required_tools:
+        print(f"Building native {tool}...")
+        subprocess.check_call(["cmake", "--build", str(native_dir), "--target", tool])
+
+    for tool in optional_tools:
+        try:
+            print(f"Building native {tool} (optional)...")
+            subprocess.check_call(
+                ["cmake", "--build", str(native_dir), "--target", tool]
+            )
+        except subprocess.CalledProcessError:
+            print(f"  {tool} not available, skipping.")
+
+    bin_dir = native_dir / "bin"
+    print(f"Native host tools ready in {bin_dir}")
+    return bin_dir
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="Build LLVM with specific configurations."
@@ -48,6 +109,10 @@ def main():
         "--build-dir",
         help="Custom build directory (relative to project root or absolute)",
     )
+    parser.add_argument(
+        "--target-triple",
+        help="Cross-compilation target triple (e.g. x86_64-apple-darwin, aarch64-linux-gnu, aarch64-pc-windows-msvc)",
+    )
 
     args = parser.parse_args()
 
@@ -85,118 +150,46 @@ def main():
     print("--- Configuration ---")
     print(f"Mode:           {args.mode}")
     print(f"LTO:            {args.lto}")
+    print(f"Target Triple:  {args.target_triple or '(native)'}")
     print(f"Root:           {project_root}")
     print(f"Build Dir:      {build_dir}")
     print(f"Install Prefix: {install_prefix}")
     print(f"Toolchain:      {toolchain_file}")
     print("---------------------")
 
-    llvm_distribution_components = [
-        "LLVMDemangle",
-        "LLVMSupport",
-        "LLVMCore",
-        "LLVMOption",
-        "LLVMBinaryFormat",
-        "LLVMMC",
-        "LLVMMCParser",
-        "LLVMObject",
-        "LLVMProfileData",
-        "LLVMBitReader",
-        "LLVMBitstreamReader",
-        "LLVMRemarks",
-        "LLVMObjectYAML",
-        "LLVMAggressiveInstCombine",
-        "LLVMInstCombine",
-        "LLVMIRReader",
-        "LLVMTextAPI",
-        "LLVMSymbolize",
-        "LLVMDebugInfoDWARF",
-        "LLVMDebugInfoDWARFLowLevel",
-        "LLVMDebugInfoCodeView",
-        "LLVMDebugInfoGSYM",
-        "LLVMDebugInfoPDB",
-        "LLVMDebugInfoBTF",
-        "LLVMDebugInfoMSF",
-        "LLVMAsmParser",
-        "LLVMTargetParser",
-        "LLVMTransformUtils",
-        "LLVMAnalysis",
-        "LLVMScalarOpts",
-        "LLVMFrontendHLSL",
-        "LLVMFrontendOpenMP",
-        "LLVMFrontendOffloading",
-        "LLVMFrontendAtomic",
-        "LLVMFrontendDirective",
-        "LLVMWindowsDriver",
-        "clangIndex",
-        "clangAPINotes",
-        "clangAST",
-        "clangASTMatchers",
-        "clangBasic",
-        "clangDriver",
-        "clangFormat",
-        "clangFrontend",
-        "clangLex",
-        "clangParse",
-        "clangSema",
-        "clangSerialization",
-        "clangRewrite",
-        "clangAnalysis",
-        "clangEdit",
-        "clangSupport",
-        "clangStaticAnalyzerCore",
-        "clangStaticAnalyzerFrontend",
-        "clangTidy",
-        "clangTidyUtils",
-        "clangTidyAndroidModule",
-        "clangTidyAbseilModule",
-        "clangTidyAlteraModule",
-        "clangTidyBoostModule",
-        "clangTidyBugproneModule",
-        "clangTidyCERTModule",
-        "clangTidyConcurrencyModule",
-        "clangTidyCppCoreGuidelinesModule",
-        "clangTidyDarwinModule",
-        "clangTidyFuchsiaModule",
-        "clangTidyGoogleModule",
-        "clangTidyHICPPModule",
-        "clangTidyLinuxKernelModule",
-        "clangTidyLLVMModule",
-        "clangTidyLLVMLibcModule",
-        "clangTidyMiscModule",
-        "clangTidyModernizeModule",
-        "clangTidyObjCModule",
-        "clangTidyOpenMPModule",
-        "clangTidyPerformanceModule",
-        "clangTidyPortabilityModule",
-        "clangTidyReadabilityModule",
-        "clangTidyZirconModule",
-        "clangTooling",
-        "clangToolingCore",
-        "clangToolingInclusions",
-        "clangToolingInclusionsStdlib",
-        "clangToolingSyntax",
-        "clangToolingRefactoring",
-        "clangTransformer",
-        "clangCrossTU",
-        "clangAnalysisFlowSensitive",
-        "clangAnalysisFlowSensitiveModels",
-        "clangStaticAnalyzerCheckers",
-        "clangIncludeCleaner",
-        "llvm-headers",
-        "clang-headers",
-        "clang-tidy-headers",
-        "clang-resource-headers",
-    ]
+    components_path = Path(__file__).resolve().parent / "llvm-components.json"
+    with components_path.open() as f:
+        llvm_distribution_components = json.load(f)["components"]
 
     components_joined = ";".join(llvm_distribution_components)
     cmake_args = [
         "-G",
         "Ninja",
-        f"-DCMAKE_TOOLCHAIN_FILE={toolchain_file.as_posix()}",
         f"-DCMAKE_INSTALL_PREFIX={install_prefix}",
-        "-DCMAKE_C_FLAGS=-w",
-        "-DCMAKE_CXX_FLAGS=-w",
+    ]
+
+    if sys.platform == "win32":
+        # Use clang-cl (MSVC driver) on Windows so that LLVM's CMake
+        # generates correct MSVC-style linker flags for LTO, etc.
+        c_flags = "-w"
+        if args.target_triple:
+            c_flags += f" --target={args.target_triple}"
+        cmake_args += [
+            "-DCMAKE_C_COMPILER=clang-cl",
+            "-DCMAKE_CXX_COMPILER=clang-cl",
+            f"-DCMAKE_C_FLAGS={c_flags}",
+            f"-DCMAKE_CXX_FLAGS={c_flags}",
+            "-DLLVM_USE_LINKER=lld-link",
+        ]
+    else:
+        cmake_args += [
+            f"-DCMAKE_TOOLCHAIN_FILE={toolchain_file.as_posix()}",
+            "-DCMAKE_C_FLAGS=-w",
+            "-DCMAKE_CXX_FLAGS=-w",
+            "-DLLVM_USE_LINKER=lld",
+        ]
+
+    cmake_args += [
         "-DLLVM_ENABLE_ZLIB=OFF",
         "-DLLVM_ENABLE_ZSTD=OFF",
         "-DLLVM_ENABLE_LIBXML2=OFF",
@@ -231,7 +224,6 @@ def main():
         "-DCMAKE_JOB_POOL_LINK=console",
         "-DLLVM_ENABLE_PROJECTS=clang;clang-tools-extra",
         "-DLLVM_TARGETS_TO_BUILD=all",
-        "-DLLVM_USE_LINKER=lld",
         "-DLLVM_DISABLE_ASSEMBLY_FILES=ON",
         # Distribution
         f"-DLLVM_DISTRIBUTION_COMPONENTS={components_joined}",
@@ -256,8 +248,10 @@ def main():
     is_shared = "OFF"
     if args.mode == "Debug":
         cmake_args.append("-DCMAKE_BUILD_TYPE=Debug")
-        cmake_args.append("-DLLVM_USE_SANITIZER=Address")
-        is_shared = "ON"
+        # ASAN is incompatible with -MDd on Windows (clang-cl), skip it there.
+        if sys.platform != "win32":
+            cmake_args.append("-DLLVM_USE_SANITIZER=Address")
+            is_shared = "ON"
     elif args.mode == "Release":
         cmake_args.append("-DCMAKE_BUILD_TYPE=Release")
     elif args.mode == "RelWithDebInfo":
@@ -272,6 +266,24 @@ def main():
     else:
         cmake_args.append("-DLLVM_ENABLE_LTO=OFF")
 
+    if args.target_triple:
+        cmake_args.append(f"-DCLICE_TARGET_TRIPLE={args.target_triple}")
+        cmake_args.append(f"-DLLVM_HOST_TRIPLE={args.target_triple}")
+
+        # When cross-compiling, clear conda's host-platform flags so they
+        # don't leak into the target build (e.g. -L pointing to x86_64 libs).
+        # This must happen before the native-tools build too so we don't
+        # contaminate the native configure with target-arch link flags.
+        for var in ["LIBRARY_PATH", "LDFLAGS", "CFLAGS", "CXXFLAGS", "CPPFLAGS"]:
+            os.environ.pop(var, None)
+
+        # Cross-compilation needs native host tools (tablegen, etc.) that can
+        # run on the build machine.  macOS handles this transparently via
+        # Rosetta 2, but Linux and Windows require a separate native build.
+        if sys.platform != "darwin":
+            native_bin_dir = build_native_tools(project_root, build_dir)
+            cmake_args.append(f"-DLLVM_NATIVE_TOOL_DIR={native_bin_dir}")
+
     build_dir.mkdir(exist_ok=True)
 
     print(f"\nConfiguring in {build_dir}...")

scripts/llvm-components.json

@@ -0,0 +1,99 @@
+{
+  "components": [
+    "LLVMDemangle",
+    "LLVMSupport",
+    "LLVMCore",
+    "LLVMOption",
+    "LLVMBinaryFormat",
+    "LLVMMC",
+    "LLVMMCParser",
+    "LLVMObject",
+    "LLVMProfileData",
+    "LLVMBitReader",
+    "LLVMBitstreamReader",
+    "LLVMRemarks",
+    "LLVMObjectYAML",
+    "LLVMAggressiveInstCombine",
+    "LLVMInstCombine",
+    "LLVMIRReader",
+    "LLVMTextAPI",
+    "LLVMSymbolize",
+    "LLVMDebugInfoDWARF",
+    "LLVMDebugInfoDWARFLowLevel",
+    "LLVMDebugInfoCodeView",
+    "LLVMDebugInfoGSYM",
+    "LLVMDebugInfoPDB",
+    "LLVMDebugInfoBTF",
+    "LLVMDebugInfoMSF",
+    "LLVMAsmParser",
+    "LLVMTargetParser",
+    "LLVMTransformUtils",
+    "LLVMAnalysis",
+    "LLVMScalarOpts",
+    "LLVMFrontendHLSL",
+    "LLVMFrontendOpenMP",
+    "LLVMFrontendOffloading",
+    "LLVMFrontendAtomic",
+    "LLVMFrontendDirective",
+    "LLVMWindowsDriver",
+    "clangIndex",
+    "clangAPINotes",
+    "clangAST",
+    "clangASTMatchers",
+    "clangBasic",
+    "clangDriver",
+    "clangFormat",
+    "clangFrontend",
+    "clangLex",
+    "clangParse",
+    "clangSema",
+    "clangSerialization",
+    "clangRewrite",
+    "clangAnalysis",
+    "clangEdit",
+    "clangSupport",
+    "clangStaticAnalyzerCore",
+    "clangStaticAnalyzerFrontend",
+    "clangTidy",
+    "clangTidyUtils",
+    "clangTidyAndroidModule",
+    "clangTidyAbseilModule",
+    "clangTidyAlteraModule",
+    "clangTidyBoostModule",
+    "clangTidyBugproneModule",
+    "clangTidyCERTModule",
+    "clangTidyConcurrencyModule",
+    "clangTidyCppCoreGuidelinesModule",
+    "clangTidyDarwinModule",
+    "clangTidyFuchsiaModule",
+    "clangTidyGoogleModule",
+    "clangTidyHICPPModule",
+    "clangTidyLinuxKernelModule",
+    "clangTidyLLVMModule",
+    "clangTidyLLVMLibcModule",
+    "clangTidyMiscModule",
+    "clangTidyModernizeModule",
+    "clangTidyObjCModule",
+    "clangTidyOpenMPModule",
+    "clangTidyPerformanceModule",
+    "clangTidyPortabilityModule",
+    "clangTidyReadabilityModule",
+    "clangTidyZirconModule",
+    "clangTooling",
+    "clangToolingCore",
+    "clangToolingInclusions",
+    "clangToolingInclusionsStdlib",
+    "clangToolingSyntax",
+    "clangToolingRefactoring",
+    "clangTransformer",
+    "clangCrossTU",
+    "clangAnalysisFlowSensitive",
+    "clangAnalysisFlowSensitiveModels",
+    "clangStaticAnalyzerCheckers",
+    "clangIncludeCleaner",
+    "llvm-headers",
+    "clang-headers",
+    "clang-tidy-headers",
+    "clang-resource-headers"
+  ]
+}

scripts/setup-llvm.py

@@ -40,23 +40,52 @@ def detect_platform() -> str:
     raise RuntimeError(f"Unsupported platform: {plat}")
 
 
+def detect_arch() -> str:
+    import platform
+
+    machine = platform.machine().lower()
+    if machine in ("x86_64", "amd64"):
+        return "x64"
+    if machine in ("aarch64", "arm64"):
+        return "arm64"
+    raise RuntimeError(f"Unsupported architecture: {machine}")
+
+
 def pick_artifact(
-    manifest: list[dict], version: str, build_type: str, is_lto: bool, platform: str
+    manifest: list[dict],
+    version: str,
+    build_type: str,
+    is_lto: bool,
+    platform: str,
+    arch: str,
 ) -> dict:
     base_version = version.split("+", 1)[0]
+    saw_missing_arch = False
     for entry in manifest:
         if entry.get("version") != version:
             continue
         if entry.get("platform") != platform.lower():
             continue
+        entry_arch = entry.get("arch")
+        if entry_arch is None:
+            saw_missing_arch = True
+            continue
+        if entry_arch != arch:
+            continue
         if entry.get("build_type") != build_type:
             continue
         if bool(entry.get("lto")) != is_lto:
             continue
         return entry
+    if saw_missing_arch:
+        raise RuntimeError(
+            f"Manifest contains entries without an 'arch' field for version={base_version}, "
+            f"platform={platform}. The manifest format changed to require explicit "
+            f"architectures; regenerate it via scripts/update-llvm-version.py."
+        )
     raise RuntimeError(
         f"No matching LLVM artifact in manifest for version={base_version}, platform={platform}, "
-        f"build_type={build_type}, lto={is_lto}"
+        f"arch={arch}, build_type={build_type}, lto={is_lto}"
     )
 
 
@@ -264,6 +293,14 @@ def main() -> None:
     parser.add_argument("--install-path")
     parser.add_argument("--enable-lto", action="store_true")
     parser.add_argument("--offline", action="store_true")
+    parser.add_argument(
+        "--target-platform",
+        help="Override platform for cross-compilation (e.g. macosx, linux, windows)",
+    )
+    parser.add_argument(
+        "--target-arch",
+        help="Override architecture for cross-compilation (e.g. x64, arm64)",
+    )
     parser.add_argument("--output", required=True)
     args = parser.parse_args()
 
@@ -275,8 +312,11 @@ def main() -> None:
     )
     token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
     build_type = args.build_type
-    platform_name = detect_platform()
-    log(f"Platform detected: {platform_name}, normalized build type: {build_type}")
+    platform_name = args.target_platform if args.target_platform else detect_platform()
+    arch_name = args.target_arch if args.target_arch else detect_arch()
+    log(
+        f"Platform: {platform_name}, arch: {arch_name}, normalized build type: {build_type}"
+    )
     manifest = read_manifest(Path(args.manifest))
 
     binary_dir = Path(args.binary_dir).resolve()
@@ -304,7 +344,12 @@ def main() -> None:
     if install_path is None:
         needs_install = True
         artifact = pick_artifact(
-            manifest, args.version, build_type, args.enable_lto, platform_name
+            manifest,
+            args.version,
+            build_type,
+            args.enable_lto,
+            platform_name,
+            arch_name,
         )
         log(f"Selected artifact: {artifact.get('filename')} for download")
         filename = artifact["filename"]
@@ -317,7 +362,12 @@ def main() -> None:
         install_path = install_root
     elif needs_install:
         artifact = pick_artifact(
-            manifest, args.version, build_type, args.enable_lto, platform_name
+            manifest,
+            args.version,
+            build_type,
+            args.enable_lto,
+            platform_name,
+            arch_name,
         )
         log(f"Selected artifact: {artifact.get('filename')} for download")
         filename = artifact["filename"]

scripts/update-llvm-version.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def copy_manifest(src: Path, dest: Path) -> None:
+    text = src.read_text(encoding="utf-8")
+
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as err:
+        print(f"Error: {src} is not valid JSON: {err}", file=sys.stderr)
+        sys.exit(1)
+
+    if not isinstance(data, list) or len(data) == 0:
+        print(f"Error: {src} must be a non-empty JSON array", file=sys.stderr)
+        sys.exit(1)
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with dest.open("w", encoding="utf-8") as handle:
+        json.dump(data, handle, indent=2)
+        handle.write("\n")
+
+    print(f"Copied manifest: {src} -> {dest} ({len(data)} entries)")
+
+
+def update_package_cmake(path: Path, version: str) -> None:
+    text = path.read_text(encoding="utf-8")
+
+    pattern = r'setup_llvm\("[^"]*"\)'
+    matches = re.findall(pattern, text)
+
+    if len(matches) == 0:
+        print(f"Error: no setup_llvm(...) call found in {path}", file=sys.stderr)
+        sys.exit(1)
+
+    if len(matches) > 1:
+        print(
+            f"Error: expected exactly 1 setup_llvm(...) call in {path}, "
+            f"found {len(matches)}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    old_call = matches[0]
+    new_call = f'setup_llvm("{version}")'
+
+    if old_call == new_call:
+        print(f"Version in {path} is already {version}, no change needed")
+        return
+
+    updated = text.replace(old_call, new_call)
+    path.write_text(updated, encoding="utf-8")
+    print(f"Updated {path}: {old_call} -> {new_call}")
+
+
+def check_package_cmake(path: Path) -> None:
+    """Verify package.cmake has exactly one setup_llvm(...) call that the
+    update script can rewrite. Used by CI to catch drift before the next bump."""
+    text = path.read_text(encoding="utf-8")
+    matches = re.findall(r'setup_llvm\("[^"]*"\)', text)
+    if len(matches) == 0:
+        print(f"Error: no setup_llvm(...) call found in {path}", file=sys.stderr)
+        sys.exit(1)
+    if len(matches) > 1:
+        print(
+            f"Error: expected exactly 1 setup_llvm(...) call in {path}, "
+            f"found {len(matches)}: {matches}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    print(f"OK: {path} has a single setup_llvm(...) call: {matches[0]}")
+
+
+def check_manifest(path: Path) -> None:
+    """Verify the manifest is a well-formed non-empty array with required fields."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as err:
+        print(f"Error: {path} is not valid JSON: {err}", file=sys.stderr)
+        sys.exit(1)
+    if not isinstance(data, list) or len(data) == 0:
+        print(f"Error: {path} must be a non-empty JSON array", file=sys.stderr)
+        sys.exit(1)
+    required = ("version", "platform", "arch", "build_type", "filename", "sha256")
+    for idx, entry in enumerate(data):
+        missing = [k for k in required if k not in entry]
+        if missing:
+            print(
+                f"Error: {path} entry {idx} is missing fields: {missing}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+    print(f"OK: {path} has {len(data)} well-formed entries")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Update LLVM version references in the clice project."
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Validate existing state without modifying files (for CI drift checks)",
+    )
+    parser.add_argument(
+        "--version",
+        help="New LLVM version string (e.g. 21.2.0); required unless --check",
+    )
+    parser.add_argument(
+        "--manifest-src",
+        help="Path to the source llvm-manifest.json; required unless --check",
+    )
+    parser.add_argument(
+        "--manifest-dest",
+        required=True,
+        help="Path to destination manifest (e.g. config/llvm-manifest.json)",
+    )
+    parser.add_argument(
+        "--package-cmake",
+        required=True,
+        help="Path to cmake/package.cmake",
+    )
+    args = parser.parse_args()
+
+    manifest_dest = Path(args.manifest_dest)
+    package_cmake = Path(args.package_cmake)
+
+    if not package_cmake.is_file():
+        print(f"Error: package.cmake not found: {package_cmake}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.check:
+        check_package_cmake(package_cmake)
+        check_manifest(manifest_dest)
+        print("Done (check mode).")
+        return
+
+    if not args.version or not args.manifest_src:
+        print(
+            "Error: --version and --manifest-src are required unless --check is set",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    manifest_src = Path(args.manifest_src)
+    if not manifest_src.is_file():
+        print(f"Error: manifest source not found: {manifest_src}", file=sys.stderr)
+        sys.exit(1)
+
+    copy_manifest(manifest_src, manifest_dest)
+    update_package_cmake(package_cmake, args.version)
+
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()

scripts/upload-llvm.py

@@ -27,6 +27,15 @@ def parse_platform(name: str) -> str:
     raise ValueError(f"Unable to determine platform from filename: {name}")
 
 
+def parse_arch(name: str) -> str:
+    lowered = name.lower()
+    if lowered.startswith("aarch64-") or lowered.startswith("arm64-"):
+        return "arm64"
+    if lowered.startswith("x64-") or lowered.startswith("x86_64-"):
+        return "x64"
+    raise ValueError(f"Unable to determine arch from filename: {name}")
+
+
 def parse_build_type(name: str) -> str:
     lowered = name.lower()
     if "debug" in lowered:
@@ -43,6 +52,7 @@ def build_metadata_entry(path: Path, version: str) -> dict:
         "lto": "-lto" in filename.lower(),
         "asan": "-asan" in filename.lower(),
         "platform": parse_platform(filename),
+        "arch": parse_arch(filename),
         "build_type": parse_build_type(filename),
     }
 

scripts/validate-llvm-components.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+Validate the LLVM distribution component list against the actual LLVM source tree.
+
+Scans the LLVM source for CMake library targets and compares them against
+a components JSON file to detect stale or misspelled entries.
+"""
+
+import argparse
+import difflib
+import json
+import re
+import sys
+from pathlib import Path
+
+
+# CMake function calls that define library targets.
+# The captured group uses [^\s)]+  to grab the target name without
+# trailing parentheses or whitespace.
+LLVM_LIB_PATTERNS = [
+    re.compile(r"add_llvm_component_library\(\s*([^\s)]+)"),
+    re.compile(r"add_llvm_library\(\s*([^\s)]+)"),
+]
+
+CLANG_LIB_PATTERNS = [
+    re.compile(r"add_clang_library\(\s*([^\s)]+)"),
+]
+
+# Header-only / custom install targets.
+HEADER_PATTERNS = [
+    re.compile(r"add_llvm_install_targets\(\s*([^\s)]+)"),
+    re.compile(r"add_custom_target\(\s*([^\s)]+)"),
+    re.compile(r"add_library\(\s*([^\s)]+)"),
+]
+
+# Targets we recognise as header-only distribution components.
+KNOWN_HEADER_TARGETS = {
+    "llvm-headers",
+    "clang-headers",
+    "clang-tidy-headers",
+    "clang-resource-headers",
+}
+
+
+def scan_targets(directory: Path, patterns: list[re.Pattern]) -> set[str]:
+    """Recursively scan *directory* for CMakeLists.txt files and extract target names."""
+    targets: set[str] = set()
+    if not directory.is_dir():
+        return targets
+    for cmake_file in directory.rglob("CMakeLists.txt"):
+        text = cmake_file.read_text(errors="replace")
+        for pattern in patterns:
+            for match in pattern.finditer(text):
+                targets.add(match.group(1))
+    return targets
+
+
+def scan_header_targets(llvm_src: Path) -> set[str]:
+    """Scan for well-known header / custom-install targets across the tree."""
+    found: set[str] = set()
+    for cmake_file in llvm_src.rglob("CMakeLists.txt"):
+        text = cmake_file.read_text(errors="replace")
+        for pattern in HEADER_PATTERNS:
+            for match in pattern.finditer(text):
+                name = match.group(1)
+                if name in KNOWN_HEADER_TARGETS:
+                    found.add(name)
+    return found
+
+
+def collect_source_targets(llvm_src: Path) -> set[str]:
+    """Return the full set of library / header targets found in the LLVM source tree."""
+    targets: set[str] = set()
+    targets |= scan_targets(llvm_src / "llvm" / "lib", LLVM_LIB_PATTERNS)
+    targets |= scan_targets(llvm_src / "clang" / "lib", CLANG_LIB_PATTERNS)
+    targets |= scan_targets(llvm_src / "clang-tools-extra", CLANG_LIB_PATTERNS)
+    targets |= scan_header_targets(llvm_src)
+    return targets
+
+
+def load_components(path: Path) -> list[str]:
+    with path.open("r", encoding="utf-8") as handle:
+        data = json.load(handle)
+    if isinstance(data, dict):
+        data = data.get("components", [])
+    if not isinstance(data, list) or not data:
+        print(f"Error: no component list found in {path}", file=sys.stderr)
+        sys.exit(1)
+    return data
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Validate LLVM distribution components against the source tree."
+    )
+    parser.add_argument(
+        "--llvm-src",
+        required=True,
+        help="Path to the llvm-project source root",
+    )
+    parser.add_argument(
+        "--components-file",
+        required=True,
+        help="Path to llvm-components.json",
+    )
+    args = parser.parse_args()
+
+    llvm_src = Path(args.llvm_src).expanduser().resolve()
+    components_file = Path(args.components_file).expanduser().resolve()
+
+    if not llvm_src.is_dir():
+        print(f"Error: LLVM source directory not found: {llvm_src}")
+        sys.exit(1)
+
+    if not (llvm_src / "llvm" / "CMakeLists.txt").exists():
+        print(f"Error: {llvm_src} does not look like an llvm-project root.")
+        sys.exit(1)
+
+    if not components_file.is_file():
+        print(f"Error: components file not found: {components_file}")
+        sys.exit(1)
+
+    components = load_components(components_file)
+    source_targets = collect_source_targets(llvm_src)
+
+    print(f"Found {len(source_targets)} targets in LLVM source tree")
+    print(f"Components file lists {len(components)} entries")
+
+    # Check for components that are missing from the source tree.
+    missing: list[tuple[str, list[str]]] = []
+    for name in components:
+        if name not in source_targets:
+            suggestions = difflib.get_close_matches(
+                name, source_targets, n=3, cutoff=0.6
+            )
+            missing.append((name, suggestions))
+
+    if missing:
+        print(f"\nError: {len(missing)} component(s) not found in the source tree:\n")
+        for name, suggestions in missing:
+            print(f"  - {name}")
+            if suggestions:
+                print(f"    Did you mean: {', '.join(suggestions)}?")
+        sys.exit(1)
+
+    # Warn about source targets not present in the component list.
+    component_set = set(components)
+    new_targets = sorted(source_targets - component_set - KNOWN_HEADER_TARGETS)
+    # Filter to targets that follow LLVM/Clang naming conventions to reduce noise.
+    noteworthy = [t for t in new_targets if t.startswith(("LLVM", "clang", "Clang"))]
+    if noteworthy:
+        print(
+            f"\nWarning: {len(noteworthy)} target(s) in source not listed in components:"
+        )
+        for name in noteworthy:
+            print(f"  + {name}")
+
+    print("\nAll components validated successfully.")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

src/compile/compilation.cpp

@@ -219,9 +219,10 @@ public:
 
     auto CreateASTConsumer(clang::CompilerInstance& instance, llvm::StringRef file)
         -> std::unique_ptr<clang::ASTConsumer> final {
-        return std::make_unique<ProxyASTConsumer>(
-            WrapperFrontendAction::CreateASTConsumer(instance, file),
-            unit);
+        auto consumer = WrapperFrontendAction::CreateASTConsumer(instance, file);
+        if(!consumer)
+            return nullptr;
+        return std::make_unique<ProxyASTConsumer>(std::move(consumer), unit);
     }
 
     /// Make this public.
@@ -241,6 +242,7 @@ CompilationStatus CompilationUnitRef::Self::run_clang(
     std::unique_ptr diagnostic_consumer = self.create_diagnostic();
     std::unique_ptr invocation = self.create_invocation(params, diagnostic_consumer.get());
     if(!invocation) {
+        LOG_WARN("run_clang: invocation creation failed");
         return CompilationStatus::SetupFail;
     }
 
@@ -255,6 +257,7 @@ CompilationStatus CompilationUnitRef::Self::run_clang(
     }
 
     if(!instance.createTarget()) {
+        LOG_WARN("run_clang: target creation failed");
         return CompilationStatus::SetupFail;
     }
 
@@ -269,6 +272,7 @@ CompilationStatus CompilationUnitRef::Self::run_clang(
         /// But if we fail to `BeginSourceFile` we don't need to call `EndSourceFile`. So just
         /// reset it.
         self.action.reset();
+        LOG_WARN("run_clang: BeginSourceFile failed");
         return CompilationStatus::SetupFail;
     }
 
@@ -302,6 +306,8 @@ CompilationStatus CompilationUnitRef::Self::run_clang(
     /// in crash frequently. So forbidden it here and return as error.
     if(!instance.getFrontendOpts().OutputFile.empty() &&
        instance.getDiagnostics().hasErrorOccurred()) {
+        LOG_WARN("run_clang: errors during PCH/PCM generation, output={}",
+                 instance.getFrontendOpts().OutputFile);
         return CompilationStatus::FatalError;
     }
 

src/compile/compilation_unit.cpp

@@ -81,7 +81,8 @@ auto CompilationUnitRef::file_offset(clang::SourceLocation location) -> std::uin
 }
 
 auto CompilationUnitRef::file_path(clang::FileID fid) -> llvm::StringRef {
-    assert(fid.isValid() && "Invalid fid");
+    if(!fid.isValid())
+        return {};
     if(auto it = self->path_cache.find(fid); it != self->path_cache.end()) {
         return it->second;
     }

src/feature/code_completion.cpp

@@ -158,28 +158,12 @@ auto extract_signature(const clang::CodeCompletionString& ccs) -> std::string {
     return signature;
 }
 
-/// Find the first non-whitespace character after the given offset in content.
-/// Returns '\0' if none found (end of content).
-auto next_token_char(llvm::StringRef content, std::uint32_t offset) -> char {
-    for(auto i = offset; i < content.size(); ++i) {
-        char c = content[i];
-        if(c != ' ' && c != '\t' && c != '\n' && c != '\r') {
-            return c;
-        }
-    }
-    return '\0';
-}
-
 /// Build a snippet string from a CodeCompletionString.
 /// Produces e.g. "funcName(${1:int x}, ${2:float y})" for functions,
 /// or "ClassName<${1:T}>" for class templates.
-/// If skip_parens is true, omits everything from '(' onward (when the next
-/// token after the cursor is already '(').
-auto build_snippet(const clang::CodeCompletionString& ccs, bool skip_parens = false)
-    -> std::string {
+auto build_snippet(const clang::CodeCompletionString& ccs) -> std::string {
     std::string snippet;
     unsigned placeholder_index = 0;
-    bool in_parens = false;
 
     for(const auto& chunk: ccs) {
         using CK = clang::CodeCompletionString::ChunkKind;
@@ -190,47 +174,33 @@ auto build_snippet(const clang::CodeCompletionString& ccs, bool skip_parens = fa
                 }
                 break;
             case CK::CK_Placeholder:
-                if(in_parens && skip_parens) {
-                    break;
-                }
                 if(chunk.Text) {
                     snippet += std::format("${{{0}:{1}}}", ++placeholder_index, chunk.Text);
                 }
                 break;
-            case CK::CK_LeftParen:
-                in_parens = true;
-                if(!skip_parens) {
-                    snippet += '(';
-                }
-                break;
-            case CK::CK_RightParen:
-                in_parens = false;
-                if(!skip_parens) {
-                    snippet += ')';
-                }
-                break;
+            case CK::CK_LeftParen: snippet += '('; break;
+            case CK::CK_RightParen: snippet += ')'; break;
             case CK::CK_LeftAngle: snippet += '<'; break;
             case CK::CK_RightAngle: snippet += '>'; break;
-            case CK::CK_Comma:
-                if(!(in_parens && skip_parens)) {
-                    snippet += ", ";
-                }
-                break;
+            case CK::CK_Comma: snippet += ", "; break;
             case CK::CK_Text:
-                if(!(in_parens && skip_parens) && chunk.Text) {
+                if(chunk.Text) {
                     snippet += chunk.Text;
                 }
                 break;
-            case CK::CK_Optional: break;
+            case CK::CK_Optional:
+                // Optional chunks contain default arguments — skip for snippet.
+                break;
             case CK::CK_Informative:
             case CK::CK_ResultType:
-            case CK::CK_CurrentParameter: break;
+            case CK::CK_CurrentParameter:
+                // Display-only chunks, not part of insertion.
+                break;
             default: break;
         }
     }
 
-    // If no placeholders were generated and parens were skipped,
-    // return empty to signal plain text.
+    // If no placeholders were generated, return empty to signal plain text.
     if(placeholder_index == 0) {
         return {};
     }
@@ -259,11 +229,9 @@ public:
     CodeCompletionCollector(std::uint32_t offset,
                             PositionEncoding encoding,
                             std::vector<protocol::CompletionItem>& output,
-                            const CodeCompletionOptions& options,
-                            llvm::StringRef original_content) :
+                            const CodeCompletionOptions& options) :
         clang::CodeCompleteConsumer({}), offset(offset), encoding(encoding), output(output),
-        options(options), original_content(original_content),
-        info(std::make_shared<clang::GlobalCodeCompletionAllocator>()) {}
+        options(options), info(std::make_shared<clang::GlobalCodeCompletionAllocator>()) {}
 
     clang::CodeCompletionAllocator& getAllocator() final {
         return info.getAllocator();
@@ -328,7 +296,8 @@ public:
                            llvm::StringRef overload_key,
                            llvm::StringRef signature = {},
                            llvm::StringRef return_type = {},
-                           bool is_snippet = false) {
+                           bool is_snippet = false,
+                           bool is_deprecated = false) {
             if(label.empty()) {
                 return;
             }
@@ -359,6 +328,9 @@ public:
                         }
                         item.label_details = std::move(details);
                     }
+                    if(is_deprecated) {
+                        item.tags = std::vector{protocol::CompletionItemTag::Deprecated};
+                    }
                     overloads.push_back({
                         .item = std::move(item),
                         .score = *score,
@@ -387,6 +359,9 @@ public:
                 }
                 item.label_details = std::move(details);
             }
+            if(is_deprecated) {
+                item.tags = std::vector{protocol::CompletionItemTag::Deprecated};
+            }
             collected.push_back(std::move(item));
         };
 
@@ -457,20 +432,21 @@ public:
                         // Generate snippet for non-bundled callables.
                         if(is_callable && !options.bundle_overloads &&
                            options.enable_function_arguments_snippet) {
-                            bool next_is_paren = next_token_char(original_content, offset) == '(';
-                            snippet = build_snippet(*ccs, /*skip_parens=*/next_is_paren);
+                            snippet = build_snippet(*ccs);
                         }
                     }
 
                     bool has_snippet = !snippet.empty();
                     auto insert = has_snippet ? llvm::StringRef(snippet) : llvm::StringRef(label);
+                    bool deprecated = candidate.Availability == CXAvailability_Deprecated;
                     try_add(label,
                             kind,
                             insert,
                             qualified_name.str(),
                             signature,
                             return_type,
-                            has_snippet);
+                            has_snippet,
+                            deprecated);
                     break;
                 }
             }
@@ -528,7 +504,6 @@ private:
     std::uint32_t offset;
     PositionEncoding encoding;
     std::vector<protocol::CompletionItem>& output;
-    llvm::StringRef original_content;
     const CodeCompletionOptions& options;
     clang::CodeCompletionTUInfo info;
 };
@@ -543,15 +518,7 @@ auto code_complete(CompilationParams& params,
     auto& [file, offset] = params.completion;
     (void)file;
 
-    // Get the original file content for lookahead (smart parens detection).
-    llvm::StringRef original_content;
-    auto buf_it = params.buffers.find(file);
-    if(buf_it != params.buffers.end()) {
-        original_content = buf_it->second->getBuffer();
-    }
-
-    auto* consumer =
-        new CodeCompletionCollector(offset, encoding, items, options, original_content);
+    auto* consumer = new CodeCompletionCollector(offset, encoding, items, options);
     auto unit = complete(params, consumer);
     (void)unit;
 

src/semantic/ast_utility.cpp

@@ -308,6 +308,10 @@ const clang::NamedDecl* decl_of_impl(const void* T) {
 }
 
 auto decl_of(clang::QualType type) -> const clang::NamedDecl* {
+    if(type.isNull()) {
+        return nullptr;
+    }
+
     // Strip type-sugar that wraps the underlying type without adding a decl
     // (e.g. ElaboratedType for "struct Foo" vs plain "Foo").
     if(auto ET = type->getAs<clang::ElaboratedType>()) {

src/server/compiler.cpp

@@ -47,8 +47,13 @@ void Compiler::init_compile_graph() {
     // Lazy dependency resolver: scans a module file on demand to discover imports.
     auto resolve = [this](std::uint32_t path_id) -> llvm::SmallVector<std::uint32_t> {
         auto file_path = workspace.path_pool.resolve(path_id);
-        auto results =
-            workspace.cdb.lookup(file_path, {.query_toolchain = true, .suppress_logging = true});
+        std::vector<std::string> rule_append, rule_remove;
+        workspace.config.match_rules(file_path, rule_append, rule_remove);
+        auto results = workspace.cdb.lookup(file_path,
+                                            {.query_toolchain = true,
+                                             .suppress_logging = true,
+                                             .remove = rule_remove,
+                                             .append = rule_append});
         if(results.empty())
             return {};
 
@@ -97,7 +102,8 @@ void Compiler::init_compile_graph() {
         }
         auto args_hash = llvm::xxh3_64bits(llvm::StringRef(hash_input));
         auto pcm_filename = std::format("{}-{:016x}.pcm", safe_module_name, args_hash);
-        auto pcm_path = path::join(workspace.config.cache_dir, "cache", "pcm", pcm_filename);
+        auto pcm_path =
+            path::join(workspace.config.project.cache_dir, "cache", "pcm", pcm_filename);
 
         // Check if cached PCM is still valid.
         if(auto pcm_it = workspace.pcm_cache.find(path_id); pcm_it != workspace.pcm_cache.end()) {
@@ -116,9 +122,11 @@ void Compiler::init_compile_graph() {
 
         auto result = co_await pool.send_stateless(bp);
         if(!result.has_value() || !result.value().success) {
-            LOG_WARN("BuildPCM failed for module {}: {}",
-                     mod_it->second,
-                     result.has_value() ? result.value().error : result.error().message);
+            auto error_msg = result.has_value() ? result.value().error : result.error().message;
+            LOG_WARN("BuildPCM failed for module {}: {}", mod_it->second, error_msg);
+            peer.send_notification(protocol::LogMessageParams{
+                protocol::MessageType::Warning,
+                std::format("PCM build failed for module {}: {}", mod_it->second, error_msg)});
             co_return false;
         }
 
@@ -156,11 +164,19 @@ bool Compiler::fill_compile_args(llvm::StringRef path,
     }
 
     // 2. Normal CDB lookup for the file itself.
-    auto results = workspace.cdb.lookup(path, {.query_toolchain = true});
+    //    Apply rules from config (append/remove flags based on file patterns).
+    std::vector<std::string> rule_append, rule_remove;
+    workspace.config.match_rules(path, rule_append, rule_remove);
+    CommandOptions opts{.query_toolchain = true, .remove = rule_remove, .append = rule_append};
+    auto results = workspace.cdb.lookup(path, opts);
     if(!results.empty()) {
         auto& cmd = results.front();
         directory = cmd.resolved.directory.str();
         arguments = cmd.to_string_argv();
+        LOG_DEBUG("fill_compile_args: CDB match for {} (dir={}, {} args)",
+                  path,
+                  directory,
+                  arguments.size());
         return true;
     }
 
@@ -205,7 +221,13 @@ bool Compiler::fill_header_context_args(llvm::StringRef path,
     }
 
     auto host_path = workspace.path_pool.resolve(ctx_ptr->host_path_id);
-    auto host_results = workspace.cdb.lookup(host_path, {.query_toolchain = true});
+    // Apply rules matching the HEADER path (what the user is editing) on top of
+    // the host's command — rules are expected to apply uniformly to every file.
+    std::vector<std::string> rule_append, rule_remove;
+    workspace.config.match_rules(path, rule_append, rule_remove);
+    auto host_results = workspace.cdb.lookup(
+        host_path,
+        {.query_toolchain = true, .remove = rule_remove, .append = rule_append});
     if(host_results.empty()) {
         LOG_WARN("fill_header_context_args: host {} has no CDB entry", host_path);
         return false;
@@ -355,7 +377,7 @@ std::optional<HeaderFileContext> Compiler::resolve_header_context(std::uint32_t
     // Hash the preamble and write to cache directory.
     auto preamble_hash = llvm::xxh3_64bits(llvm::StringRef(preamble));
     auto preamble_filename = std::format("{:016x}.h", preamble_hash);
-    auto preamble_dir = path::join(workspace.config.cache_dir, "header_context");
+    auto preamble_dir = path::join(workspace.config.project.cache_dir, "header_context");
     auto preamble_path = path::join(preamble_dir, preamble_filename);
 
     if(!llvm::sys::fs::exists(preamble_path)) {
@@ -438,7 +460,7 @@ kota::task<bool> Compiler::ensure_pch(Session& session,
     auto preamble_hash = llvm::xxh3_64bits(preamble_text);
 
     // Deterministic content-addressed PCH path.
-    auto pch_path = path::join(workspace.config.cache_dir,
+    auto pch_path = path::join(workspace.config.project.cache_dir,
                                "cache",
                                "pch",
                                std::format("{:016x}.pch", preamble_hash));
@@ -474,6 +496,22 @@ kota::task<bool> Compiler::ensure_pch(Session& session,
     auto completion = std::make_shared<kota::event>();
     workspace.pch_cache[path_id].building = completion;
 
+    if(workspace.config.project.cache_dir.empty()) {
+        LOG_WARN("PCH build skipped: cache_dir is not configured");
+        workspace.pch_cache[path_id].building.reset();
+        completion->set();
+        co_return false;
+    }
+
+    // Ensure the PCH cache directory exists.
+    auto pch_dir = path::join(workspace.config.project.cache_dir, "cache", "pch");
+    if(auto ec = llvm::sys::fs::create_directories(pch_dir)) {
+        LOG_WARN("Cannot create PCH cache dir {}: {}", pch_dir, ec.message());
+        workspace.pch_cache[path_id].building.reset();
+        completion->set();
+        co_return false;
+    }
+
     // Build a new PCH via stateless worker.
     worker::BuildParams bp;
     bp.kind = worker::BuildKind::BuildPCH;
@@ -489,9 +527,11 @@ kota::task<bool> Compiler::ensure_pch(Session& session,
     auto result = co_await pool.send_stateless(bp);
 
     if(!result.has_value() || !result.value().success) {
-        LOG_WARN("PCH build failed for {}: {}",
-                 path,
-                 result.has_value() ? result.value().error : result.error().message);
+        auto error_msg = result.has_value() ? result.value().error : result.error().message;
+        LOG_WARN("PCH build failed for {}: {}", path, error_msg);
+        peer.send_notification(protocol::LogMessageParams{
+            protocol::MessageType::Warning,
+            std::format("PCH build failed for {}: {}", path, error_msg)});
         workspace.pch_cache[path_id].building.reset();
         completion->set();
         co_return false;
@@ -698,6 +738,10 @@ kota::task<bool> Compiler::ensure_compiled(Session& session) {
         params.version = sess->version;
         params.text = sess->text;
         if(!self->fill_compile_args(file_path, params.directory, params.arguments, sess)) {
+            LOG_WARN("ensure_compiled: no compile args for {}", uri_str);
+            self->peer.send_notification(protocol::LogMessageParams{
+                protocol::MessageType::Warning,
+                std::format("No compile arguments available for {}", file_path)});
             finish_compile();
             co_return;
         }
@@ -705,6 +749,9 @@ kota::task<bool> Compiler::ensure_compiled(Session& session) {
         if(!co_await self
                 ->ensure_deps(*sess, params.directory, params.arguments, params.pch, params.pcms)) {
             LOG_WARN("Dependency preparation failed for {}, skipping compile", uri_str);
+            self->peer.send_notification(protocol::LogMessageParams{
+                protocol::MessageType::Warning,
+                std::format("Dependency preparation failed for {}", file_path)});
             finish_compile();
             co_return;
         }
@@ -736,6 +783,9 @@ kota::task<bool> Compiler::ensure_compiled(Session& session) {
 
         if(!result.has_value()) {
             LOG_WARN("Compile failed for {}: {}", uri_str, result.error().message);
+            self->peer.send_notification(protocol::LogMessageParams{
+                protocol::MessageType::Error,
+                std::format("Compilation failed for {}: {}", file_path, result.error().message)});
             self->clear_diagnostics(uri_str);
             finish_compile();
             co_return;
@@ -784,11 +834,17 @@ Compiler::RawResult Compiler::forward_query(worker::QueryKind kind,
     auto text = session.text;
 
     if(!co_await ensure_compiled(session)) {
-        co_return serde_raw{"null"};
+        LOG_WARN("forward_query: compilation failed for {}", path);
+        co_await kota::fail("Compilation failed");
     }
 
     auto sit = sessions.find(path_id);
-    if(sit == sessions.end() || sit->second.ast_dirty) {
+    if(sit == sessions.end()) {
+        LOG_WARN("forward_query: session lost after compile for {}", path);
+        co_await kota::fail("Document was closed during compilation");
+    }
+    if(sit->second.ast_dirty) {
+        LOG_DEBUG("forward_query: still dirty after compile for {} (concurrent edit)", path);
         co_return serde_raw{"null"};
     }
 
@@ -800,8 +856,13 @@ Compiler::RawResult Compiler::forward_query(worker::QueryKind kind,
 
     if(position) {
         auto offset = mapper.to_offset(*position);
-        if(!offset)
-            co_return serde_raw{"null"};
+        if(!offset) {
+            LOG_WARN("forward_query: invalid position {}:{} for {}",
+                     position->line,
+                     position->character,
+                     path);
+            co_await kota::fail("Invalid position: failed to convert to byte offset");
+        }
         wp.offset = *offset;
     }
 
@@ -815,7 +876,8 @@ Compiler::RawResult Compiler::forward_query(worker::QueryKind kind,
 
     auto result = co_await pool.send_stateful(path_id, wp);
     if(!result.has_value()) {
-        co_return serde_raw{};
+        LOG_WARN("forward_query: worker failed for {}: {}", path, result.error().message);
+        co_await kota::fail(result.error().message);
     }
     co_return std::move(result.value());
 }
@@ -834,27 +896,36 @@ Compiler::RawResult Compiler::forward_build(worker::BuildKind kind,
     wp.version = session.version;
     wp.text = session.text;
     if(!fill_compile_args(path, wp.directory, wp.arguments, &session)) {
-        co_return serde_raw{};
+        LOG_WARN("forward_build: compile args not available for {}", path);
+        co_await kota::fail("Compile arguments not available");
     }
 
     if(!co_await ensure_deps(session, wp.directory, wp.arguments, wp.pch, wp.pcms)) {
-        co_return serde_raw{};
+        LOG_WARN("forward_build: dependency preparation failed for {}", path);
+        co_await kota::fail("Dependency preparation failed");
     }
 
     // After co_await, verify session still exists.
     if(sessions.find(path_id) == sessions.end()) {
-        co_return serde_raw{};
+        LOG_WARN("forward_build: session lost after co_await for {}", path);
+        co_await kota::fail("Document was closed during compilation");
     }
 
     lsp::PositionMapper mapper(wp.text, lsp::PositionEncoding::UTF16);
     auto offset = mapper.to_offset(position);
-    if(!offset)
-        co_return serde_raw{"null"};
+    if(!offset) {
+        LOG_WARN("forward_build: invalid position {}:{} for {}",
+                 position.line,
+                 position.character,
+                 path);
+        co_await kota::fail("Invalid position: failed to convert to byte offset");
+    }
     wp.offset = *offset;
 
     auto result = co_await pool.send_stateless(wp);
     if(!result.has_value()) {
-        co_return serde_raw{};
+        LOG_WARN("forward_build: worker failed for {}: {}", path, result.error().message);
+        co_await kota::fail(result.error().message);
     }
     co_return std::move(result.value().result_json);
 }
@@ -872,8 +943,10 @@ Compiler::RawResult Compiler::handle_completion(const protocol::Position& positi
            pctx.kind == CompletionContext::IncludeAngled) {
             std::string directory;
             std::vector<std::string> arguments;
-            if(!fill_compile_args(path, directory, arguments))
-                co_return serde_raw{"[]"};
+            if(!fill_compile_args(path, directory, arguments)) {
+                LOG_WARN("handle_completion: compile args not available for {}", path);
+                co_await kota::fail("Compile arguments not available for include completion");
+            }
 
             std::vector<const char*> args_ptrs;
             args_ptrs.reserve(arguments.size());

src/server/compiler.h

@@ -14,7 +14,7 @@
 #include "syntax/completion.h"
 
 #include "kota/async/async.h"
-#include "kota/codec/raw_value.h"
+#include "kota/codec/json/json.h"
 #include "kota/ipc/codec/json.h"
 #include "kota/ipc/lsp/protocol.h"
 #include "kota/ipc/peer.h"

src/server/config.cpp

@@ -1,99 +1,197 @@
 #include "server/config.h"
 
 #include <algorithm>
-#include <thread>
 
 #include "support/filesystem.h"
+#include "support/glob_pattern.h"
 #include "support/logging.h"
 
-#include "kota/codec/toml.h"
+#include "kota/async/io/system.h"
+#include "kota/codec/json/json.h"
+#include "kota/codec/toml/toml.h"
+#include "llvm/Support/FileSystem.h"
+#include "llvm/Support/Path.h"
+#include "llvm/Support/Process.h"
+#include "llvm/Support/xxhash.h"
 
 namespace clice {
 
 /// Replace all occurrences of ${workspace} with the workspace root.
-static void substitute_workspace(std::string& value, const std::string& workspace_root) {
+/// No-op when workspace_root is empty, to avoid producing paths like "/cache"
+/// from "${workspace}/cache".
+static void substitute_workspace(std::string& value, llvm::StringRef workspace_root) {
+    if(workspace_root.empty())
+        return;
     constexpr std::string_view placeholder = "${workspace}";
-    std::string::size_type pos = 0;
+    std::size_t pos = 0;
     while((pos = value.find(placeholder, pos)) != std::string::npos) {
         value.replace(pos, placeholder.size(), workspace_root);
         pos += workspace_root.size();
     }
 }
 
-void CliceConfig::apply_defaults(const std::string& workspace_root) {
-    auto cpu_count = std::thread::hardware_concurrency();
-    if(cpu_count == 0)
-        cpu_count = 4;
-
-    if(stateful_worker_count == 0) {
-        stateful_worker_count = 2;
-    }
-    if(stateless_worker_count == 0) {
-        stateless_worker_count = 3;
-    }
-    if(worker_memory_limit == 0) {
-        worker_memory_limit = 4ULL * 1024 * 1024 * 1024;  // 4GB default
-    }
-    if(cache_dir.empty() && !workspace_root.empty()) {
-        cache_dir = path::join(workspace_root, ".clice");
+/// Try to resolve the default cache directory using XDG_CACHE_HOME.
+/// Returns empty string on failure.
+static std::string resolve_xdg_cache_dir(llvm::StringRef workspace_root) {
+    // Determine base: $XDG_CACHE_HOME or ~/.cache
+    std::string base;
+    if(auto xdg = llvm::sys::Process::GetEnv("XDG_CACHE_HOME"); xdg && !xdg->empty()) {
+        base = std::move(*xdg);
+    } else if(auto home = llvm::sys::Process::GetEnv("HOME"); home && !home->empty()) {
+        base = path::join(*home, ".cache");
+    } else {
+        return {};
     }
 
-    if(index_dir.empty() && !cache_dir.empty()) {
-        index_dir = path::join(cache_dir, "index");
-    }
+    // Use a hash of workspace_root to create a unique subdirectory.
+    auto hash = llvm::xxh3_64bits(workspace_root);
+    auto dir = path::join(base, "clice", std::format("{:016x}", hash));
 
-    if(logging_dir.empty() && !cache_dir.empty()) {
-        logging_dir = path::join(cache_dir, "logs");
+    if(auto ec = llvm::sys::fs::create_directories(dir)) {
+        LOG_WARN("Failed to create XDG cache directory {}: {}", dir, ec.message());
+        return {};
     }
-
-    // Apply variable substitution to string fields
-    substitute_workspace(compile_commands_path, workspace_root);
-    substitute_workspace(cache_dir, workspace_root);
-    substitute_workspace(index_dir, workspace_root);
-    substitute_workspace(logging_dir, workspace_root);
+    return dir;
 }
 
-std::optional<CliceConfig> CliceConfig::load(const std::string& path,
-                                             const std::string& workspace_root) {
-    auto content = fs::read(path);
-    if(!content) {
-        return std::nullopt;
-    }
+void Config::apply_defaults(llvm::StringRef workspace_root) {
+    auto& p = project;
 
-    auto result = kota::codec::toml::parse<CliceConfig>(*content);
+    if(p.max_active_file == 0)
+        p.max_active_file = 8;
+    if(!p.enable_indexing)
+        p.enable_indexing = true;
+    if(!p.idle_timeout_ms)
+        p.idle_timeout_ms = 3000;
+
+    if(p.stateful_worker_count == 0)
+        p.stateful_worker_count = 2;
+    if(p.stateless_worker_count == 0) {
+        auto cores = kota::sys::parallelism();
+        p.stateless_worker_count = std::max(cores / 2, 2u);
+    }
+    if(p.worker_memory_limit == 0)
+        p.worker_memory_limit = 4ULL * 1024 * 1024 * 1024;  // 4GB
+
+    if(p.cache_dir.empty() && !workspace_root.empty()) {
+        p.cache_dir = resolve_xdg_cache_dir(workspace_root);
+        if(p.cache_dir.empty())
+            p.cache_dir = path::join(workspace_root, ".clice");
+    }
+    if(p.index_dir.empty() && !p.cache_dir.empty())
+        p.index_dir = path::join(p.cache_dir, "index");
+    if(p.logging_dir.empty() && !p.cache_dir.empty())
+        p.logging_dir = path::join(p.cache_dir, "logs");
+
+    // Variable substitution on string fields.
+    substitute_workspace(p.cache_dir, workspace_root);
+    substitute_workspace(p.index_dir, workspace_root);
+    substitute_workspace(p.logging_dir, workspace_root);
+    for(auto& entry: p.compile_commands_paths)
+        substitute_workspace(entry, workspace_root);
+
+    // Pre-compile glob patterns from rules.
+    compiled_rules.clear();
+    for(auto& rule: rules) {
+        CompiledRule compiled;
+        for(auto& pattern_str: rule.patterns) {
+            auto pat = GlobPattern::create(pattern_str);
+            if(!pat) {
+                LOG_WARN("Invalid glob pattern in rule: {}", pattern_str);
+                continue;
+            }
+            compiled.patterns.push_back(std::move(*pat));
+        }
+        // Drop the whole rule if no pattern compiled successfully — otherwise the
+        // append/remove flags would be silently attached to a rule that can never match.
+        if(compiled.patterns.empty()) {
+            if(!rule.patterns.empty())
+                LOG_WARN("Rule dropped: all glob patterns failed to compile");
+            continue;
+        }
+        compiled.append.assign(rule.append.begin(), rule.append.end());
+        compiled.remove.assign(rule.remove.begin(), rule.remove.end());
+        compiled_rules.push_back(std::move(compiled));
+    }
+}
+
+void Config::match_rules(llvm::StringRef file_path,
+                         std::vector<std::string>& append,
+                         std::vector<std::string>& remove) const {
+    // Rules are processed in declaration order so that a later rule can
+    // override an earlier one. Specifically, when a later rule removes
+    // an argument, we also strip any string-equal entry already added
+    // to `append` by an earlier matching rule — otherwise the append
+    // would silently survive (lookup applies removes to the base flags
+    // only, not to entries contributed via `append`).
+    for(auto& rule: compiled_rules) {
+        bool matched =
+            std::ranges::any_of(rule.patterns, [&](auto& pat) { return pat.match(file_path); });
+        if(!matched)
+            continue;
+
+        for(auto& r: rule.remove) {
+            std::erase(append, r);
+            remove.push_back(r);
+        }
+        append.insert(append.end(), rule.append.begin(), rule.append.end());
+    }
+}
+
+std::optional<Config> Config::load(llvm::StringRef path, llvm::StringRef workspace_root) {
+    auto content = fs::read(path);
+    if(!content)
+        return std::nullopt;
+
+    auto result = kota::codec::toml::parse<Config>(*content);
     if(!result) {
-        LOG_WARN("Failed to parse config file {}", path);
+        LOG_ERROR("Invalid clice.toml {}: {}", path, result.error().to_string());
         return std::nullopt;
     }
 
     auto config = std::move(*result);
     config.apply_defaults(workspace_root);
-
     LOG_INFO("Loaded config from {}", path);
     return config;
 }
 
-CliceConfig CliceConfig::load_from_workspace(const std::string& workspace_root) {
+std::optional<Config> Config::load_from_json(llvm::StringRef json, llvm::StringRef workspace_root) {
+    auto result = kota::codec::json::from_json<Config>(json);
+    if(!result) {
+        LOG_WARN("Failed to parse initializationOptions JSON: {}", result.error().message());
+        return std::nullopt;
+    }
+
+    auto config = std::move(*result);
+    config.apply_defaults(workspace_root);
+    LOG_INFO("Loaded config from initializationOptions");
+    return config;
+}
+
+Config Config::load_from_workspace(llvm::StringRef workspace_root, std::string* warning) {
     if(!workspace_root.empty()) {
-        // Try standard config file locations
         for(auto* name: {"clice.toml", ".clice/config.toml"}) {
             auto config_path = path::join(workspace_root, name);
-            if(llvm::sys::fs::exists(config_path)) {
-                auto config = load(config_path, workspace_root);
-                if(config)
-                    return std::move(*config);
-            }
+            if(!llvm::sys::fs::exists(config_path))
+                continue;
+            if(auto config = load(config_path, workspace_root))
+                return std::move(*config);
+            // Present but malformed: fall through to defaults, but surface
+            // the situation clearly so users know their config wasn't applied.
+            LOG_WARN("Falling back to default configuration because {} is invalid", config_path);
+            if(warning)
+                *warning = std::format("Configuration file {} is invalid, falling back to defaults",
+                                       config_path);
         }
     }
 
-    // No config file found; use defaults
-    CliceConfig config;
+    Config config;
     config.apply_defaults(workspace_root);
     LOG_INFO(
         "No clice.toml found, using default configuration " "(stateful={}, stateless={}, memory_limit={}MB)",
-        config.stateful_worker_count,
-        config.stateless_worker_count,
-        config.worker_memory_limit / (1024 * 1024));
+        config.project.stateful_worker_count.value,
+        config.project.stateless_worker_count.value,
+        config.project.worker_memory_limit.value / (1024 * 1024));
     return config;
 }
 

src/server/config.h

@@ -3,44 +3,80 @@
 #include <cstdint>
 #include <optional>
 #include <string>
+#include <vector>
+
+#include "support/glob_pattern.h"
+
+#include "kota/meta/annotation.h"
+#include "llvm/ADT/StringRef.h"
 
 namespace clice {
 
-/// Configuration for the clice LSP server, loadable from clice.toml.
-struct CliceConfig {
-    // Worker configuration (0 = auto-detect from system resources)
-    std::uint32_t stateful_worker_count = 0;
-    std::uint32_t stateless_worker_count = 0;
-    std::uint64_t worker_memory_limit = 0;  // bytes; 0 = auto
+using kota::meta::defaulted;
 
-    // Compilation database path (empty = auto-detect)
-    std::string compile_commands_path;
+/// A file-pattern rule that appends/removes compilation flags.
+/// Corresponds to `[[rules]]` in clice.toml.
+struct ConfigRule {
+    defaulted<std::vector<std::string>> patterns;
+    defaulted<std::vector<std::string>> append;
+    defaulted<std::vector<std::string>> remove;
+};
 
-    // Cache directory (empty = default: <workspace>/.clice/)
-    std::string cache_dir;
+/// Corresponds to the `[project]` section in clice.toml.
+struct ProjectConfig {
+    defaulted<bool> clang_tidy = {};
+    defaulted<int> max_active_file = {};
 
-    // Index storage directory (default: <cache_dir>/index/)
-    std::string index_dir;
+    defaulted<std::string> cache_dir;
+    defaulted<std::string> index_dir;
+    defaulted<std::string> logging_dir;
 
-    // Logging directory (default: <cache_dir>/logs/)
-    std::string logging_dir;
+    defaulted<std::vector<std::string>> compile_commands_paths;
 
-    // Background indexing
-    bool enable_indexing = true;
-    int idle_timeout_ms = 3000;
+    std::optional<bool> enable_indexing;
+    std::optional<int> idle_timeout_ms;
+
+    defaulted<std::uint32_t> stateful_worker_count = {};
+    defaulted<std::uint32_t> stateless_worker_count = {};
+    defaulted<std::uint64_t> worker_memory_limit = {};
+};
+
+struct CompiledRule {
+    std::vector<GlobPattern> patterns;
+    std::vector<std::string> append;
+    std::vector<std::string> remove;
+};
+
+/// Configuration for the clice LSP server, loadable from clice.toml
+/// or passed via LSP initializationOptions.
+struct Config {
+    defaulted<ProjectConfig> project;
+
+    defaulted<std::vector<ConfigRule>> rules;
+
+    kota::meta::annotation<std::vector<CompiledRule>, kota::meta::attrs::skip> compiled_rules;
 
     /// Compute default values for any field left at its zero/empty sentinel.
-    void apply_defaults(const std::string& workspace_root);
+    void apply_defaults(llvm::StringRef workspace_root);
+
+    /// Collect append/remove flags from all rules whose patterns match `path`.
+    void match_rules(llvm::StringRef path,
+                     std::vector<std::string>& append,
+                     std::vector<std::string>& remove) const;
 
     /// Try to load configuration from a TOML file.
-    /// Performs ${workspace} variable substitution in string fields.
-    /// Returns std::nullopt if the file does not exist or cannot be parsed.
-    static std::optional<CliceConfig> load(const std::string& path,
-                                           const std::string& workspace_root);
+    static std::optional<Config> load(llvm::StringRef path, llvm::StringRef workspace_root);
+
+    /// Try to load configuration from a JSON string (e.g. initializationOptions).
+    static std::optional<Config> load_from_json(llvm::StringRef json,
+                                                llvm::StringRef workspace_root);
 
     /// Load config from the workspace, trying standard locations.
     /// Returns a default config (with apply_defaults) if no file is found.
-    static CliceConfig load_from_workspace(const std::string& workspace_root);
+    /// If `warning` is non-null and a config file was found but malformed,
+    /// the warning message is written there.
+    static Config load_from_workspace(llvm::StringRef workspace_root,
+                                      std::string* warning = nullptr);
 };
 
 }  // namespace clice

src/server/indexer.cpp

@@ -1,5 +1,6 @@
 #include "server/indexer.h"
 
+#include <algorithm>
 #include <string>
 #include <variant>
 #include <vector>
@@ -624,18 +625,105 @@ void Indexer::enqueue(std::uint32_t server_path_id) {
     index_queue.push_back(server_path_id);
 }
 
+void Indexer::pause_indexing() {
+    ++pause_depth;
+    if(pause_depth == 1) {
+        resume_event.reset();
+        LOG_DEBUG("Background indexing paused");
+    }
+}
+
+void Indexer::resume_indexing() {
+    if(pause_depth > 0)
+        --pause_depth;
+    if(pause_depth == 0) {
+        resume_event.set();
+        LOG_DEBUG("Background indexing resumed");
+    }
+}
+
 void Indexer::schedule() {
-    if(!workspace.config.enable_indexing || indexing_active || indexing_scheduled)
+    if(!*workspace.config.project.enable_indexing || indexing_active || indexing_scheduled)
         return;
     indexing_scheduled = true;
 
     if(!index_idle_timer) {
         index_idle_timer = std::make_shared<kota::timer>(kota::timer::create(loop));
     }
-    index_idle_timer->start(std::chrono::milliseconds(workspace.config.idle_timeout_ms));
+    index_idle_timer->start(std::chrono::milliseconds(*workspace.config.project.idle_timeout_ms));
     loop.schedule(run_background_indexing());
 }
 
+kota::task<> Indexer::index_one(std::uint32_t server_path_id) {
+    auto file_path = std::string(workspace.path_pool.resolve(server_path_id));
+
+    if(sessions.contains(server_path_id))
+        co_return;
+
+    if(!need_update(file_path))
+        co_return;
+
+    // For module interface units, compile their PCM (and transitive deps)
+    // first so the stateless worker has the artifacts it needs.
+    if(workspace.compile_graph && workspace.path_to_module.contains(server_path_id)) {
+        co_await workspace.compile_graph->compile(server_path_id);
+    }
+
+    worker::BuildParams params;
+    params.kind = worker::BuildKind::Index;
+    params.file = file_path;
+    if(!compiler.fill_compile_args(file_path, params.directory, params.arguments, nullptr))
+        co_return;
+
+    workspace.fill_pcm_deps(params.pcms);
+
+    LOG_INFO("Background indexing: {}", file_path);
+
+    auto result = co_await pool.send_stateless(params);
+    if(result.has_value() && result.value().success && !result.value().tu_index_data.empty()) {
+        LOG_INFO("Background indexing got TUIndex for {}: {} bytes",
+                 file_path,
+                 result.value().tu_index_data.size());
+        merge(result.value().tu_index_data.data(), result.value().tu_index_data.size());
+    } else if(result.has_value() && !result.value().success) {
+        LOG_WARN("Background index failed for {}: {}", file_path, result.value().error);
+    } else if(result.has_value() && result.value().tu_index_data.empty()) {
+        LOG_WARN("Background index returned empty TUIndex for {}", file_path);
+    } else {
+        LOG_WARN("Background index IPC error for {}: {}", file_path, result.error().message);
+    }
+}
+
+kota::task<> Indexer::monitor_resources(std::uint32_t generation) {
+    while(generation == monitor_generation) {
+        co_await kota::sleep(std::chrono::milliseconds(3000), loop);
+
+        if(generation != monitor_generation)
+            break;
+
+        auto mem = kota::sys::memory();
+        if(mem.total == 0)
+            continue;
+
+        // Respect cgroup/container limits when present.
+        auto effective_total =
+            (mem.constrained > 0 && mem.constrained < mem.total) ? mem.constrained : mem.total;
+        auto ratio = static_cast<double>(mem.available) / static_cast<double>(effective_total);
+
+        if(ratio < 0.15 && max_concurrent > 1) {
+            --max_concurrent;
+            LOG_INFO("Index concurrency -> {} (memory pressure: {:.0f}% available)",
+                     max_concurrent,
+                     ratio * 100);
+        } else if(ratio > 0.30 && max_concurrent < baseline_concurrent) {
+            ++max_concurrent;
+            LOG_DEBUG("Index concurrency -> {} (memory OK: {:.0f}% available)",
+                      max_concurrent,
+                      ratio * 100);
+        }
+    }
+}
+
 kota::task<> Indexer::run_background_indexing() {
     if(index_idle_timer) {
         co_await index_idle_timer->wait();
@@ -648,49 +736,89 @@ kota::task<> Indexer::run_background_indexing() {
     }
 
     indexing_active = true;
-    std::size_t processed = 0;
+    ++monitor_generation;
+    loop.schedule(monitor_resources(monitor_generation));
 
-    while(index_queue_pos < index_queue.size()) {
-        auto server_path_id = index_queue[index_queue_pos];
-        index_queue_pos++;
+    // Put module interface units first so their PCMs are built before
+    // non-module files that might import them.
+    std::stable_partition(
+        index_queue.begin() + index_queue_pos,
+        index_queue.end(),
+        [this](std::uint32_t id) { return workspace.path_to_module.contains(id); });
 
-        auto file_path = std::string(workspace.path_pool.resolve(server_path_id));
+    auto batch = index_queue.size() - index_queue_pos;
+    std::size_t dispatched = 0;
+    std::size_t completed = 0;
+    finished = 0;
 
-        if(sessions.contains(server_path_id))
-            continue;
-
-        if(!need_update(file_path))
-            continue;
-
-        worker::BuildParams params;
-        params.kind = worker::BuildKind::Index;
-        params.file = file_path;
-        if(!compiler.fill_compile_args(file_path, params.directory, params.arguments, nullptr))
-            continue;
-
-        workspace.fill_pcm_deps(params.pcms);
-
-        LOG_INFO("Background indexing: {}", file_path);
-
-        auto result = co_await pool.send_stateless(params);
-        if(result.has_value() && result.value().success && !result.value().tu_index_data.empty()) {
-            LOG_INFO("Background indexing got TUIndex for {}: {} bytes",
-                     file_path,
-                     result.value().tu_index_data.size());
-            merge(result.value().tu_index_data.data(), result.value().tu_index_data.size());
-            ++processed;
-        } else if(result.has_value() && !result.value().success) {
-            LOG_WARN("Background index failed for {}: {}", file_path, result.value().error);
-        } else if(result.has_value() && result.value().tu_index_data.empty()) {
-            LOG_WARN("Background index returned empty TUIndex for {}", file_path);
+    // Progress reporting via LSP $/progress.
+    std::optional<lsp::ProgressReporter<kota::ipc::JsonPeer>> progress;
+    if(peer) {
+        progress.emplace(*peer, protocol::ProgressToken(std::string("clice/backgroundIndex")));
+        auto create_result = co_await progress->create();
+        if(!create_result.has_error()) {
+            progress->begin("Indexing", std::format("0/{} files", batch), 0);
         } else {
-            LOG_WARN("Background index IPC error for {}: {}", file_path, result.error().message);
+            progress.reset();
         }
     }
 
+    while(index_queue_pos < index_queue.size() || inflight > 0) {
+        // Dispatch new tasks up to max_concurrent.
+        while(index_queue_pos < index_queue.size() && inflight < max_concurrent) {
+            // Wait if paused by a user request.
+            if(pause_depth > 0) {
+                co_await resume_event.wait();
+            }
+
+            auto server_path_id = index_queue[index_queue_pos++];
+
+            // Quick pre-filter: skip open files and fresh files without
+            // consuming a concurrency slot.
+            auto file_path = std::string(workspace.path_pool.resolve(server_path_id));
+            if(sessions.contains(server_path_id) || !need_update(file_path)) {
+                ++completed;
+                continue;
+            }
+
+            ++inflight;
+            ++dispatched;
+
+            // Launch the index task.  On completion it decrements
+            // inflight, bumps finished, and signals the event.
+            loop.schedule([](Indexer* self, std::uint32_t id, kota::event& done) -> kota::task<> {
+                co_await self->index_one(id);
+                --self->inflight;
+                ++self->finished;
+                done.set();
+            }(this, server_path_id, completion_event));
+        }
+
+        if(inflight == 0)
+            break;
+
+        // Wait for at least one task to finish.
+        co_await completion_event.wait();
+        completion_event.reset();
+
+        // Drain all completions that occurred since last wake.
+        completed += std::exchange(finished, 0);
+
+        // Report progress.
+        if(progress) {
+            auto pct = batch > 0 ? static_cast<std::uint32_t>(completed * 100 / batch) : 100;
+            progress->report(std::format("{}/{} files", completed, batch), pct);
+        }
+    }
+
+    if(progress) {
+        progress->end(std::format("Indexed {} files", dispatched));
+    }
+
     indexing_active = false;
-    LOG_INFO("Background indexing complete: {} files processed", processed);
-    save(workspace.config.index_dir);
+    ++monitor_generation;  // Stop the monitor coroutine.
+    LOG_INFO("Background indexing complete: {} files dispatched", dispatched);
+    save(workspace.config.project.index_dir);
 }
 
 }  // namespace clice

src/server/indexer.h

@@ -12,7 +12,9 @@
 #include "server/workspace.h"
 
 #include "kota/async/async.h"
+#include "kota/ipc/codec/json.h"
 #include "kota/ipc/lsp/position.h"
+#include "kota/ipc/lsp/progress.h"
 #include "kota/ipc/lsp/protocol.h"
 #include "llvm/ADT/DenseMap.h"
 #include "llvm/ADT/SmallVector.h"
@@ -62,6 +64,47 @@ public:
         loop(loop), workspace(workspace), sessions(sessions), pool(pool), compiler(compiler),
         is_file_open(std::move(is_file_open)) {}
 
+    /// Set the LSP peer for progress reporting.  Must be called before
+    /// schedule() if progress notifications are desired.
+    void set_peer(kota::ipc::JsonPeer* p) {
+        peer = p;
+    }
+
+    /// Temporarily pause background indexing to give priority to user
+    /// requests.  Indexing tasks already dispatched to workers continue,
+    /// but no new tasks will be sent until resume_indexing() is called.
+    void pause_indexing();
+
+    /// Resume background indexing after a pause.
+    void resume_indexing();
+
+    /// RAII guard that pauses indexing for its lifetime.
+    struct [[nodiscard]] ScopedPause {
+        Indexer& indexer;
+
+        explicit ScopedPause(Indexer& idx) : indexer(idx) {
+            indexer.pause_indexing();
+        }
+
+        ~ScopedPause() {
+            indexer.resume_indexing();
+        }
+
+        ScopedPause(const ScopedPause&) = delete;
+        ScopedPause& operator=(const ScopedPause&) = delete;
+    };
+
+    ScopedPause scoped_pause() {
+        return ScopedPause{*this};
+    }
+
+    /// Set the maximum number of concurrent index tasks.
+    /// Also sets the baseline that dynamic adjustment will restore to.
+    void set_max_concurrency(std::size_t n) {
+        max_concurrent = std::max<std::size_t>(n, 1);
+        baseline_concurrent = max_concurrent;
+    }
+
     /// Add a file to the background indexing queue.
     void enqueue(std::uint32_t server_path_id);
 
@@ -175,6 +218,9 @@ private:
     /// server-path-id-keyed sessions map to project-level path_ids.
     std::function<bool(std::uint32_t)> is_file_open;
 
+    /// LSP peer for progress reporting (optional, not owned).
+    kota::ipc::JsonPeer* peer = nullptr;
+
     /// Background indexing queue and scheduling state.
     std::vector<std::uint32_t> index_queue;
     std::size_t index_queue_pos = 0;
@@ -182,7 +228,30 @@ private:
     bool indexing_scheduled = false;
     std::shared_ptr<kota::timer> index_idle_timer;
 
+    /// Concurrency control for background indexing.
+    std::size_t max_concurrent = 2;
+    std::size_t baseline_concurrent = 2;
+    std::size_t inflight = 0;
+    std::size_t finished = 0;  ///< Incremented by each completed dispatch task.
+
+    /// Pause/resume: when paused, new index tasks wait on this event.
+    /// Uses a counter so nested pause/resume pairs work correctly.
+    std::size_t pause_depth = 0;
+    kota::event resume_event{true};
+
+    /// Completion event — signalled by each finished dispatch task so the
+    /// main loop can wake up.  Must be a member (not local to the coroutine)
+    /// because inflight tasks capture it by reference and may outlive the
+    /// coroutine frame during server shutdown.
+    kota::event completion_event;
+
+    /// Generation counter — incremented each run so a stale monitor_resources
+    /// coroutine can detect that its owning run has ended.
+    std::uint32_t monitor_generation = 0;
+
     kota::task<> run_background_indexing();
+    kota::task<> index_one(std::uint32_t server_path_id);
+    kota::task<> monitor_resources(std::uint32_t generation);
 };
 
 }  // namespace clice

src/server/master_server.cpp

@@ -56,63 +56,93 @@ MasterServer::MasterServer(kota::event_loop& loop,
 
 MasterServer::~MasterServer() = default;
 
-kota::task<> MasterServer::load_workspace() {
+void MasterServer::load_workspace() {
     if(workspace_root.empty())
-        co_return;
+        return;
 
-    if(!workspace.config.cache_dir.empty()) {
-        auto ec = llvm::sys::fs::create_directories(workspace.config.cache_dir);
+    auto& cfg = workspace.config.project;
+
+    if(!cfg.cache_dir.empty()) {
+        auto ec = llvm::sys::fs::create_directories(cfg.cache_dir);
         if(ec) {
             LOG_WARN("Failed to create cache directory {}: {}",
-                     workspace.config.cache_dir,
+                     std::string_view(cfg.cache_dir),
                      ec.message());
         } else {
-            LOG_INFO("Cache directory: {}", workspace.config.cache_dir);
+            LOG_INFO("Cache directory: {}", std::string_view(cfg.cache_dir));
         }
 
         for(auto* subdir: {"cache/pch", "cache/pcm"}) {
-            auto dir = path::join(workspace.config.cache_dir, subdir);
-            auto ec2 = llvm::sys::fs::create_directories(dir);
-            if(ec2) {
+            auto dir = path::join(cfg.cache_dir, subdir);
+            if(auto ec2 = llvm::sys::fs::create_directories(dir))
                 LOG_WARN("Failed to create {}: {}", dir, ec2.message());
-            }
         }
 
-        // Clean up stale files first, then load — load_cache() only restores
-        // entries still listed in cache.json, so cleanup won't delete live files.
         workspace.cleanup_cache();
         workspace.load_cache();
     }
 
+    // Discover compile_commands.json: configured paths first, then auto-scan.
     std::string cdb_path;
-    if(!workspace.config.compile_commands_path.empty()) {
-        if(llvm::sys::fs::exists(workspace.config.compile_commands_path)) {
-            cdb_path = workspace.config.compile_commands_path;
-        } else {
-            LOG_WARN("Configured compile_commands_path not found: {}",
-                     workspace.config.compile_commands_path);
-        }
-    }
-
-    if(cdb_path.empty()) {
-        for(auto* subdir: {"build", "cmake-build-debug", "cmake-build-release", "out", "."}) {
-            auto candidate = path::join(workspace_root, subdir, "compile_commands.json");
+    for(auto& configured: cfg.compile_commands_paths) {
+        // Each entry can be a file or a directory containing compile_commands.json.
+        if(llvm::sys::fs::is_directory(configured)) {
+            auto candidate = path::join(configured, "compile_commands.json");
             if(llvm::sys::fs::exists(candidate)) {
                 cdb_path = std::move(candidate);
                 break;
             }
+        } else if(llvm::sys::fs::exists(configured)) {
+            cdb_path = configured;
+            break;
+        } else {
+            LOG_WARN("Configured compile_commands_path not found: {}", configured);
+        }
+    }
+
+    // Auto-scan: workspace root + all immediate subdirectories.
+    if(cdb_path.empty()) {
+        auto try_candidate = [&](llvm::StringRef dir) -> bool {
+            auto candidate = path::join(dir, "compile_commands.json");
+            if(llvm::sys::fs::exists(candidate)) {
+                cdb_path = std::move(candidate);
+                return true;
+            }
+            return false;
+        };
+
+        if(!try_candidate(workspace_root)) {
+            std::error_code ec;
+            for(llvm::sys::fs::directory_iterator it(workspace_root, ec), end; it != end && !ec;
+                it.increment(ec)) {
+                if(it->type() == llvm::sys::fs::file_type::directory_file) {
+                    if(try_candidate(it->path()))
+                        break;
+                }
+            }
         }
     }
 
     if(cdb_path.empty()) {
         LOG_WARN("No compile_commands.json found in workspace {}", workspace_root);
-        co_return;
+        peer.send_notification(protocol::LogMessageParams{
+            protocol::MessageType::Warning,
+            std::format("No compile_commands.json found in workspace {}", workspace_root)});
+        return;
     }
 
     auto count = workspace.cdb.load(cdb_path);
     LOG_INFO("Loaded CDB from {} with {} entries", cdb_path, count);
 
-    auto report = scan_dependency_graph(workspace.cdb, workspace.path_pool, workspace.dep_graph);
+    auto report = scan_dependency_graph(workspace.cdb,
+                                        workspace.path_pool,
+                                        workspace.dep_graph,
+                                        /*cache=*/nullptr,
+                                        [this](llvm::StringRef path,
+                                               std::vector<std::string>& append,
+                                               std::vector<std::string>& remove) {
+                                            workspace.config.match_rules(path, append, remove);
+                                        });
     workspace.dep_graph.build_reverse_map();
 
     auto unresolved = report.includes_found - report.includes_resolved;
@@ -131,14 +161,13 @@ kota::task<> MasterServer::load_workspace() {
         report.includes_found,
         accuracy,
         report.waves);
-    if(unresolved > 0) {
+    if(unresolved > 0)
         LOG_WARN("{} unresolved includes", unresolved);
-    }
 
     workspace.build_module_map();
-    indexer.load(workspace.config.index_dir);
+    indexer.load(cfg.index_dir);
 
-    if(workspace.config.enable_indexing) {
+    if(*cfg.enable_indexing) {
         for(auto& entry: workspace.cdb.get_entries()) {
             auto file = workspace.cdb.resolve_path(entry.file);
             auto server_id = workspace.path_pool.intern(file);
@@ -164,6 +193,14 @@ void MasterServer::register_handlers() {
             workspace_root = uri_to_path(*init.root_uri);
         }
 
+        // Capture initializationOptions as raw JSON for config loading.
+        if(init.initialization_options.has_value()) {
+            auto json =
+                kota::codec::json::to_json<kota::ipc::lsp_config>(*init.initialization_options);
+            if(json)
+                init_options_json = std::move(*json);
+        }
+
         lifecycle = ServerLifecycle::Initialized;
         LOG_INFO("Initialized with workspace: {}", workspace_root);
 
@@ -244,30 +281,60 @@ void MasterServer::register_handlers() {
     });
 
     peer.on_notification([this](const protocol::InitializedParams& params) {
-        workspace.config = CliceConfig::load_from_workspace(workspace_root);
+        // Config priority: initializationOptions > clice.toml > defaults.
+        // Load the workspace config (with defaults applied) first, then overlay
+        // any initializationOptions on top so fields not mentioned in the JSON
+        // keep the values from clice.toml — kotatsu's deserializer only touches
+        // fields that are present in the input.
+        std::string config_warning;
+        workspace.config = Config::load_from_workspace(workspace_root, &config_warning);
+        if(!config_warning.empty())
+            peer.send_notification(
+                protocol::LogMessageParams{protocol::MessageType::Warning, config_warning});
+        if(!init_options_json.empty()) {
+            if(auto ov = kota::codec::json::parse(init_options_json, workspace.config); !ov) {
+                LOG_WARN("Failed to apply initializationOptions: {}", ov.error().to_string());
+                peer.send_notification(protocol::LogMessageParams{
+                    protocol::MessageType::Warning,
+                    std::format("Failed to apply initializationOptions: {}",
+                                ov.error().to_string())});
+            } else {
+                // Re-run apply_defaults so overridden strings get workspace
+                // substitution and `compiled_rules` is rebuilt if `rules`
+                // changed. Defaults are gated on zero/empty sentinels, so
+                // existing values from the overlay are preserved.
+                workspace.config.apply_defaults(workspace_root);
+                LOG_INFO("Applied initializationOptions overlay");
+            }
+            init_options_json.clear();
+        }
 
-        if(!workspace.config.logging_dir.empty()) {
+        auto& cfg = workspace.config.project;
+
+        if(!cfg.logging_dir.empty()) {
             auto now = std::chrono::system_clock::now();
             auto pid = llvm::sys::Process::getProcessId();
-            auto session_dir = path::join(workspace.config.logging_dir,
-                                          std::format("{:%Y-%m-%d_%H-%M-%S}_{}", now, pid));
+            auto session_dir =
+                path::join(cfg.logging_dir, std::format("{:%Y-%m-%d_%H-%M-%S}_{}", now, pid));
             logging::file_logger("master", session_dir, logging::options);
             session_log_dir = session_dir;
         }
 
         LOG_INFO("Server ready (stateful={}, stateless={}, idle={}ms)",
-                 workspace.config.stateful_worker_count,
-                 workspace.config.stateless_worker_count,
-                 workspace.config.idle_timeout_ms);
+                 cfg.stateful_worker_count.value,
+                 cfg.stateless_worker_count.value,
+                 *cfg.idle_timeout_ms);
 
         WorkerPoolOptions pool_opts;
         pool_opts.self_path = self_path;
-        pool_opts.stateful_count = workspace.config.stateful_worker_count;
-        pool_opts.stateless_count = workspace.config.stateless_worker_count;
-        pool_opts.worker_memory_limit = workspace.config.worker_memory_limit;
+        pool_opts.stateful_count = cfg.stateful_worker_count;
+        pool_opts.stateless_count = cfg.stateless_worker_count;
+        pool_opts.worker_memory_limit = cfg.worker_memory_limit;
         pool_opts.log_dir = session_log_dir;
         if(!pool.start(pool_opts)) {
             LOG_ERROR("Failed to start worker pool");
+            peer.send_notification(protocol::LogMessageParams{protocol::MessageType::Error,
+                                                              "Failed to start worker pool"});
             return;
         }
 
@@ -277,7 +344,10 @@ void MasterServer::register_handlers() {
             indexer.schedule();
         };
 
-        loop.schedule(load_workspace());
+        indexer.set_peer(&peer);
+        indexer.set_max_concurrency(cfg.stateless_worker_count.value);
+
+        load_workspace();
     });
 
     peer.on_request(
@@ -292,7 +362,7 @@ void MasterServer::register_handlers() {
         lifecycle = ServerLifecycle::Exited;
         LOG_INFO("Exit notification received");
 
-        indexer.save(workspace.config.index_dir);
+        indexer.save(workspace.config.project.index_dir);
         workspace.save_cache();
 
         loop.schedule([this]() -> kota::task<> {
@@ -431,7 +501,7 @@ void MasterServer::register_handlers() {
         auto path_id = workspace.path_pool.intern(path);
         auto sit = sessions.find(path_id);
         if(sit == sessions.end())
-            co_return serde_raw{"null"};
+            co_await kota::fail("Document not open");
         co_return co_await compiler.forward_query(worker::QueryKind::Hover,
                                                   sit->second,
                                                   params.text_document_position_params.position);
@@ -443,7 +513,7 @@ void MasterServer::register_handlers() {
         auto path_id = workspace.path_pool.intern(path);
         auto sit = sessions.find(path_id);
         if(sit == sessions.end())
-            co_return serde_raw{"null"};
+            co_await kota::fail("Document not open");
         co_return co_await compiler.forward_query(worker::QueryKind::SemanticTokens, sit->second);
     });
 
@@ -453,7 +523,7 @@ void MasterServer::register_handlers() {
             auto path_id = workspace.path_pool.intern(path);
             auto sit = sessions.find(path_id);
             if(sit == sessions.end())
-                co_return serde_raw{"null"};
+                co_await kota::fail("Document not open");
             co_return co_await compiler.forward_query(worker::QueryKind::InlayHints,
                                                       sit->second,
                                                       {},
@@ -466,7 +536,7 @@ void MasterServer::register_handlers() {
             auto path_id = workspace.path_pool.intern(path);
             auto sit = sessions.find(path_id);
             if(sit == sessions.end())
-                co_return serde_raw{"null"};
+                co_await kota::fail("Document not open");
             co_return co_await compiler.forward_query(worker::QueryKind::FoldingRange, sit->second);
         });
 
@@ -476,7 +546,7 @@ void MasterServer::register_handlers() {
         auto path_id = workspace.path_pool.intern(path);
         auto sit = sessions.find(path_id);
         if(sit == sessions.end())
-            co_return serde_raw{"null"};
+            co_await kota::fail("Document not open");
         co_return co_await compiler.forward_query(worker::QueryKind::DocumentSymbol, sit->second);
     });
 
@@ -486,7 +556,7 @@ void MasterServer::register_handlers() {
         auto path_id = workspace.path_pool.intern(path);
         auto sit = sessions.find(path_id);
         if(sit == sessions.end())
-            co_return serde_raw{"null"};
+            co_await kota::fail("Document not open");
         auto& session = sit->second;
         auto result = co_await compiler.forward_query(worker::QueryKind::DocumentLink, session);
         if(!result.has_value())
@@ -519,7 +589,7 @@ void MasterServer::register_handlers() {
             auto path_id = workspace.path_pool.intern(path);
             auto sit = sessions.find(path_id);
             if(sit == sessions.end())
-                co_return serde_raw{"null"};
+                co_await kota::fail("Document not open");
             co_return co_await compiler.forward_query(worker::QueryKind::CodeAction, sit->second);
         });
 
@@ -574,7 +644,7 @@ void MasterServer::register_handlers() {
         auto path_id = workspace.path_pool.intern(path);
         auto sit = sessions.find(path_id);
         if(sit == sessions.end())
-            co_return serde_raw{"null"};
+            co_await kota::fail("Document not open");
         co_return co_await compiler.forward_query(worker::QueryKind::GoToDefinition,
                                                   sit->second,
                                                   pos);
@@ -616,28 +686,33 @@ void MasterServer::register_handlers() {
 
     /// Feature requests — stateless forwarding.
 
-    peer.on_request([this](RequestContext& ctx,
-                           const protocol::CompletionParams& params) -> RawResult {
-        auto path = uri_to_path(params.text_document_position_params.text_document.uri);
-        auto path_id = workspace.path_pool.intern(path);
-        auto sit = sessions.find(path_id);
-        if(sit == sessions.end())
-            co_return serde_raw{"null"};
-        co_return co_await compiler.handle_completion(params.text_document_position_params.position,
-                                                      sit->second);
-    });
-
     peer.on_request(
-        [this](RequestContext& ctx, const protocol::SignatureHelpParams& params) -> RawResult {
+        [this](RequestContext& ctx, const protocol::CompletionParams& params) -> RawResult {
             auto path = uri_to_path(params.text_document_position_params.text_document.uri);
             auto path_id = workspace.path_pool.intern(path);
             auto sit = sessions.find(path_id);
             if(sit == sessions.end())
-                co_return serde_raw{"null"};
-            co_return co_await compiler.forward_build(worker::BuildKind::SignatureHelp,
+                co_await kota::fail("Document not open");
+            auto pause = indexer.scoped_pause();
+            auto result =
+                co_await compiler.handle_completion(params.text_document_position_params.position,
+                                                    sit->second);
+            co_return std::move(result);
+        });
+
+    peer.on_request([this](RequestContext& ctx,
+                           const protocol::SignatureHelpParams& params) -> RawResult {
+        auto path = uri_to_path(params.text_document_position_params.text_document.uri);
+        auto path_id = workspace.path_pool.intern(path);
+        auto sit = sessions.find(path_id);
+        if(sit == sessions.end())
+            co_await kota::fail("Document not open");
+        auto pause = indexer.scoped_pause();
+        auto result = co_await compiler.forward_build(worker::BuildKind::SignatureHelp,
                                                       params.text_document_position_params.position,
                                                       sit->second);
-        });
+        co_return std::move(result);
+    });
 
     /// Hierarchy queries — index-based.
 
@@ -663,10 +738,8 @@ void MasterServer::register_handlers() {
                         const protocol::CallHierarchyIncomingCallsParams& params) -> RawResult {
         auto info = resolve_item(params.item.uri, params.item.range, params.item.data);
         if(!info)
-            co_return serde_raw{"null"};
+            co_await kota::fail("Failed to resolve call hierarchy item");
         auto results = indexer.find_incoming_calls(info->hash);
-        if(results.empty())
-            co_return serde_raw{"null"};
         co_return to_raw(results);
     });
 
@@ -675,10 +748,8 @@ void MasterServer::register_handlers() {
                         const protocol::CallHierarchyOutgoingCallsParams& params) -> RawResult {
         auto info = resolve_item(params.item.uri, params.item.range, params.item.data);
         if(!info)
-            co_return serde_raw{"null"};
+            co_await kota::fail("Failed to resolve call hierarchy item");
         auto results = indexer.find_outgoing_calls(info->hash);
-        if(results.empty())
-            co_return serde_raw{"null"};
         co_return to_raw(results);
     });
 
@@ -705,10 +776,8 @@ void MasterServer::register_handlers() {
                              const protocol::TypeHierarchySupertypesParams& params) -> RawResult {
             auto info = resolve_item(params.item.uri, params.item.range, params.item.data);
             if(!info)
-                co_return serde_raw{"null"};
+                co_await kota::fail("Failed to resolve type hierarchy item");
             auto results = indexer.find_supertypes(info->hash);
-            if(results.empty())
-                co_return serde_raw{"null"};
             co_return to_raw(results);
         });
 
@@ -717,18 +786,14 @@ void MasterServer::register_handlers() {
                              const protocol::TypeHierarchySubtypesParams& params) -> RawResult {
             auto info = resolve_item(params.item.uri, params.item.range, params.item.data);
             if(!info)
-                co_return serde_raw{"null"};
+                co_await kota::fail("Failed to resolve type hierarchy item");
             auto results = indexer.find_subtypes(info->hash);
-            if(results.empty())
-                co_return serde_raw{"null"};
             co_return to_raw(results);
         });
 
     peer.on_request(
         [this](RequestContext& ctx, const protocol::WorkspaceSymbolParams& params) -> RawResult {
             auto results = indexer.search_symbols(params.query);
-            if(results.empty())
-                co_return serde_raw{"null"};
             co_return to_raw(results);
         });
 

src/server/master_server.h

@@ -12,7 +12,7 @@
 #include "server/workspace.h"
 
 #include "kota/async/async.h"
-#include "kota/codec/raw_value.h"
+#include "kota/codec/json/json.h"
 #include "kota/ipc/peer.h"
 #include "llvm/ADT/DenseMap.h"
 
@@ -71,8 +71,9 @@ private:
     std::string self_path;
     std::string workspace_root;
     std::string session_log_dir;
+    std::string init_options_json;  ///< Raw JSON from initializationOptions, consumed once.
 
-    kota::task<> load_workspace();
+    void load_workspace();
 
     using RawResult = kota::task<kota::codec::RawValue, kota::ipc::Error>;
 };

src/server/protocol.h

@@ -9,7 +9,7 @@
 
 #include "syntax/token.h"
 
-#include "kota/codec/raw_value.h"
+#include "kota/codec/json/json.h"
 #include "kota/ipc/lsp/protocol.h"
 #include "kota/ipc/protocol.h"
 

src/server/stateful_worker.cpp

@@ -94,6 +94,7 @@ class StatefulWorker {
     kota::task<kota::codec::RawValue> with_ast(llvm::StringRef path, F&& fn) {
         auto it = documents.find(path);
         if(it == documents.end()) {
+            LOG_WARN("with_ast: document not found: {}", path.str());
             co_return kota::codec::RawValue{"null"};
         }
 
@@ -105,8 +106,10 @@ class StatefulWorker {
         co_await doc->strand.lock();
 
         auto result = co_await kota::queue([&]() -> kota::codec::RawValue {
-            if(!doc->has_ast || (!doc->unit.completed() && !doc->unit.fatal_error()))
+            if(!doc->has_ast || (!doc->unit.completed() && !doc->unit.fatal_error())) {
+                LOG_WARN("with_ast: AST not available for {}", path.str());
                 return kota::codec::RawValue{"null"};
+            }
             return fn(*doc);
         });
 

src/server/stateless_worker.cpp

@@ -15,6 +15,22 @@
 
 namespace clice {
 
+/// RAII guard that lowers the current process's scheduling priority and
+/// restores it on destruction.
+struct ScopedNice {
+    int saved;
+
+    explicit ScopedNice(int increment = 10) {
+        auto p = kota::sys::priority();
+        saved = p ? *p : 0;
+        kota::sys::set_priority(saved + increment);
+    }
+
+    ~ScopedNice() {
+        kota::sys::set_priority(saved);
+    }
+};
+
 using kota::ipc::RequestResult;
 using RequestContext = kota::ipc::BincodePeer::RequestContext;
 
@@ -228,6 +244,8 @@ static worker::BuildResult handle_completion(const worker::BuildParams& params)
     cp.completion = {params.file, params.offset};
 
     auto items = feature::code_complete(cp);
+    if(items.empty())
+        LOG_DEBUG("Completion: no items returned for {}:{}", params.file, params.offset);
     LOG_DEBUG("Completion done: {} items, {}ms", items.size(), timer.ms());
 
     worker::BuildResult result;
@@ -251,7 +269,7 @@ static worker::BuildResult handle_signature_help(const worker::BuildParams& para
     cp.completion = {params.file, params.offset};
 
     auto help = feature::signature_help(cp);
-    LOG_DEBUG("SignatureHelp done: {}ms", timer.ms());
+    LOG_DEBUG("SignatureHelp done: {} signatures, {}ms", help.signatures.size(), timer.ms());
 
     worker::BuildResult result;
     result.result_json = to_raw(help);
@@ -283,7 +301,10 @@ int run_stateless_worker_mode(const std::string& worker_name, const std::string&
             switch(params.kind) {
                 case K::BuildPCH: return handle_build_pch(params);
                 case K::BuildPCM: return handle_build_pcm(params);
-                case K::Index: return handle_index(params);
+                case K::Index: {
+                    ScopedNice guard;
+                    return handle_index(params);
+                }
                 case K::Completion: return handle_completion(params);
                 case K::SignatureHelp: return handle_signature_help(params);
             }

src/server/worker_common.h

@@ -8,8 +8,7 @@
 
 #include "compile/compilation.h"
 
-#include "kota/codec/json/serializer.h"
-#include "kota/codec/raw_value.h"
+#include "kota/codec/json/json.h"
 #include "kota/ipc/codec/json.h"
 
 namespace clice {

src/server/worker_pool.cpp

@@ -13,14 +13,13 @@ namespace {
 
 /// Coroutine that drains a worker's stderr pipe.
 /// Workers write their own log files, so this only captures unexpected output
-/// (crash stacktraces, assertion failures, etc.) that bypasses spdlog.
+/// (crash stacktraces, assertion failures, sanitizer reports, etc.).
 kota::task<> drain_stderr(kota::pipe stderr_pipe, std::string prefix) {
     std::string buffer;
     while(true) {
         auto result = co_await stderr_pipe.read();
-        if(!result.has_value()) {
+        if(!result.has_value())
             break;
-        }
         auto& chunk = result.value();
         if(chunk.empty())
             break;
@@ -34,7 +33,7 @@ kota::task<> drain_stderr(kota::pipe stderr_pipe, std::string prefix) {
                 break;
             auto line = buffer.substr(pos, nl - pos);
             if(!line.empty()) {
-                LOG_DEBUG("{} {}", prefix, line);
+                LOG_WARN("{} {}", prefix, line);
             }
             pos = nl + 1;
         }
@@ -42,7 +41,7 @@ kota::task<> drain_stderr(kota::pipe stderr_pipe, std::string prefix) {
     }
 
     if(!buffer.empty()) {
-        LOG_DEBUG("{} {}", prefix, buffer);
+        LOG_WARN("{} {}", prefix, buffer);
     }
 }
 
@@ -108,24 +107,29 @@ bool WorkerPool::spawn_worker(const std::string& self_path,
     });
 
     auto& w = workers.back();
+    w.alive = true;
+    ++alive_count_;
     loop.schedule(w.peer->run());
 
     return true;
 }
 
 bool WorkerPool::start(const WorkerPoolOptions& options) {
+    options_ = options;
     log_dir_ = options.log_dir;
 
     for(std::uint32_t i = 0; i < options.stateless_count; ++i) {
         if(!spawn_worker(options.self_path, false, 0)) {
             return false;
         }
+        loop.schedule(monitor_worker(stateless_workers.size() - 1, false));
     }
 
     for(std::uint32_t i = 0; i < options.stateful_count; ++i) {
         if(!spawn_worker(options.self_path, true, options.worker_memory_limit)) {
             return false;
         }
+        loop.schedule(monitor_worker(stateful_workers.size() - 1, true));
     }
 
     // Register evicted notification handler for each stateful worker
@@ -145,29 +149,24 @@ bool WorkerPool::start(const WorkerPoolOptions& options) {
 
 kota::task<> WorkerPool::stop() {
     LOG_INFO("WorkerPool stopping...");
+    shutting_down_ = true;
 
-    // Close output pipes to signal workers to exit gracefully
-    for(auto& w: stateless_workers) {
+    // Close output pipes to signal workers to exit gracefully.
+    for(auto& w: stateless_workers)
         w.peer->close_output();
-    }
-    for(auto& w: stateful_workers) {
+    for(auto& w: stateful_workers)
         w.peer->close_output();
-    }
 
-    // Send SIGTERM to all workers
-    for(auto& w: stateless_workers) {
+    // Send SIGTERM.  monitor_worker coroutines handle the wait.
+    for(auto& w: stateless_workers)
         w.proc.kill(SIGTERM);
-    }
-    for(auto& w: stateful_workers) {
+    for(auto& w: stateful_workers)
         w.proc.kill(SIGTERM);
-    }
 
-    // Wait for all worker processes to exit
-    for(auto& w: stateless_workers) {
-        co_await w.proc.wait();
-    }
-    for(auto& w: stateful_workers) {
-        co_await w.proc.wait();
+    // Wait until all monitor_worker coroutines have finished.
+    if(alive_count_ > 0) {
+        all_exited_.reset();
+        co_await all_exited_.wait();
     }
 
     LOG_INFO("WorkerPool stopped");
@@ -198,7 +197,10 @@ std::size_t WorkerPool::assign_worker(std::uint32_t path_id) {
 std::size_t WorkerPool::pick_least_loaded() {
     std::size_t best = 0;
     for(std::size_t i = 1; i < stateful_workers.size(); ++i) {
-        if(stateful_workers[i].owned_documents < stateful_workers[best].owned_documents) {
+        if(!stateful_workers[i].alive)
+            continue;
+        if(!stateful_workers[best].alive ||
+           stateful_workers[i].owned_documents < stateful_workers[best].owned_documents) {
             best = i;
         }
     }
@@ -233,4 +235,127 @@ void WorkerPool::clear_owner(std::size_t worker_index) {
     }
 }
 
+kota::task<> WorkerPool::monitor_worker(std::size_t index, bool stateful) {
+    auto& workers = stateful ? stateful_workers : stateless_workers;
+    auto& w = workers[index];
+    auto name = std::string(stateful ? "SF-" : "SL-") + std::to_string(index);
+
+    auto result = co_await w.proc.wait();
+    w.alive = false;
+    --alive_count_;
+
+    if(shutting_down_) {
+        if(alive_count_ == 0)
+            all_exited_.set();
+        co_return;
+    }
+
+    if(result.has_value()) {
+        auto& exit = result.value();
+        if(exit.term_signal != 0) {
+            LOG_ERROR("Worker {} killed by signal {} (restarts: {})",
+                      name,
+                      exit.term_signal,
+                      w.restart_count);
+        } else {
+            LOG_ERROR("Worker {} exited with code {} (restarts: {})",
+                      name,
+                      exit.status,
+                      w.restart_count);
+        }
+    } else {
+        LOG_ERROR("Worker {} lost: {} (restarts: {})",
+                  name,
+                  result.error().message(),
+                  w.restart_count);
+    }
+
+    if(stateful)
+        clear_owner(index);
+
+    constexpr unsigned max_restarts = 5;
+    if(w.restart_count >= max_restarts) {
+        LOG_ERROR("Worker {} exceeded max restarts ({}), giving up", name, max_restarts);
+        co_return;
+    }
+
+    if(!respawn_worker(index, stateful)) {
+        LOG_ERROR("Worker {} respawn failed", name);
+    }
+}
+
+bool WorkerPool::respawn_worker(std::size_t index, bool stateful) {
+    auto& workers = stateful ? stateful_workers : stateless_workers;
+    auto old_restart_count = workers[index].restart_count + 1;
+    auto worker_name = std::string(stateful ? "SF-" : "SL-") + std::to_string(index);
+
+    // Close the old peer and retire it so its coroutines (run/write_loop)
+    // can finish naturally before the object is destroyed.
+    if(workers[index].peer) {
+        workers[index].peer->close();
+        retired_peers.push_back(std::move(workers[index].peer));
+    }
+
+    kota::process::options opts;
+    opts.file = options_.self_path;
+    if(stateful) {
+        opts.args = {options_.self_path,
+                     "--mode",
+                     "stateful-worker",
+                     "--worker-memory-limit",
+                     std::to_string(options_.worker_memory_limit)};
+    } else {
+        opts.args = {options_.self_path, "--mode", "stateless-worker"};
+    }
+    opts.args.push_back("--worker-name");
+    opts.args.push_back(worker_name);
+    if(!log_dir_.empty()) {
+        opts.args.push_back("--log-dir");
+        opts.args.push_back(log_dir_);
+    }
+    opts.streams = {
+        kota::process::stdio::pipe(true, false),
+        kota::process::stdio::pipe(false, true),
+        kota::process::stdio::pipe(false, true),
+    };
+
+    auto result = kota::process::spawn(opts, loop);
+    if(!result) {
+        LOG_ERROR("Failed to respawn worker {}: {}", worker_name, result.error().message());
+        return false;
+    }
+
+    auto& spawn = *result;
+    auto transport = std::make_unique<kota::ipc::StreamTransport>(std::move(spawn.stdout_pipe),
+                                                                  std::move(spawn.stdin_pipe));
+    auto peer = std::make_unique<kota::ipc::BincodePeer>(loop, std::move(transport));
+
+    std::string prefix = "[" + worker_name + "]";
+    loop.schedule(drain_stderr(std::move(spawn.stderr_pipe), prefix));
+
+    workers[index] = WorkerProcess{
+        .proc = std::move(spawn.proc),
+        .peer = std::move(peer),
+        .owned_documents = 0,
+        .alive = true,
+        .restart_count = old_restart_count,
+    };
+
+    auto& w = workers[index];
+    ++alive_count_;
+    loop.schedule(w.peer->run());
+
+    if(stateful) {
+        w.peer->on_notification([this](const worker::EvictedParams& params) {
+            if(on_evicted)
+                on_evicted(params.path);
+        });
+    }
+
+    loop.schedule(monitor_worker(index, stateful));
+
+    LOG_INFO("Worker {} restarted (attempt {})", worker_name, old_restart_count);
+    return true;
+}
+
 }  // namespace clice

src/server/worker_pool.h

@@ -64,6 +64,8 @@ private:
         kota::process proc;
         std::unique_ptr<kota::ipc::BincodePeer> peer;
         std::size_t owned_documents = 0;
+        bool alive = true;
+        unsigned restart_count = 0;
     };
 
     kota::event_loop& loop;
@@ -80,8 +82,19 @@ private:
     void clear_owner(std::size_t worker_index);
     std::size_t pick_least_loaded();
 
+    bool shutting_down_ = false;
+    std::size_t alive_count_ = 0;
+    kota::event all_exited_{true};  // Signalled when alive_count_ reaches 0.
+    WorkerPoolOptions options_;
     std::string log_dir_;
+
+    /// Peers moved here during respawn so their coroutines can finish
+    /// before the object is destroyed.
+    llvm::SmallVector<std::unique_ptr<kota::ipc::BincodePeer>> retired_peers;
+
     bool spawn_worker(const std::string& self_path, bool stateful, std::uint64_t memory_limit);
+    bool respawn_worker(std::size_t index, bool stateful);
+    kota::task<> monitor_worker(std::size_t index, bool stateful);
 };
 
 template <typename Params>
@@ -91,11 +104,10 @@ RequestResult<Params> WorkerPool::send_stateful(std::uint32_t path_id,
     if(stateful_workers.empty()) {
         co_return kota::outcome_error(kota::ipc::Error{"No stateful workers available"});
     }
-    // No timeout: compile tasks run as detached tasks (loop.schedule) that
-    // are immune to LSP $/cancelRequest.  Adding a timeout here would use
-    // kotatsu's with_token/when_any which has a spurious-cancellation bug
-    // that kills requests within milliseconds instead of the configured period.
     auto idx = assign_worker(path_id);
+    if(!stateful_workers[idx].alive) {
+        co_return kota::outcome_error(kota::ipc::Error{"Assigned stateful worker is down"});
+    }
     co_return co_await stateful_workers[idx].peer->send_request(params, opts);
 }
 
@@ -105,9 +117,16 @@ RequestResult<Params> WorkerPool::send_stateless(const Params& params,
     if(stateless_workers.empty()) {
         co_return kota::outcome_error(kota::ipc::Error{"No stateless workers available"});
     }
-    auto idx = next_stateless;
-    next_stateless = (next_stateless + 1) % stateless_workers.size();
-    co_return co_await stateless_workers[idx].peer->send_request(params, opts);
+    // Round-robin, skipping dead workers.
+    auto start = next_stateless;
+    for(std::size_t i = 0; i < stateless_workers.size(); ++i) {
+        auto idx = (start + i) % stateless_workers.size();
+        if(stateless_workers[idx].alive) {
+            next_stateless = (idx + 1) % stateless_workers.size();
+            co_return co_await stateless_workers[idx].peer->send_request(params, opts);
+        }
+    }
+    co_return kota::outcome_error(kota::ipc::Error{"All stateless workers are down"});
 }
 
 template <typename Params>
@@ -115,6 +134,8 @@ void WorkerPool::notify_stateful(std::uint32_t path_id, const Params& params) {
     auto it = owner.find(path_id);
     if(it == owner.end())
         return;
+    if(!stateful_workers[it->second].alive)
+        return;
     stateful_workers[it->second].peer->send_notification(params);
 }
 

src/server/workspace.cpp

@@ -183,10 +183,10 @@ struct CacheData {
 }  // namespace
 
 void Workspace::load_cache() {
-    if(config.cache_dir.empty())
+    if(config.project.cache_dir.empty())
         return;
 
-    auto cache_path = path::join(config.cache_dir, "cache", "cache.json");
+    auto cache_path = path::join(config.project.cache_dir, "cache", "cache.json");
     auto content = fs::read(cache_path);
     if(!content) {
         LOG_DEBUG("No cache.json found at {}", cache_path);
@@ -218,7 +218,7 @@ void Workspace::load_cache() {
     };
 
     for(auto& entry: data.pch) {
-        auto pch_path = path::join(config.cache_dir, "cache", "pch", entry.filename);
+        auto pch_path = path::join(config.project.cache_dir, "cache", "pch", entry.filename);
         auto source = resolve(entry.source_file);
         if(!llvm::sys::fs::exists(pch_path) || source.empty())
             continue;
@@ -234,7 +234,7 @@ void Workspace::load_cache() {
     }
 
     for(auto& entry: data.pcm) {
-        auto pcm_path = path::join(config.cache_dir, "cache", "pcm", entry.filename);
+        auto pcm_path = path::join(config.project.cache_dir, "cache", "pcm", entry.filename);
         auto source = resolve(entry.source_file);
         if(!llvm::sys::fs::exists(pcm_path) || source.empty())
             continue;
@@ -252,7 +252,7 @@ void Workspace::load_cache() {
 }
 
 void Workspace::save_cache() {
-    if(config.cache_dir.empty())
+    if(config.project.cache_dir.empty())
         return;
 
     CacheData data;
@@ -306,7 +306,7 @@ void Workspace::save_cache() {
         return;
     }
 
-    auto cache_path = path::join(config.cache_dir, "cache", "cache.json");
+    auto cache_path = path::join(config.project.cache_dir, "cache", "cache.json");
     auto tmp_path = cache_path + ".tmp";
     auto write_result = fs::write(tmp_path, *json_str);
     if(!write_result) {
@@ -321,14 +321,14 @@ void Workspace::save_cache() {
 }
 
 void Workspace::cleanup_cache(int max_age_days) {
-    if(config.cache_dir.empty())
+    if(config.project.cache_dir.empty())
         return;
 
     auto now = std::chrono::system_clock::now();
     auto max_age = std::chrono::hours(max_age_days * 24);
 
     for(auto* subdir: {"cache/pch", "cache/pcm"}) {
-        auto dir = path::join(config.cache_dir, subdir);
+        auto dir = path::join(config.project.cache_dir, subdir);
         std::error_code ec;
         for(auto it = llvm::sys::fs::directory_iterator(dir, ec);
             !ec && it != llvm::sys::fs::directory_iterator();

src/server/workspace.h

@@ -170,7 +170,7 @@ struct PCMState {
 ///   - didSave         (on_file_saved: rescan disk, cascade invalidation)
 ///   - Background index (merge TUIndex results from stateless workers)
 struct Workspace {
-    CliceConfig config;
+    Config config;
     CompilationDatabase cdb;
 
     PathPool path_pool;

src/support/glob_pattern.cpp

@@ -289,7 +289,7 @@ std::expected<GlobPattern::SubGlobPattern, std::string>
     return pat;
 }
 
-bool GlobPattern::match(llvm::StringRef str) {
+bool GlobPattern::match(llvm::StringRef str) const {
     if(!str.consume_front(prefix)) {
         return false;
     }

src/support/glob_pattern.h

@@ -54,7 +54,7 @@ public:
     }
 
     /// \returns \p true if \p str matches this glob pattern
-    bool match(llvm::StringRef s);
+    bool match(llvm::StringRef s) const;
 
 private:
     /// GlobPattern is seperated into `Prefix + SubGlobPattern`

src/syntax/dependency_graph.cpp

@@ -256,7 +256,8 @@ kota::task<> scan_impl(CompilationDatabase& cdb,
                        DependencyGraph& graph,
                        ScanReport& report,
                        ScanCache* ext_cache,
-                       kota::event_loop& loop) {
+                       kota::event_loop& loop,
+                       const RuleMatcher& rule_matcher) {
     auto start_time = std::chrono::steady_clock::now();
 
     // Reuse context groups and configs from cache when available (warm runs).
@@ -355,9 +356,19 @@ kota::task<> scan_impl(CompilationDatabase& cdb,
             std::uint32_t config_id = next_config_id++;
             context_to_config_id[context] = config_id;
             auto representative_path = path_pool.resolve(file_ids[0]);
+
+            // Apply per-file rules so that `[[rules]]`-modified -I/-isystem/-std
+            // flags are reflected in the search config used by the scan.
+            // Rules are applied to the representative file and assumed to hold
+            // for the whole context group (same CompilationInfo).
+            std::vector<std::string> rule_append, rule_remove;
+            if(rule_matcher)
+                rule_matcher(representative_path, rule_append, rule_remove);
+
             auto t0 = std::chrono::steady_clock::now();
-            configs[config_id] =
-                cdb.lookup_search_config(representative_path, {.query_toolchain = true});
+            configs[config_id] = cdb.lookup_search_config(
+                representative_path,
+                {.query_toolchain = true, .remove = rule_remove, .append = rule_append});
             auto t1 = std::chrono::steady_clock::now();
             lookup_us += std::chrono::duration_cast<std::chrono::microseconds>(t1 - t0).count();
         }
@@ -819,14 +830,15 @@ kota::task<> scan_impl(CompilationDatabase& cdb,
 ScanReport scan_dependency_graph(CompilationDatabase& cdb,
                                  PathPool& path_pool,
                                  DependencyGraph& graph,
-                                 ScanCache* cache) {
+                                 ScanCache* cache,
+                                 const RuleMatcher& rule_matcher) {
     ScanReport report;
     if(cdb.get_entries().empty()) {
         return report;
     }
 
     kota::event_loop loop;
-    loop.schedule(scan_impl(cdb, path_pool, graph, report, cache, loop));
+    loop.schedule(scan_impl(cdb, path_pool, graph, report, cache, loop, rule_matcher));
     loop.run();
     return report;
 }

src/syntax/dependency_graph.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <cstdint>
+#include <functional>
 #include <string>
 #include <vector>
 
@@ -253,6 +254,12 @@ struct ScanCache {
     std::vector<WaveEntry> initial_wave;
 };
 
+/// Callback for per-file rule-based flag modification. Given a file path,
+/// populates `append`/`remove` with rule-configured arguments so they can be
+/// layered on top of the CDB command when extracting the search config.
+using RuleMatcher = std::function<
+    void(llvm::StringRef path, std::vector<std::string>& append, std::vector<std::string>& remove)>;
+
 /// Run the wavefront BFS scan over all files in the compilation database.
 /// Internally creates a local event loop for async I/O (file reads via worker
 /// thread pool, stat calls via libuv). Blocks until the scan is complete.
@@ -261,9 +268,14 @@ struct ScanCache {
 ///               avoids repeated readdir() and include-resolution work across
 ///               successive calls.  PathPool must NOT be reset between calls
 ///               when a persistent cache is used (path_id values must remain stable).
+/// @param rule_matcher  Optional callback applied per context group so that
+///               `[[rules]]`-modified include/std flags are reflected in the
+///               dependency graph (otherwise rule-affected files would have
+///               stale resolution).
 ScanReport scan_dependency_graph(CompilationDatabase& cdb,
                                  PathPool& path_pool,
                                  DependencyGraph& graph,
-                                 ScanCache* cache = nullptr);
+                                 ScanCache* cache = nullptr,
+                                 const RuleMatcher& rule_matcher = {});
 
 }  // namespace clice

tests/conftest.py

@@ -10,6 +10,14 @@ import pytest
 from tests.integration.utils.client import CliceClient
 
 
+@pytest.hookimpl(tryfirst=True, hookwrapper=True)
+def pytest_runtest_makereport(item, call):
+    """Store test outcome so fixtures can detect failures."""
+    outcome = yield
+    rep = outcome.get_result()
+    setattr(item, f"rep_{rep.when}", rep)
+
+
 def pytest_addoption(parser: pytest.Parser) -> None:
     parser.addoption(
         "--executable",
@@ -75,7 +83,8 @@ def workspace(request: pytest.FixtureRequest, test_data_dir: Path) -> Path | Non
     """
     marker = request.node.get_closest_marker("workspace")
     if marker is None:
-        return None
+        yield None
+        return
     if not marker.args or not isinstance(marker.args[0], str):
         raise pytest.UsageError(
             "@pytest.mark.workspace requires a string argument, e.g. "
@@ -88,7 +97,10 @@ def workspace(request: pytest.FixtureRequest, test_data_dir: Path) -> Path | Non
     clice_dir = path / ".clice"
     if clice_dir.exists():
         shutil.rmtree(clice_dir)
-    return path
+    yield path
+    # Post-test cleanup: remove cache generated during the test.
+    if clice_dir.exists():
+        shutil.rmtree(clice_dir)
 
 
 @pytest.fixture
@@ -109,11 +121,21 @@ async def client(
     await c.start_io(*cmd)
 
     if workspace is not None:
-        await c.initialize(workspace)
+        init_options_marker = request.node.get_closest_marker("init_options")
+        init_options = dict(init_options_marker.args[0]) if init_options_marker else {}
+        # Force cache_dir into the workspace so .clice/ cleanup prevents stale PCH.
+        project = dict(init_options.get("project", {}))
+        project.setdefault("cache_dir", str(workspace / ".clice"))
+        init_options["project"] = project
+        await c.initialize(workspace, initialization_options=init_options)
 
     yield c
 
-    await _shutdown_client(c)
+    test_failed = (
+        getattr(request.node, "rep_call", None) is not None
+        and request.node.rep_call.failed
+    )
+    await _shutdown_client(c, verbose=test_failed)
 
 
 def generate_cdb(workspace: Path) -> None:
@@ -146,8 +168,12 @@ async def make_client(executable: Path, workspace: Path) -> CliceClient:
     return c
 
 
-async def _shutdown_client(c: CliceClient) -> None:
-    """Gracefully shut down a client, force-kill if needed."""
+async def _shutdown_client(c: CliceClient, *, verbose: bool = False) -> None:
+    """Gracefully shut down a client, force-kill if needed.
+
+    When verbose=True (typically on test failure), dump collected log messages
+    and server stderr to help diagnose the failure.
+    """
     try:
         await asyncio.wait_for(c.shutdown_async(None), timeout=3.0)
     except Exception:
@@ -163,15 +189,25 @@ async def _shutdown_client(c: CliceClient) -> None:
 
     try:
         server = getattr(c, "_server", None)
-        if server and server.stderr:
-            stderr_data = await asyncio.wait_for(server.stderr.read(), timeout=2.0)
-            if stderr_data:
-                for line in stderr_data.decode("utf-8", errors="replace").splitlines():
-                    if "[warn]" in line or "[error]" in line:
-                        print(f"[server] {line}", flush=True)
+        if server:
+            if server.returncode is not None:
+                print(f"[server] exit code: {server.returncode}", flush=True)
+            if server.stderr:
+                stderr_data = await asyncio.wait_for(server.stderr.read(), timeout=2.0)
+                if stderr_data:
+                    for line in stderr_data.decode(
+                        "utf-8", errors="replace"
+                    ).splitlines():
+                        if "[warn]" in line or "[error]" in line or "Sanitizer" in line:
+                            print(f"[server] {line}", flush=True)
     except Exception:
         pass
 
+    if verbose and c.log_messages:
+        for msg in c.log_messages:
+            level = {1: "ERROR", 2: "WARN", 3: "INFO", 4: "LOG"}.get(msg.type, "?")
+            print(f"[logMessage/{level}] {msg.message}", flush=True)
+
     try:
         c._stop_event.set()
         for task in c._async_tasks:
@@ -239,6 +275,15 @@ def _generate_test_data_cdbs(data_dir: Path) -> None:
             dl_dir, [_entry(dl_dir, dl_main, [f"-I{dl_dir.as_posix()}", "-std=c++23"])]
         )
 
+    # config_rules_toml / config_rules_no_config — rules tests must start
+    # from a CDB that does NOT include the flag the rule will append, so the
+    # rule's effect is observable through diagnostics.
+    for name in ("config_rules_toml", "config_rules_no_config"):
+        cr_dir = data_dir / name
+        cr_main = cr_dir / "main.cpp"
+        if cr_main.exists():
+            _write(cr_dir, [_entry(cr_dir, cr_main)])
+
     # pch_test
     pt_dir = data_dir / "pch_test"
     if pt_dir.exists():

tests/data/config_rules_no_config/main.cpp

@@ -0,0 +1,7 @@
+int value() {
+    return FROM_INIT;
+}
+
+int main() {
+    return value();
+}

tests/data/config_rules_toml/clice.toml

@@ -0,0 +1,3 @@
+[[rules]]
+patterns = ["**/*.cpp"]
+append = ["-DFROM_TOML"]

tests/data/config_rules_toml/main.cpp

@@ -0,0 +1,7 @@
+int value() {
+    return FROM_TOML;
+}
+
+int main() {
+    return value();
+}

tests/integration/compilation/test_persistent_cache.py

@@ -16,6 +16,7 @@ from lsprotocol.types import (
 
 from tests.conftest import make_client, shutdown_client
 from tests.integration.utils import write_cdb, doc
+from tests.integration.utils.wait import MTIME_GRANULARITY, SETTLE_TIME
 from tests.integration.utils.cache import (
     list_pch_files,
     list_pcm_files,
@@ -24,9 +25,17 @@ from tests.integration.utils.cache import (
 from tests.integration.utils.assertions import assert_clean_compile
 
 
+def _pin_cache_to_workspace(tmp_path):
+    """Write a clice.toml that pins cache_dir to <workspace>/.clice/."""
+    (tmp_path / "clice.toml").write_text(
+        '[project]\ncache_dir = "${workspace}/.clice"\n'
+    )
+
+
 async def test_pch_written_to_cache_dir(client, tmp_path):
     """After opening a file with #include, a .pch file should appear
     in .clice/cache/pch/ with a hex-hash filename."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "header.h").write_text("#pragma once\nstruct Foo { int x; };\n")
     (tmp_path / "main.cpp").write_text(
         '#include "header.h"\nint main() { Foo f; return f.x; }\n'
@@ -48,6 +57,7 @@ async def test_pch_written_to_cache_dir(client, tmp_path):
 
 async def test_cache_json_persisted(client, tmp_path):
     """After a PCH build, cache.json should be written with the entry."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "header.h").write_text("#pragma once\nint global_val = 42;\n")
     (tmp_path / "main.cpp").write_text(
         '#include "header.h"\nint main() { return global_val; }\n'
@@ -74,6 +84,7 @@ async def test_cache_json_persisted(client, tmp_path):
 async def test_pch_reused_on_close_reopen(client, tmp_path):
     """Closing and reopening a file within the same session should reuse
     the cached PCH — no additional .pch files should be created."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "header.h").write_text("#pragma once\nstruct Bar { int y; };\n")
     (tmp_path / "main.cpp").write_text(
         '#include "header.h"\nint main() { Bar b; return b.y; }\n'
@@ -90,7 +101,7 @@ async def test_pch_reused_on_close_reopen(client, tmp_path):
 
     # Close.
     client.text_document_did_close(DidCloseTextDocumentParams(text_document=doc(uri)))
-    await asyncio.sleep(0.5)
+    await asyncio.sleep(SETTLE_TIME)
 
     # Clear diagnostics so we can wait for fresh ones.
     client.diagnostics.pop(uri, None)
@@ -108,6 +119,7 @@ async def test_pch_reused_on_close_reopen(client, tmp_path):
 async def test_pch_survives_server_restart(executable, tmp_path):
     """PCH cache should survive a full server restart — cache.json is
     loaded on startup and the existing .pch file is reused."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "header.h").write_text("#pragma once\nstruct Baz { int z; };\n")
     (tmp_path / "main.cpp").write_text(
         '#include "header.h"\nint main() { Baz b; return b.z; }\n'
@@ -150,6 +162,7 @@ async def test_pch_survives_server_restart(executable, tmp_path):
 async def test_shared_preamble_shares_pch(client, tmp_path):
     """Two files with identical preambles should share the same PCH file
     (content-addressed by preamble hash)."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "header.h").write_text("#pragma once\nint shared_val = 1;\n")
     (tmp_path / "a.cpp").write_text(
         '#include "header.h"\nint fa() { return shared_val; }\n'
@@ -176,6 +189,7 @@ async def test_shared_preamble_shares_pch(client, tmp_path):
 
 async def test_different_preamble_different_pch(client, tmp_path):
     """Files with different preambles should produce different PCH files."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "a.h").write_text("#pragma once\nint val_a = 1;\n")
     (tmp_path / "b.h").write_text("#pragma once\nint val_b = 2;\n")
     (tmp_path / "a.cpp").write_text('#include "a.h"\nint fa() { return val_a; }\n')
@@ -199,6 +213,7 @@ async def test_different_preamble_different_pch(client, tmp_path):
 async def test_pch_rebuilt_on_header_change(client, tmp_path):
     """When a preamble header changes, a new PCH should be built
     (different hash → different filename). The old one remains for cleanup."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "header.h").write_text("#pragma once\nstruct V1 { int a; };\n")
     (tmp_path / "main.cpp").write_text(
         '#include "header.h"\nint main() { V1 v; return v.a; }\n'
@@ -213,7 +228,7 @@ async def test_pch_rebuilt_on_header_change(client, tmp_path):
     assert len(pch_before) >= 1
 
     # Modify header — changes preamble content hash.
-    await asyncio.sleep(1.1)
+    await asyncio.sleep(MTIME_GRANULARITY)
     (tmp_path / "header.h").write_text("#pragma once\nstruct V2 { int b; };\n")
     # Also update main.cpp to use V2 so it compiles cleanly.
     (tmp_path / "main.cpp").write_text(
@@ -222,7 +237,7 @@ async def test_pch_rebuilt_on_header_change(client, tmp_path):
 
     # Close and reopen to get fresh preamble.
     client.text_document_did_close(DidCloseTextDocumentParams(text_document=doc(uri)))
-    await asyncio.sleep(0.5)
+    await asyncio.sleep(SETTLE_TIME)
     client.diagnostics.pop(uri, None)
 
     uri2, _ = await client.open_and_wait(tmp_path / "main.cpp")
@@ -240,6 +255,7 @@ async def test_pch_rebuilt_on_header_change(client, tmp_path):
 
 async def test_no_tmp_files_after_build(client, tmp_path):
     """After a successful PCH build, no .tmp files should remain in the cache dir."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "header.h").write_text("#pragma once\nint val = 1;\n")
     (tmp_path / "main.cpp").write_text(
         '#include "header.h"\nint main() { return val; }\n'
@@ -265,6 +281,7 @@ async def test_no_tmp_files_after_build(client, tmp_path):
 async def test_cache_dirs_created_on_startup(client, tmp_path):
     """The .clice/cache/pch/ and .clice/cache/pcm/ directories should be created
     when the server initializes a workspace."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "main.cpp").write_text("int main() { return 0; }\n")
     write_cdb(tmp_path, ["main.cpp"])
     await client.initialize(tmp_path)

tests/integration/compilation/test_staleness.py

@@ -21,7 +21,7 @@ from lsprotocol.types import (
 )
 
 from tests.integration.utils import write_cdb, doc
-from tests.integration.utils.wait import wait_for_recompile
+from tests.integration.utils.wait import MTIME_GRANULARITY, wait_for_recompile
 from tests.integration.utils.assertions import assert_clean_compile, assert_has_errors
 
 
@@ -42,7 +42,7 @@ async def test_header_change_invalidates_ast(client, tmp_path):
 
     # Modify header on disk — introduce an error.
     # Ensure mtime advances past filesystem granularity (1s on some FSes).
-    await asyncio.sleep(1.1)
+    await asyncio.sleep(MTIME_GRANULARITY)
     (tmp_path / "header.h").write_text(
         "inline int value() { return }\n"
     )  # syntax error
@@ -71,7 +71,7 @@ async def test_header_change_invalidates_pch(client, tmp_path):
 
     # Modify header — rename struct field.
     # Ensure mtime advances past filesystem granularity (1s on some FSes).
-    await asyncio.sleep(1.1)
+    await asyncio.sleep(MTIME_GRANULARITY)
     (tmp_path / "header.h").write_text(
         "#pragma once\nstruct Foo { int y; };\n"  # x -> y
     )
@@ -115,16 +115,22 @@ async def test_touch_without_content_change_skips_recompile(client, tmp_path):
     assert_clean_compile(client, uri)
 
     # Touch the header — mtime changes but content stays the same.
-    await asyncio.sleep(1.1)
+    await asyncio.sleep(MTIME_GRANULARITY)
     original_content = (tmp_path / "header.h").read_text()
     (tmp_path / "header.h").write_text(original_content)
 
     # Hover triggers ensure_compiled which runs deps_changed.
     # Layer 2 hash confirms nothing actually changed → cached AST reused.
-    # Hover on "main" (line 1, col 4) which should be hoverable.
-    hover = await client.text_document_hover_async(
-        HoverParams(text_document=doc(uri), position=Position(line=1, character=4))
-    )
+    # The first hover may see ast_dirty=true (mtime changed, hash check in progress),
+    # so retry to let the hash check complete.
+    hover = None
+    for _ in range(3):
+        hover = await client.text_document_hover_async(
+            HoverParams(text_document=doc(uri), position=Position(line=1, character=4))
+        )
+        if hover is not None:
+            break
+        await asyncio.sleep(SETTLE_TIME)
     assert hover is not None
 
     # No new diagnostics should appear — the file is still clean.
@@ -145,7 +151,7 @@ async def test_header_replaced_with_different_content(client, tmp_path):
     assert_clean_compile(client, uri)
 
     # Replace header — delete and recreate with a breaking change.
-    await asyncio.sleep(1.1)
+    await asyncio.sleep(MTIME_GRANULARITY)
     (tmp_path / "header.h").unlink()
     (tmp_path / "header.h").write_text("inline int renamed_value() { return 1; }\n")
 
@@ -170,7 +176,7 @@ async def test_fix_error_clears_diagnostics(client, tmp_path):
     assert_has_errors(client, uri, "Expected diagnostics from broken header")
 
     # Fix the header.
-    await asyncio.sleep(1.1)
+    await asyncio.sleep(MTIME_GRANULARITY)
     (tmp_path / "header.h").write_text("inline int value() { return 1; }\n")
 
     # Hover triggers recompilation — diagnostics should clear.
@@ -198,7 +204,7 @@ async def test_multiple_files_share_header(client, tmp_path):
     assert_clean_compile(client, uri_b)
 
     # Break the shared header.
-    await asyncio.sleep(1.1)
+    await asyncio.sleep(MTIME_GRANULARITY)
     (tmp_path / "shared.h").write_text("inline int shared() { return }\n")
 
     # Both files should get diagnostics after hover.
@@ -223,7 +229,7 @@ async def test_transitive_header_change(client, tmp_path):
     assert_clean_compile(client, uri)
 
     # Modify the transitive dep (base.h).
-    await asyncio.sleep(1.1)
+    await asyncio.sleep(MTIME_GRANULARITY)
     (tmp_path / "base.h").write_text("inline int base() { return }\n")  # broken
 
     await wait_for_recompile(client, uri)
@@ -310,7 +316,7 @@ async def test_didclose_then_reopen(client, tmp_path):
     client.text_document_did_close(DidCloseTextDocumentParams(text_document=doc(uri)))
 
     # Modify on disk while closed.
-    await asyncio.sleep(1.1)
+    await asyncio.sleep(MTIME_GRANULARITY)
     (tmp_path / "main.cpp").write_text("int main() { return }\n")  # broken
 
     # Reopen — should compile the new (broken) content from disk.
@@ -321,7 +327,7 @@ async def test_didclose_then_reopen(client, tmp_path):
 
 
 async def test_didclose_clears_hover(client, tmp_path):
-    """After didClose, hover on the closed file should return None."""
+    """After didClose, hover on the closed file should return an error."""
     (tmp_path / "main.cpp").write_text("int main() { return 0; }\n")
     write_cdb(tmp_path, ["main.cpp"])
     await client.initialize(tmp_path)
@@ -330,10 +336,10 @@ async def test_didclose_clears_hover(client, tmp_path):
 
     client.text_document_did_close(DidCloseTextDocumentParams(text_document=doc(uri)))
 
-    hover = await client.text_document_hover_async(
-        HoverParams(text_document=doc(uri), position=Position(line=0, character=4))
-    )
-    assert hover is None, "Hover on closed file should return None"
+    with pytest.raises(Exception, match="Document not open"):
+        await client.text_document_hover_async(
+            HoverParams(text_document=doc(uri), position=Position(line=0, character=4))
+        )
 
 
 async def test_didsave_triggers_recompile_for_dependents(client, tmp_path):
@@ -349,7 +355,7 @@ async def test_didsave_triggers_recompile_for_dependents(client, tmp_path):
     assert_clean_compile(client, uri)
 
     # Modify header on disk and send didSave.
-    await asyncio.sleep(1.1)
+    await asyncio.sleep(MTIME_GRANULARITY)
     (tmp_path / "header.h").write_text("inline int value() { return }\n")  # broken
     client.text_document_did_save(
         DidSaveTextDocumentParams(

tests/integration/features/test_server.py

@@ -10,6 +10,7 @@ from lsprotocol.types import (
 )
 
 from tests.integration.utils import doc
+from tests.integration.utils.wait import SETTLE_TIME
 from tests.integration.utils.workspace import did_change
 
 
@@ -70,7 +71,7 @@ async def test_semantic_token_modifier_legend(client, workspace):
 @pytest.mark.workspace("hello_world")
 async def test_did_open_close_cycle(client, workspace):
     uri, _ = client.open(workspace / "main.cpp")
-    await asyncio.sleep(0.5)
+    await asyncio.sleep(SETTLE_TIME)
     client.close(uri)
 
 
@@ -83,8 +84,8 @@ async def test_shutdown_exit(client, workspace):
 async def test_feature_requests_after_close(client, workspace):
     uri, _ = client.open(workspace / "main.cpp")
     client.close(uri)
-    result = await client.hover_at(uri, 0, 0)
-    assert result is None
+    with pytest.raises(Exception, match="Document not open"):
+        await client.hover_at(uri, 0, 0)
 
 
 @pytest.mark.workspace("hello_world")
@@ -94,7 +95,7 @@ async def test_incremental_change(client, workspace):
         content += f"\n// change {i}"
         did_change(client, uri, i + 1, content)
         await asyncio.sleep(0.05)
-    await asyncio.sleep(1)
+    await asyncio.sleep(SETTLE_TIME * 2)
     client.close(uri)
 
 
@@ -191,23 +192,23 @@ async def test_rapid_changes_stress(client, workspace):
     for i in range(20):
         content += f"\n// stress change {i}\n"
         did_change(client, uri, i + 1, content)
-    await asyncio.sleep(2)
+    await asyncio.sleep(SETTLE_TIME * 2)
     client.close(uri)
 
 
 @pytest.mark.workspace("hello_world")
 async def test_save_notification(client, workspace):
     uri, _ = client.open(workspace / "main.cpp")
-    await asyncio.sleep(0.5)
+    await asyncio.sleep(SETTLE_TIME)
     client.text_document_did_save(DidSaveTextDocumentParams(text_document=doc(uri)))
-    await asyncio.sleep(0.5)
+    await asyncio.sleep(SETTLE_TIME)
     client.close(uri)
 
 
 @pytest.mark.workspace("hello_world")
 async def test_hover_on_unknown_file(client, workspace):
-    result = await client.hover_at("file:///nonexistent/fake.cpp", 0, 0)
-    assert result is None
+    with pytest.raises(Exception, match="Document not open"):
+        await client.hover_at("file:///nonexistent/fake.cpp", 0, 0)
 
 
 @pytest.mark.workspace("hello_world")

tests/integration/lifecycle/test_config.py

@@ -0,0 +1,68 @@
+"""Integration tests for clice configuration (clice.toml + initializationOptions).
+
+Each workspace's main.cpp references a macro that is only defined when the
+rule's `-D<macro>=...` is applied. When rules are applied, compilation is
+clean; otherwise an undeclared-identifier diagnostic surfaces.
+"""
+
+import pytest
+
+from tests.integration.utils.assertions import (
+    assert_clean_compile,
+    assert_has_errors,
+    get_errors,
+)
+
+
+@pytest.mark.workspace("config_rules_no_config")
+async def test_baseline_without_rules(client, workspace):
+    uri, _ = await client.open_and_wait(workspace / "main.cpp")
+    assert_has_errors(client, uri, "Expected diagnostics without any rules applied")
+    errors = get_errors(client.diagnostics[uri])
+    assert any("FROM_INIT" in (d.message or "") for d in errors), (
+        f"Expected a diagnostic referencing FROM_INIT, got: {errors}"
+    )
+
+
+@pytest.mark.workspace("config_rules_toml")
+async def test_rules_from_toml(client, workspace):
+    uri, _ = await client.open_and_wait(workspace / "main.cpp")
+    assert_clean_compile(client, uri)
+
+    symbols = await client.document_symbols(uri)
+    assert symbols, "Expected document symbols for value()/main()"
+    hover = await client.hover_at(uri, line=4, character=4)  # on 'main'
+    assert hover is not None
+
+
+@pytest.mark.workspace("config_rules_no_config")
+@pytest.mark.init_options(
+    {"rules": [{"patterns": ["**/*.cpp"], "append": ["-DFROM_INIT=1"]}]}
+)
+async def test_rules_from_init_options(client, workspace):
+    uri, _ = await client.open_and_wait(workspace / "main.cpp")
+    assert_clean_compile(client, uri)
+
+
+@pytest.mark.workspace("config_rules_toml")
+@pytest.mark.init_options(
+    {"rules": [{"patterns": ["**/*.cpp"], "append": ["-DUNRELATED"]}]}
+)
+async def test_init_options_replaces_toml_rules(client, workspace):
+    uri, _ = await client.open_and_wait(workspace / "main.cpp")
+    assert_has_errors(
+        client, uri, "initializationOptions should have overridden clice.toml rules"
+    )
+    errors = get_errors(client.diagnostics[uri])
+    assert any("FROM_TOML" in (d.message or "") for d in errors), (
+        f"Expected FROM_TOML diagnostic after override, got: {errors}"
+    )
+
+
+@pytest.mark.workspace("config_rules_no_config")
+@pytest.mark.init_options(
+    {"rules": [{"patterns": ["**/does_not_match.cpp"], "append": ["-DFROM_INIT=1"]}]}
+)
+async def test_rules_pattern_mismatch(client, workspace):
+    uri, _ = await client.open_and_wait(workspace / "main.cpp")
+    assert_has_errors(client, uri, "Rule pattern should not have matched main.cpp")

tests/integration/lifecycle/test_file_operation.py

@@ -13,13 +13,14 @@ from lsprotocol.types import (
 )
 
 from tests.integration.utils import doc
+from tests.integration.utils.wait import IDLE_TIMEOUT
 from tests.integration.utils.workspace import did_change
 
 
 @pytest.mark.workspace("hello_world")
 async def test_did_open(client, workspace):
     client.open(workspace / "main.cpp")
-    await asyncio.sleep(5)
+    await asyncio.sleep(IDLE_TIMEOUT)
 
 
 @pytest.mark.workspace("hello_world")
@@ -29,13 +30,13 @@ async def test_did_change(client, workspace):
         content += "\n"
         await asyncio.sleep(0.2)
         did_change(client, uri, i + 1, content)
-    await asyncio.sleep(5)
+    await asyncio.sleep(IDLE_TIMEOUT)
 
 
 @pytest.mark.workspace("clang_tidy")
 async def test_clang_tidy(client, workspace):
     client.open(workspace / "main.cpp")
-    await asyncio.sleep(5)
+    await asyncio.sleep(IDLE_TIMEOUT)
 
 
 @pytest.mark.workspace("hello_world")
@@ -56,7 +57,7 @@ async def test_hover_save_close(client, workspace):
         )
     )
     client.text_document_did_close(DidCloseTextDocumentParams(text_document=doc(uri)))
-    closed_hover = await client.text_document_hover_async(
-        HoverParams(text_document=doc(uri), position=Position(line=0, character=0))
-    )
-    assert closed_hover is None
+    with pytest.raises(Exception, match="Document not open"):
+        await client.text_document_hover_async(
+            HoverParams(text_document=doc(uri), position=Position(line=0, character=0))
+        )

tests/integration/modules/test_modules.py

@@ -14,6 +14,7 @@ from lsprotocol.types import (
 )
 
 from tests.integration.utils.assertions import assert_clean_compile, assert_has_errors
+from tests.integration.utils.wait import IDLE_TIMEOUT
 
 
 @pytest.mark.workspace("modules/single_module_no_deps")
@@ -267,7 +268,7 @@ async def test_circular_module_dependency(client, workspace):
     the server remains responsive by opening a non-cyclic file afterwards.
     """
     client.open(workspace / "cycle_a.cppm")
-    await asyncio.sleep(5.0)
+    await asyncio.sleep(IDLE_TIMEOUT)
 
     uri_ok, _ = await client.open_and_wait(workspace / "ok.cppm")
     diags = client.diagnostics.get(uri_ok, [])

tests/integration/stress/test_rapid_edit.py

@@ -10,6 +10,7 @@ from lsprotocol.types import (
 )
 
 from tests.integration.utils import doc
+from tests.integration.utils.wait import SETTLE_TIME
 from tests.integration.utils.workspace import did_change
 
 
@@ -53,7 +54,7 @@ async def test_rapid_edits_with_hover(client, workspace):
         await asyncio.sleep(0.02)  # ~20ms between edits
 
     # Wait a moment for in-flight requests to settle.
-    await asyncio.sleep(1.0)
+    await asyncio.sleep(SETTLE_TIME * 2)
 
     # Final hover must succeed and return correct result.
     final_hover = await asyncio.wait_for(

tests/integration/utils/assertions.py

@@ -1,6 +1,6 @@
-"""Diagnostic assertion helpers for integration tests."""
+"""Diagnostic and log message assertion helpers for integration tests."""
 
-from lsprotocol.types import Diagnostic, DiagnosticSeverity
+from lsprotocol.types import Diagnostic, DiagnosticSeverity, MessageType
 
 
 def get_errors(diagnostics: list[Diagnostic]) -> list[Diagnostic]:
@@ -48,3 +48,23 @@ def assert_clean_compile(client, uri: str) -> None:
     """Assert the file compiled without any diagnostics at all."""
     diags = client.diagnostics.get(uri, [])
     assert len(diags) == 0, f"Expected clean compile, got: {diags}"
+
+
+def has_log_message(
+    client, substring: str, *, severity: MessageType | None = None
+) -> bool:
+    """Check if any log message contains the given substring."""
+    for msg in client.log_messages:
+        if severity is not None and msg.type != severity:
+            continue
+        if substring in msg.message:
+            return True
+    return False
+
+
+def assert_no_log_errors(client) -> None:
+    """Assert that no error-level log messages were received."""
+    errors = [m for m in client.log_messages if m.type == MessageType.Error]
+    assert len(errors) == 0, (
+        f"Expected no log errors, got: {[e.message for e in errors]}"
+    )

tests/integration/utils/client.py

@@ -7,6 +7,7 @@ from urllib.parse import unquote
 from lsprotocol.types import (
     PROGRESS,
     TEXT_DOCUMENT_PUBLISH_DIAGNOSTICS,
+    WINDOW_LOG_MESSAGE,
     WINDOW_WORK_DONE_PROGRESS_CREATE,
     ClientCapabilities,
     CodeActionContext,
@@ -24,6 +25,7 @@ from lsprotocol.types import (
     InitializeParams,
     InitializeResult,
     InitializedParams,
+    LogMessageParams,
     Position,
     ProgressParams,
     PublishDiagnosticsParams,
@@ -48,6 +50,7 @@ class CliceClient(BaseLanguageClient):
         super().__init__("clice-test-client", "0.1.0")
         self.diagnostics: dict[str, list[Diagnostic]] = {}
         self.diagnostics_events: dict[str, asyncio.Event] = {}
+        self.log_messages: list[LogMessageParams] = []
         self.progress_tokens: list[str] = []
         self.progress_events: list[dict] = []
         self.init_result: InitializeResult | None = None
@@ -64,6 +67,10 @@ class CliceClient(BaseLanguageClient):
                 if key in self.diagnostics_events:
                     self.diagnostics_events[key].set()
 
+        @self.feature(WINDOW_LOG_MESSAGE)
+        def on_log_message(params: LogMessageParams) -> None:
+            self.log_messages.append(params)
+
         @self.feature(WINDOW_WORK_DONE_PROGRESS_CREATE)
         def on_create_progress(params: WorkDoneProgressCreateParams) -> None:
             token = str(params.token) if isinstance(params.token, int) else params.token
@@ -86,16 +93,20 @@ class CliceClient(BaseLanguageClient):
 
     # ── Lifecycle ────────────────────────────────────────────────────
 
-    async def initialize(self, workspace: Path) -> InitializeResult:
-        result = await self.initialize_async(
-            InitializeParams(
-                capabilities=ClientCapabilities(),
-                root_uri=workspace.as_uri(),
-                workspace_folders=[
-                    WorkspaceFolder(uri=workspace.as_uri(), name="test")
-                ],
-            )
+    async def initialize(
+        self,
+        workspace: Path,
+        *,
+        initialization_options: dict | None = None,
+    ) -> InitializeResult:
+        params = InitializeParams(
+            capabilities=ClientCapabilities(),
+            root_uri=workspace.as_uri(),
+            workspace_folders=[WorkspaceFolder(uri=workspace.as_uri(), name="test")],
         )
+        if initialization_options is not None:
+            params.initialization_options = initialization_options
+        result = await self.initialize_async(params)
         self.initialized(InitializedParams())
         self.init_result = result
         return result

tests/integration/utils/wait.py

@@ -9,6 +9,11 @@ from lsprotocol.types import (
     WorkspaceSymbolParams,
 )
 
+# Standard timing constants — use these instead of hardcoded sleep values.
+MTIME_GRANULARITY = 1.1  # Filesystem mtime precision (1s on many FSes, +0.1 margin)
+SETTLE_TIME = 0.5  # Time for server to stabilize after an operation
+IDLE_TIMEOUT = 5.0  # Time to wait for server idle in lifecycle tests
+
 
 async def wait_for_recompile(client, uri: str, *, timeout: float = 60.0) -> None:
     """Trigger recompilation via hover and wait for fresh diagnostics.

tests/pytest.ini

@@ -1,3 +1,5 @@
 [pytest]
 asyncio_mode = auto
-markers = workspace
+markers =
+    workspace
+    init_options

tests/replay.py

@@ -13,6 +13,9 @@ import re
 import signal
 import sys
 import time
+
+# Force line-buffered stdout so CI sees output immediately.
+sys.stdout.reconfigure(line_buffering=True)
 from pathlib import Path
 from urllib.parse import quote, unquote
 
@@ -109,7 +112,9 @@ async def write_lsp_message(writer: asyncio.StreamWriter, payload: str):
     await writer.drain()
 
 
-async def replay_one(trace_path: Path, clice_bin: Path, timeout: int) -> bool | None:
+async def replay_one(
+    trace_path: Path, clice_bin: Path, timeout: int, wall_timeout: int = 300
+) -> bool | None:
     """Replay a single trace. Returns True=PASS, False=FAIL, None=SKIP."""
     records = load_trace(trace_path)
     if not records:
@@ -179,8 +184,21 @@ async def replay_one(trace_path: Path, clice_bin: Path, timeout: int) -> bool |
     last_method = None
     sent_count = 0
 
+    wall_deadline = wall_start + wall_timeout
+
+    def remaining_wall():
+        return max(0, wall_deadline - time.monotonic())
+
     try:
         for i, rec in enumerate(records):
+            if remaining_wall() <= 0:
+                elapsed = time.monotonic() - wall_start
+                print(
+                    f"  result: TIMEOUT (wall-clock {wall_timeout}s exceeded, {elapsed:.1f}s)"
+                )
+                success = False
+                break
+
             if i > 0:
                 delay = rec["ts"] - records[i - 1]["ts"]
                 if delay > 0:
@@ -196,7 +214,7 @@ async def replay_one(trace_path: Path, clice_bin: Path, timeout: int) -> bool |
                 try:
                     await asyncio.wait_for(
                         asyncio.gather(*pending.values(), return_exceptions=True),
-                        timeout=timeout,
+                        timeout=min(timeout, remaining_wall()),
                     )
                 except asyncio.TimeoutError:
                     elapsed = time.monotonic() - wall_start
@@ -210,7 +228,19 @@ async def replay_one(trace_path: Path, clice_bin: Path, timeout: int) -> bool |
             if msg_id is not None and method is not None:
                 pending[msg_id] = asyncio.get_event_loop().create_future()
 
-            await write_lsp_message(proc.stdin, rec["msg"])
+            try:
+                await asyncio.wait_for(
+                    write_lsp_message(proc.stdin, rec["msg"]),
+                    timeout=min(30, remaining_wall()),
+                )
+            except asyncio.TimeoutError:
+                elapsed = time.monotonic() - wall_start
+                print(
+                    f"  result: HANG (write blocked at {last_method},"
+                    f" sent={sent_count}/{len(records)}, {elapsed:.1f}s)"
+                )
+                success = False
+                break
             sent_count = i + 1
 
     except (ConnectionError, BrokenPipeError):
@@ -231,7 +261,7 @@ async def replay_one(trace_path: Path, clice_bin: Path, timeout: int) -> bool |
         try:
             await asyncio.wait_for(
                 asyncio.gather(*pending.values(), return_exceptions=True),
-                timeout=timeout,
+                timeout=min(timeout, remaining_wall()),
             )
         except asyncio.TimeoutError:
             elapsed = time.monotonic() - wall_start
@@ -294,7 +324,7 @@ async def async_main(args):
             print(f"SKIP: {trace} (not found)")
             skipped += 1
             continue
-        result = await replay_one(trace, args.clice, args.timeout)
+        result = await replay_one(trace, args.clice, args.timeout, args.wall_timeout)
         if result is None:
             skipped += 1
         elif result:
@@ -317,7 +347,16 @@ def main():
     p.add_argument("traces", nargs="+", type=Path, help="JSONL trace files")
     p.add_argument("--clice", required=True, type=Path, help="Path to clice binary")
     p.add_argument(
-        "--timeout", type=int, default=120, help="Timeout in seconds (default: 120)"
+        "--timeout",
+        type=int,
+        default=120,
+        help="Per-request timeout in seconds (default: 120)",
+    )
+    p.add_argument(
+        "--wall-timeout",
+        type=int,
+        default=300,
+        help="Max wall-clock time per trace in seconds (default: 300)",
     )
     args = p.parse_args()
     sys.exit(asyncio.run(async_main(args)))

tests/unit/feature/code_completion_tests.cpp

@@ -233,6 +233,33 @@ void bar() {
     }
 }
 
+TEST_CASE(DeprecatedTag) {
+    code_complete(R"cpp(
+[[deprecated]] int foooo(int x);
+int z = fo$(pos)
+)cpp");
+
+    auto it = find_item("foooo");
+    ASSERT_TRUE(it != items.end());
+    ASSERT_TRUE(it->tags.has_value());
+    auto& tags = *it->tags;
+    ASSERT_TRUE(std::ranges::find(tags, protocol::CompletionItemTag::Deprecated) != tags.end());
+}
+
+TEST_CASE(NotDeprecated) {
+    code_complete(R"cpp(
+int foooo(int x);
+int z = fo$(pos)
+)cpp");
+
+    auto it = find_item("foooo");
+    ASSERT_TRUE(it != items.end());
+    // Non-deprecated should have no Deprecated tag.
+    ASSERT_TRUE(!it->tags.has_value() ||
+                std::ranges::find(*it->tags, protocol::CompletionItemTag::Deprecated) ==
+                    it->tags->end());
+}
+
 TEST_CASE(NoBundleOverloads) {
     feature::CodeCompletionOptions opts;
     opts.bundle_overloads = false;
@@ -335,44 +362,6 @@ int z = fo$(pos)
                 *it->insert_text_format == protocol::InsertTextFormat::PlainText);
 }
 
-TEST_CASE(SmartParensSkip) {
-    // When next token after cursor is '(', snippet should not insert parens.
-    feature::CodeCompletionOptions opts;
-    opts.bundle_overloads = false;
-    opts.enable_function_arguments_snippet = true;
-    code_complete(R"cpp(
-int foooo(int x, float y);
-int z = fo$(pos)(1, 2.0f);
-)cpp",
-                  opts);
-
-    auto it = find_item("foooo");
-    ASSERT_TRUE(it != items.end());
-    // With parens already present, snippet should degrade to plain text
-    // (no placeholders → build_snippet returns empty → label used).
-    auto& edit = std::get<protocol::TextEdit>(*it->text_edit);
-    ASSERT_TRUE(edit.new_text.find("(") == std::string::npos);
-}
-
-TEST_CASE(SmartParensInsert) {
-    // When next token is NOT '(', snippet should include parens normally.
-    feature::CodeCompletionOptions opts;
-    opts.bundle_overloads = false;
-    opts.enable_function_arguments_snippet = true;
-    code_complete(R"cpp(
-int foooo(int x, float y);
-int z = fo$(pos);
-)cpp",
-                  opts);
-
-    auto it = find_item("foooo");
-    ASSERT_TRUE(it != items.end());
-    auto& edit = std::get<protocol::TextEdit>(*it->text_edit);
-    // Should contain '(' since there's no existing paren.
-    ASSERT_TRUE(edit.new_text.find("(") != std::string::npos);
-    ASSERT_TRUE(edit.new_text.find("${1:") != std::string::npos);
-}
-
 TEST_CASE(SnippetBundleMode) {
     // In bundle mode, snippets should NOT be generated even if enabled.
     feature::CodeCompletionOptions opts;

tests/unit/feature/document_link_tests.cpp

@@ -21,11 +21,6 @@ void run(llvm::StringRef source, llvm::StringRef standard = "-std=c++17") {
     links = feature::document_links(*unit, feature::PositionEncoding::UTF8);
 }
 
-auto to_local_range(const protocol::Range& range) -> LocalSourceRange {
-    feature::PositionMapper converter(unit->interested_content(), feature::PositionEncoding::UTF8);
-    return LocalSourceRange(*converter.to_offset(range.start), *converter.to_offset(range.end));
-}
-
 void EXPECT_LINK(std::size_t index, llvm::StringRef name, llvm::StringRef path) {
     auto& link = links[index];
     auto expected = range(name, "main.cpp");

tests/unit/feature/folding_range_tests.cpp

@@ -37,19 +37,10 @@ void run(llvm::StringRef code) {
 }
 
 auto to_local_range(const protocol::FoldingRange& range) -> LocalSourceRange {
-    feature::PositionMapper converter(unit->interested_content(), feature::PositionEncoding::UTF8);
-
-    auto start = protocol::Position{
-        .line = range.start_line,
-        .character = range.start_character.value_or(0),
-    };
-
-    auto end = protocol::Position{
-        .line = range.end_line,
-        .character = range.end_character.value_or(0),
-    };
-
-    return LocalSourceRange(*converter.to_offset(start), *converter.to_offset(end));
+    return Tester::to_local_range(protocol::Range{
+        .start = {.line = range.start_line, .character = range.start_character.value_or(0)},
+        .end = {.line = range.end_line,   .character = range.end_character.value_or(0)  },
+    });
 }
 
 void EXPECT_FOLDING(std::uint32_t index,

tests/unit/server/config_tests.cpp

@@ -0,0 +1,501 @@
+#include <cstdlib>
+
+#include "test/temp_dir.h"
+#include "test/test.h"
+#include "server/config.h"
+#include "support/filesystem.h"
+
+#include "kota/codec/json/json.h"
+#include "kota/codec/toml/toml.h"
+
+namespace clice::testing {
+
+// POSIX setenv/unsetenv don't exist on Windows; map to _putenv_s
+// (passing an empty value to _putenv_s removes the variable).
+static void set_env(const char* name, const char* value) {
+#ifdef _WIN32
+    ::_putenv_s(name, value);
+#else
+    ::setenv(name, value, 1);
+#endif
+}
+
+static void unset_env(const char* name) {
+#ifdef _WIN32
+    ::_putenv_s(name, "");
+#else
+    ::unsetenv(name);
+#endif
+}
+
+TEST_SUITE(Config) {
+
+TEST_CASE(ParsePartialProject) {
+    auto result = kota::codec::toml::parse<ProjectConfig>(R"(cache_dir = "/tmp/test")");
+    EXPECT_TRUE(result.has_value());
+    EXPECT_EQ(std::string_view(result->cache_dir), "/tmp/test");
+    EXPECT_EQ(result->clang_tidy.value, false);
+    EXPECT_EQ(result->max_active_file.value, 0);
+    EXPECT_FALSE(result->enable_indexing.has_value());
+    EXPECT_FALSE(result->idle_timeout_ms.has_value());
+}
+
+TEST_CASE(ParseConfigRule) {
+    auto result = kota::codec::toml::parse<ConfigRule>(R"(
+patterns = ["**/*.cpp"]
+append = ["-std=c++20"]
+)");
+    EXPECT_TRUE(result.has_value());
+    EXPECT_EQ(result->patterns.size(), 1u);
+    EXPECT_EQ(result->patterns[0], "**/*.cpp");
+    EXPECT_EQ(result->append[0], "-std=c++20");
+    EXPECT_TRUE(result->remove.empty());
+}
+
+TEST_CASE(ParseFullConfig) {
+    auto result = kota::codec::toml::parse<Config>(R"(
+[project]
+cache_dir = "/tmp/test"
+clang_tidy = true
+enable_indexing = false
+
+[[rules]]
+patterns = ["**/*.cpp"]
+append = ["-std=c++20"]
+)");
+    EXPECT_TRUE(result.has_value());
+    EXPECT_EQ(std::string_view(result->project.cache_dir), "/tmp/test");
+    EXPECT_EQ(result->project.clang_tidy.value, true);
+    EXPECT_EQ(*result->project.enable_indexing, false);
+    EXPECT_EQ(result->rules.size(), 1u);
+    EXPECT_EQ(result->rules[0].patterns[0], "**/*.cpp");
+}
+
+TEST_CASE(ParseEmptyConfig) {
+    auto result = kota::codec::toml::parse<Config>("");
+    EXPECT_TRUE(result.has_value());
+    EXPECT_TRUE(result->rules.empty());
+    EXPECT_TRUE(std::string_view(result->project.cache_dir).empty());
+}
+
+TEST_CASE(ParseOnlyRules) {
+    auto result = kota::codec::toml::parse<Config>(R"(
+[[rules]]
+patterns = ["*.h"]
+remove = ["-Werror"]
+)");
+    EXPECT_TRUE(result.has_value());
+    EXPECT_EQ(result->rules.size(), 1u);
+    EXPECT_EQ(result->rules[0].patterns[0], "*.h");
+    EXPECT_EQ(result->rules[0].remove[0], "-Werror");
+    EXPECT_TRUE(std::string_view(result->project.cache_dir).empty());
+}
+
+TEST_CASE(MatchRulesBasic) {
+    Config config;
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/*.cpp"},
+        .append = {"-std=c++20"},
+        .remove = {"-std=c++17"},
+    });
+    config.apply_defaults("");
+
+    std::vector<std::string> append, remove;
+    config.match_rules("/src/foo.cpp", append, remove);
+    EXPECT_EQ(append.size(), 1u);
+    EXPECT_EQ(append[0], "-std=c++20");
+    EXPECT_EQ(remove.size(), 1u);
+    EXPECT_EQ(remove[0], "-std=c++17");
+}
+
+TEST_CASE(MatchRulesNoMatch) {
+    Config config;
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/*.cpp"},
+        .append = {"-DFOO"},
+    });
+    config.apply_defaults("");
+
+    std::vector<std::string> append, remove;
+    config.match_rules("/src/foo.h", append, remove);
+    EXPECT_TRUE(append.empty());
+    EXPECT_TRUE(remove.empty());
+}
+
+TEST_CASE(MatchRulesMultiple) {
+    Config config;
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/*.cpp"},
+        .append = {"-DCPP"},
+    });
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/test_*.cpp"},
+        .append = {"-DTEST"},
+    });
+    config.apply_defaults("");
+
+    std::vector<std::string> append, remove;
+    config.match_rules("/src/test_foo.cpp", append, remove);
+    EXPECT_EQ(append.size(), 2u);
+    EXPECT_EQ(append[0], "-DCPP");
+    EXPECT_EQ(append[1], "-DTEST");
+}
+
+TEST_CASE(ApplyDefaults) {
+    Config config;
+    config.apply_defaults("/workspace");
+    EXPECT_EQ(*config.project.enable_indexing, true);
+    EXPECT_EQ(*config.project.idle_timeout_ms, 3000);
+    EXPECT_EQ(config.project.max_active_file.value, 8);
+    EXPECT_EQ(config.project.stateful_worker_count.value, 2u);
+    EXPECT_GE(config.project.stateless_worker_count.value, 2u);
+    EXPECT_FALSE(config.project.cache_dir.empty());
+    EXPECT_FALSE(config.project.index_dir.empty());
+    EXPECT_FALSE(config.project.logging_dir.empty());
+}
+
+TEST_CASE(ApplyDefaultsEmptyWorkspace) {
+    Config config;
+    config.apply_defaults("");
+    EXPECT_TRUE(config.project.cache_dir.empty());
+    EXPECT_TRUE(config.project.index_dir.empty());
+    EXPECT_TRUE(config.project.logging_dir.empty());
+}
+
+TEST_CASE(ApplyDefaultsPreserveSet) {
+    Config config;
+    config.project.cache_dir = "/custom";
+    config.project.enable_indexing = false;
+    config.apply_defaults("/workspace");
+    EXPECT_EQ(std::string_view(config.project.cache_dir), "/custom");
+    EXPECT_EQ(*config.project.enable_indexing, false);
+}
+
+TEST_CASE(LoadFromJson) {
+    auto result = Config::load_from_json(R"({
+        "project": {
+            "cache_dir": "/opt/cache",
+            "clang_tidy": true,
+            "enable_indexing": false
+        },
+        "rules": [
+            { "patterns": ["**/*.cpp"], "append": ["-DFOO"] }
+        ]
+    })",
+                                         "/workspace");
+    EXPECT_TRUE(result.has_value());
+    EXPECT_EQ(std::string_view(result->project.cache_dir), "/opt/cache");
+    EXPECT_EQ(result->project.clang_tidy.value, true);
+    EXPECT_EQ(*result->project.enable_indexing, false);
+    EXPECT_EQ(result->rules.size(), 1u);
+    EXPECT_EQ(result->compiled_rules.size(), 1u);
+}
+
+TEST_CASE(LoadFromJsonInvalid) {
+    auto result = Config::load_from_json("{not valid json", "/workspace");
+    EXPECT_FALSE(result.has_value());
+}
+
+TEST_CASE(LoadMalformedToml) {
+    TempDir tmp;
+    tmp.touch("clice.toml", "[project\nbroken");
+    auto result = Config::load(tmp.path("clice.toml"), tmp.root.str().str());
+    EXPECT_FALSE(result.has_value());
+}
+
+TEST_CASE(LoadMissingFile) {
+    auto result = Config::load("/nonexistent/clice.toml", "/workspace");
+    EXPECT_FALSE(result.has_value());
+}
+
+TEST_CASE(WorkspaceVarSubst) {
+    Config config;
+    config.project.cache_dir = "${workspace}/cache";
+    config.project.index_dir = "${workspace}/idx";
+    config.project.logging_dir = "${workspace}/logs";
+    config.project.compile_commands_paths = {"${workspace}/build"};
+    config.apply_defaults("/my/ws");
+    EXPECT_EQ(std::string_view(config.project.cache_dir), "/my/ws/cache");
+    EXPECT_EQ(std::string_view(config.project.index_dir), "/my/ws/idx");
+    EXPECT_EQ(std::string_view(config.project.logging_dir), "/my/ws/logs");
+    EXPECT_EQ(config.project.compile_commands_paths[0], "/my/ws/build");
+}
+
+TEST_CASE(XdgCacheDir) {
+    TempDir tmp;
+    auto cache_base = tmp.path("xdg");
+    set_env("XDG_CACHE_HOME", cache_base.c_str());
+    Config config;
+    config.apply_defaults("/some/ws");
+    unset_env("XDG_CACHE_HOME");
+
+    // Normalize separators: on Windows path::join uses '\\' but the test
+    // expects posix-style comparisons.
+    std::string cache = path::convert_to_slash(std::string_view(config.project.cache_dir));
+    std::string base = path::convert_to_slash(cache_base);
+    EXPECT_TRUE(llvm::StringRef(cache).starts_with(base));
+    EXPECT_TRUE(cache.find("/clice/") != std::string::npos);
+}
+
+TEST_CASE(InvalidGlobPattern) {
+    Config config;
+    // All-invalid patterns: rule must be dropped entirely, not appended as empty.
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/****.{c,cc}"},
+        .append = {"-DSHOULD_NOT_APPEAR"},
+    });
+    // Mixed valid/invalid: only the invalid pattern is skipped; rule remains.
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/****.{c,cc}", "**/*.cpp"},
+        .append = {"-DCPP"},
+    });
+    config.apply_defaults("");
+    EXPECT_EQ(config.compiled_rules.size(), 1u);
+
+    std::vector<std::string> append, remove;
+    config.match_rules("/src/foo.cpp", append, remove);
+    EXPECT_EQ(append.size(), 1u);
+    EXPECT_EQ(append[0], "-DCPP");
+}
+
+TEST_CASE(ConfigPriorityJson) {
+    // initializationOptions-sourced config should override an on-disk default.
+    auto from_json =
+        Config::load_from_json(R"({ "project": { "max_active_file": 42 } })", "/workspace");
+    EXPECT_TRUE(from_json.has_value());
+    EXPECT_EQ(from_json->project.max_active_file.value, 42);
+    // Unset fields still receive defaults.
+    EXPECT_EQ(*from_json->project.enable_indexing, true);
+    EXPECT_EQ(from_json->project.stateful_worker_count.value, 2u);
+}
+
+TEST_CASE(XdgHashUnique) {
+    // Different workspace roots must map to different cache dirs,
+    // same workspace root must map to the same dir (deterministic).
+    TempDir tmp;
+    auto cache_base = tmp.path("xdg");
+    set_env("XDG_CACHE_HOME", cache_base.c_str());
+
+    Config a, b, c;
+    a.apply_defaults("/ws/project-a");
+    b.apply_defaults("/ws/project-b");
+    c.apply_defaults("/ws/project-a");
+    unset_env("XDG_CACHE_HOME");
+
+    EXPECT_NE(std::string_view(a.project.cache_dir), std::string_view(b.project.cache_dir));
+    EXPECT_EQ(std::string_view(a.project.cache_dir), std::string_view(c.project.cache_dir));
+}
+
+TEST_CASE(HomeFallback) {
+    // With XDG_CACHE_HOME unset but HOME set, cache dir should be under $HOME/.cache/clice.
+    TempDir tmp;
+    unset_env("XDG_CACHE_HOME");
+    auto home = tmp.path("home");
+    // Save prior value so we restore cleanly.
+    const char* prior = std::getenv("HOME");
+    std::string prior_home = prior ? prior : "";
+    set_env("HOME", home.c_str());
+
+    Config config;
+    config.apply_defaults("/some/ws");
+
+    if(prior_home.empty())
+        unset_env("HOME");
+    else
+        set_env("HOME", prior_home.c_str());
+
+    std::string cache = path::convert_to_slash(std::string_view(config.project.cache_dir));
+    std::string home_posix = path::convert_to_slash(home);
+    EXPECT_TRUE(llvm::StringRef(cache).starts_with(home_posix + "/.cache/clice/"));
+}
+
+TEST_CASE(WorkspaceCacheFallback) {
+    // No XDG, no HOME → should fall back to ${workspace}/.clice.
+    unset_env("XDG_CACHE_HOME");
+    const char* prior = std::getenv("HOME");
+    std::string prior_home = prior ? prior : "";
+    unset_env("HOME");
+
+    Config config;
+    config.apply_defaults("/ws/root");
+
+    if(!prior_home.empty())
+        set_env("HOME", prior_home.c_str());
+
+    EXPECT_EQ(path::convert_to_slash(std::string_view(config.project.cache_dir)),
+              "/ws/root/.clice");
+    EXPECT_EQ(path::convert_to_slash(std::string_view(config.project.index_dir)),
+              "/ws/root/.clice/index");
+    EXPECT_EQ(path::convert_to_slash(std::string_view(config.project.logging_dir)),
+              "/ws/root/.clice/logs");
+}
+
+TEST_CASE(WorkspaceSubstEmpty) {
+    // Empty workspace_root must not rewrite "${workspace}" into "" and produce
+    // bogus paths like "/cache" — the placeholder should be left intact.
+    Config config;
+    config.project.cache_dir = "${workspace}/cache";
+    config.apply_defaults("");
+    EXPECT_EQ(std::string_view(config.project.cache_dir), "${workspace}/cache");
+}
+
+TEST_CASE(WorkspaceSubstRepeated) {
+    // Multiple ${workspace} occurrences in one string all get substituted.
+    Config config;
+    config.project.cache_dir = "${workspace}/a/${workspace}/b";
+    config.apply_defaults("/root");
+    EXPECT_EQ(std::string_view(config.project.cache_dir), "/root/a//root/b");
+}
+
+TEST_CASE(CompilePathsList) {
+    // compile_commands_paths should substitute ${workspace} on every entry.
+    Config config;
+    config.project.compile_commands_paths = {
+        "${workspace}/build",
+        "/abs/path/compile_commands.json",
+        "${workspace}/out",
+    };
+    config.apply_defaults("/ws");
+    EXPECT_EQ(config.project.compile_commands_paths.size(), 3u);
+    EXPECT_EQ(config.project.compile_commands_paths[0], "/ws/build");
+    EXPECT_EQ(config.project.compile_commands_paths[1], "/abs/path/compile_commands.json");
+    EXPECT_EQ(config.project.compile_commands_paths[2], "/ws/out");
+}
+
+TEST_CASE(TomlErrorLocated) {
+    // Malformed TOML (bad table header, missing close-bracket) must return nullopt.
+    TempDir tmp;
+    tmp.touch("clice.toml", "[project\nclang_tidy = true\n");
+    auto result = Config::load(tmp.path("clice.toml"), tmp.root.str());
+    EXPECT_FALSE(result.has_value());
+}
+
+TEST_CASE(WorkspaceMalformedFallback) {
+    // load_from_workspace must fall back to defaults when clice.toml is malformed,
+    // not propagate the failure.
+    TempDir tmp;
+    tmp.touch("clice.toml", "[project\ninvalid");
+    auto config = Config::load_from_workspace(tmp.root.str());
+    // Defaults still applied.
+    EXPECT_EQ(config.project.stateful_worker_count.value, 2u);
+    EXPECT_EQ(*config.project.enable_indexing, true);
+}
+
+TEST_CASE(RuleOrderLaterRemoveWins) {
+    // Later rule's `remove` must cancel an earlier rule's matching `append`.
+    Config config;
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/*.cpp"},
+        .append = {"-DFOO", "-DBAR"},
+    });
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/*.cpp"},
+        .remove = {"-DFOO"},
+    });
+    config.apply_defaults("");
+
+    std::vector<std::string> append, remove;
+    config.match_rules("/src/a.cpp", append, remove);
+
+    // -DFOO should have been stripped from append; -DBAR remains.
+    EXPECT_EQ(append.size(), 1u);
+    EXPECT_EQ(append[0], "-DBAR");
+    // remove is still forwarded so base CDB flags also get filtered.
+    EXPECT_EQ(remove.size(), 1u);
+    EXPECT_EQ(remove[0], "-DFOO");
+}
+
+TEST_CASE(RuleOrderLaterAppendWins) {
+    // Later append comes after earlier append — at compiler level, last wins
+    // for flags like -O; verify the ordering is preserved.
+    Config config;
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/*.cpp"},
+        .append = {"-O2"},
+    });
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/*.cpp"},
+        .append = {"-O3"},
+    });
+    config.apply_defaults("");
+
+    std::vector<std::string> append, remove;
+    config.match_rules("/src/a.cpp", append, remove);
+    EXPECT_EQ(append.size(), 2u);
+    EXPECT_EQ(append[0], "-O2");
+    EXPECT_EQ(append[1], "-O3");
+}
+
+TEST_CASE(InitOptionsOverlayPreservesToml) {
+    // Mirror the master_server flow: load workspace config from clice.toml first,
+    // then overlay initializationOptions JSON. Fields absent in the JSON must
+    // keep their clice.toml values; fields present in the JSON override.
+    TempDir tmp;
+    tmp.touch("clice.toml", R"(
+[project]
+cache_dir = "/from/toml"
+clang_tidy = true
+max_active_file = 16
+
+[[rules]]
+patterns = ["**/*.cpp"]
+append = ["-DFROM_TOML"]
+)");
+
+    auto config = Config::load_from_workspace(tmp.root.str());
+    EXPECT_EQ(std::string_view(config.project.cache_dir), "/from/toml");
+    EXPECT_EQ(config.project.clang_tidy.value, true);
+    EXPECT_EQ(config.project.max_active_file.value, 16);
+    EXPECT_EQ(config.compiled_rules.size(), 1u);
+
+    // Overlay only `max_active_file` via JSON.
+    auto ov = kota::codec::json::parse(R"({ "project": { "max_active_file": 99 } })", config);
+    EXPECT_TRUE(ov.has_value());
+    config.apply_defaults(tmp.root.str());
+
+    // Overridden field.
+    EXPECT_EQ(config.project.max_active_file.value, 99);
+    // Untouched fields stay at TOML values.
+    EXPECT_EQ(std::string_view(config.project.cache_dir), "/from/toml");
+    EXPECT_EQ(config.project.clang_tidy.value, true);
+    // Rules from clice.toml must survive the overlay.
+    EXPECT_EQ(config.rules.size(), 1u);
+    EXPECT_EQ(config.compiled_rules.size(), 1u);
+    EXPECT_EQ(config.rules[0].append[0], "-DFROM_TOML");
+}
+
+TEST_CASE(InitOptionsOverlayRulesReplace) {
+    // When `rules` is present in the overlay JSON, it replaces the whole array
+    // (kotatsu deserializes the vector by value). `compiled_rules` must be
+    // rebuilt after apply_defaults so stale compiled entries don't linger.
+    TempDir tmp;
+    tmp.touch("clice.toml", R"(
+[[rules]]
+patterns = ["**/*.cpp"]
+append = ["-DTOML_ONLY"]
+)");
+    auto config = Config::load_from_workspace(tmp.root.str());
+    EXPECT_EQ(config.compiled_rules.size(), 1u);
+
+    auto ov = kota::codec::json::parse(
+        R"({ "rules": [ { "patterns": ["**/*.cc"], "append": ["-DFROM_JSON"] } ] })",
+        config);
+    EXPECT_TRUE(ov.has_value());
+    config.apply_defaults(tmp.root.str());
+
+    EXPECT_EQ(config.rules.size(), 1u);
+    EXPECT_EQ(config.rules[0].append[0], "-DFROM_JSON");
+    EXPECT_EQ(config.compiled_rules.size(), 1u);
+
+    // Original TOML rule no longer applies.
+    std::vector<std::string> append, remove;
+    config.match_rules("/src/x.cpp", append, remove);
+    EXPECT_TRUE(append.empty());
+    config.match_rules("/src/x.cc", append, remove);
+    EXPECT_EQ(append.size(), 1u);
+    EXPECT_EQ(append[0], "-DFROM_JSON");
+}
+
+};  // TEST_SUITE(Config)
+
+}  // namespace clice::testing

tests/unit/server/stateful_worker_tests.cpp

@@ -5,7 +5,7 @@
 #include "server/protocol.h"
 #include "server/worker_test_helpers.h"
 
-#include "kota/codec/raw_value.h"
+#include "kota/codec/json/json.h"
 
 namespace clice::testing {
 

tests/unit/server/stateless_worker_tests.cpp

@@ -6,7 +6,6 @@
 #include "server/worker_test_helpers.h"
 
 #include "kota/codec/bincode/bincode.h"
-#include "kota/codec/raw_value.h"
 
 namespace clice::testing {
 

tests/unit/test/tester.h

@@ -8,6 +8,7 @@
 #include "test/test.h"
 #include "command/command.h"
 #include "compile/compilation.h"
+#include "feature/feature.h"
 #include "support/logging.h"
 
 namespace clice::testing {
@@ -82,6 +83,12 @@ struct Tester {
 
     LocalSourceRange range(llvm::StringRef name = "", llvm::StringRef file = "");
 
+    LocalSourceRange to_local_range(const kota::ipc::protocol::Range& range) {
+        feature::PositionMapper converter(unit->interested_content(),
+                                          feature::PositionEncoding::UTF8);
+        return LocalSourceRange(*converter.to_offset(range.start), *converter.to_offset(range.end));
+    }
+
     void clear();
 };