diff --git a/.github/workflows/recover-v1.0.5-macos-arm64.yml b/.github/workflows/recover-v1.0.5-macos-arm64.yml
new file mode 100644
index 000000000..c83e10883
--- /dev/null
+++ b/.github/workflows/recover-v1.0.5-macos-arm64.yml
@@ -0,0 +1,901 @@
+name: Recover v1.0.5 macOS ARM64
+'on':
+  push:
+    branches:
+    - codex/recover-v1.0.5-macos-arm64
+permissions:
+  contents: read
+  actions: read
+concurrency:
+  group: recover-v1.0.5-macos-arm64
+  cancel-in-progress: false
+jobs:
+  build-web-ui:
+    name: web-dist
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        ref: v1.0.5
+    - name: Check bundled models.dev freshness for release
+      if: 'true'
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        python3 - <<'PY'
+        import datetime as dt
+        import json
+        from pathlib import Path
+
+        manifest_path = Path("assets/models_dev/MANIFEST.json")
+        try:
+            manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+            generated_at = dt.datetime.fromisoformat(
+                manifest["generated_at"].replace("Z", "+00:00")
+            )
+        except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
+            raise SystemExit(f"Invalid {manifest_path}: {exc}")
+
+        if generated_at.tzinfo is None:
+            raise SystemExit(f"{manifest_path}: generated_at must include a timezone")
+        now = dt.datetime.now(dt.timezone.utc)
+        age = now - generated_at.astimezone(dt.timezone.utc)
+        if age < -dt.timedelta(minutes=5):
+            raise SystemExit(f"{manifest_path}: generated_at is in the future")
+        if age > dt.timedelta(days=30):
+            raise SystemExit(
+                f"Bundled models.dev registry is {age.days} days old; "
+                "run scripts/sync_models_dev before creating a release tag"
+            )
+        print(f"Bundled models.dev registry age: {age.days} days")
+        PY
+    - name: Install pnpm
+      uses: pnpm/action-setup@v4
+      with:
+        version: 10.32.1
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: pnpm
+        cache-dependency-path: web/pnpm-lock.yaml
+    - name: Build web UI
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        cd web
+        pnpm install --frozen-lockfile
+        pnpm build
+    - name: Upload web UI
+      uses: actions/upload-artifact@v4
+      with:
+        name: web-dist
+        path: web/dist
+        if-no-files-found: error
+  build-and-package:
+    name: ${{ matrix.id }}
+    needs: build-web-ui
+    runs-on: ${{ matrix.os }}
+    env:
+      VCPKG_BINARY_SOURCES: clear;default,readwrite
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - id: macos-arm64
+          os: macos-15
+          installer_arch: arm64
+          triplet: arm64-osx
+          executable: acecode
+          archive_extension: tar.gz
+          build_desktop: true
+          cmake_extra_args: -DCMAKE_OSX_ARCHITECTURES=arm64 -DACECODE_BUILD_DESKTOP=ON
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        submodules: recursive
+        ref: v1.0.5
+    - name: Verify immutable v1.0.5 source
+      shell: bash
+      run: |
+        test "$(git rev-parse HEAD)" = "f4dd8e767142cdd611d562f1bebf4634009925a8"
+        git diff --exit-code
+    - name: Resolve package version
+      id: package-version
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        declared_version="$(awk '$1 == "project(acecode" && $2 == "VERSION" { print $3; exit }' CMakeLists.txt)"
+        if [ -z "$declared_version" ]; then
+          echo "::error::Unable to read the ACECode version from CMakeLists.txt"
+          exit 1
+        fi
+        if [[ "$GITHUB_REF" == refs/tags/v* && "${GITHUB_REF_NAME#v}" != "$declared_version" ]]; then
+          echo "::error::Tag $GITHUB_REF_NAME does not match CMake version $declared_version"
+          exit 1
+        fi
+        echo "version=$declared_version" >> "$GITHUB_OUTPUT"
+    - name: Check macOS release credentials
+      if: runner.os == 'macOS'
+      id: macos-release
+      shell: bash
+      env:
+        MACOS_CERTIFICATE_BASE64: ${{ secrets.MACOS_CERTIFICATE_BASE64 }}
+        MACOS_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
+        MACOS_INSTALLER_CERTIFICATE_BASE64: ${{ secrets.MACOS_INSTALLER_CERTIFICATE_BASE64 }}
+        MACOS_INSTALLER_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_INSTALLER_CERTIFICATE_PASSWORD }}
+        APPLE_ID: ${{ secrets.APPLE_ID }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        application_missing=()
+        for name in \
+          MACOS_CERTIFICATE_BASE64 \
+          MACOS_CERTIFICATE_PASSWORD \
+          APPLE_ID \
+          APPLE_TEAM_ID \
+          APPLE_APP_SPECIFIC_PASSWORD; do
+          if [ -z "${!name}" ]; then
+            application_missing+=("$name")
+          fi
+        done
+
+        if [ "${#application_missing[@]}" -ne 0 ]; then
+          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
+            echo "::error::Tagged macOS application releases require secrets: ${application_missing[*]}"
+            exit 1
+          fi
+          echo "::notice::macOS signing/notarization disabled; missing: ${application_missing[*]}"
+          echo "enabled=false" >> "$GITHUB_OUTPUT"
+        else
+          echo "enabled=true" >> "$GITHUB_OUTPUT"
+        fi
+
+        installer_certificate_set=false
+        installer_password_set=false
+        if [ -n "$MACOS_INSTALLER_CERTIFICATE_BASE64" ]; then
+          installer_certificate_set=true
+        fi
+        if [ -n "$MACOS_INSTALLER_CERTIFICATE_PASSWORD" ]; then
+          installer_password_set=true
+        fi
+
+        if [ "$installer_certificate_set" != "$installer_password_set" ]; then
+          echo "::error::macOS Installer credentials must configure both MACOS_INSTALLER_CERTIFICATE_BASE64 and MACOS_INSTALLER_CERTIFICATE_PASSWORD"
+          exit 1
+        fi
+        if [ "$installer_certificate_set" = "true" ]; then
+          if [ "${#application_missing[@]}" -eq 0 ]; then
+            echo "pkg_enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "::notice::macOS PKG creation disabled because application signing/notarization is disabled"
+            echo "pkg_enabled=false" >> "$GITHUB_OUTPUT"
+          fi
+        else
+          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
+            echo "::error::Tagged macOS releases require MACOS_INSTALLER_CERTIFICATE_BASE64 and MACOS_INSTALLER_CERTIFICATE_PASSWORD to build both PKGs"
+            exit 1
+          fi
+          echo "::notice::macOS PKG creation disabled; Developer ID Installer credentials are not configured"
+          echo "pkg_enabled=false" >> "$GITHUB_OUTPUT"
+        fi
+    - name: Configure MSVC
+      if: runner.os == 'Windows'
+      uses: ilammy/msvc-dev-cmd@v1
+      with:
+        arch: ${{ matrix.msvc_arch }}
+    - name: Install Linux ARMv7 cross toolchain
+      if: matrix.id == 'linux-armv7'
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        sudo apt-get update
+        sudo apt-get install -y \
+          binutils-arm-linux-gnueabihf \
+          gcc-arm-linux-gnueabihf \
+          g++-arm-linux-gnueabihf \
+          qemu-user
+    - name: Run vcpkg
+      uses: lukka/run-vcpkg@v11
+    - name: Restore vcpkg binary cache
+      uses: actions/cache@v4
+      with:
+        path: ${{ env.VCPKG_DEFAULT_BINARY_CACHE }}
+        key: vcpkg-v2-${{ matrix.os }}-${{ matrix.triplet }}-${{ hashFiles('vcpkg.json', 'vcpkg-configuration.json', 'ports/**')
+          }}
+        restore-keys: |
+          vcpkg-v2-${{ matrix.os }}-${{ matrix.triplet }}-
+    - name: Install Linux desktop dependencies
+      if: runner.os == 'Linux' && matrix.build_desktop
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        sudo apt-get update
+        sudo apt-get install -y libwebkit2gtk-4.1-dev
+    - name: Download web UI
+      uses: actions/download-artifact@v4
+      with:
+        name: web-dist
+        path: web/dist
+    - name: Configure
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        cmake -S . -B build -G Ninja \
+          -DCMAKE_BUILD_TYPE=MinSizeRel \
+          -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" \
+          -DVCPKG_TARGET_TRIPLET="${{ matrix.triplet }}" \
+          -DBUILD_TESTING=OFF \
+          ${{ matrix.cmake_extra_args }}
+    - name: Build
+      shell: bash
+      run: |-
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        cmake --build build --config MinSizeRel --target acecode
+    - name: Build desktop
+      if: matrix.build_desktop
+      shell: bash
+      run: |-
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        cmake --build build --config MinSizeRel --target acecode-desktop
+    - name: Verify Linux ARMv7 executable
+      if: matrix.id == 'linux-armv7'
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        export LC_ALL=C
+        elf_header="$(arm-linux-gnueabihf-readelf -h build/acecode)"
+        arm_attributes="$(arm-linux-gnueabihf-readelf -A build/acecode)"
+        program_headers="$(arm-linux-gnueabihf-readelf -l build/acecode)"
+
+        printf '%s\n' "$elf_header"
+        printf '%s\n' "$arm_attributes"
+
+        grep -Eq 'Class:[[:space:]]+ELF32' <<<"$elf_header"
+        grep -Eq 'Machine:[[:space:]]+ARM' <<<"$elf_header"
+        grep -Eq 'Tag_CPU_arch:[[:space:]]+v7' <<<"$arm_attributes"
+        grep -Eq 'Tag_ABI_VFP_args:[[:space:]]+VFP registers' <<<"$arm_attributes"
+        grep -Fq '/lib/ld-linux-armhf.so.3' <<<"$program_headers"
+
+        version_output="$(qemu-arm -L /usr/arm-linux-gnueabihf build/acecode --version)"
+        printf '%s\n' "$version_output"
+        grep -Eq '^acecode v[^[:space:]]+$' <<<"$version_output"
+    - name: Verify bundled resources in macOS app
+      if: runner.os == 'macOS' && matrix.build_desktop
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        registry_dir="build/ACECode.app/Contents/Resources/share/acecode/models_dev"
+        file_count="$(find "$registry_dir" -type f | wc -l | tr -d '[:space:]')"
+        if [ "$file_count" != "3" ]; then
+          echo "Expected exactly 3 models.dev resources in $registry_dir, found $file_count" >&2
+          exit 1
+        fi
+        for file in api.json MANIFEST.json LICENSE; do
+          if [ ! -f "$registry_dir/$file" ] ||
+             ! cmp -s "assets/models_dev/$file" "$registry_dir/$file"; then
+            echo "Missing or mismatched macOS app models.dev resource: $file" >&2
+            exit 1
+          fi
+        done
+        python3 scripts/verify_seed_bundle.py \
+          --source assets/seed \
+          --packaged build/ACECode.app/Contents/Resources/share/acecode/seed
+    - name: Extract debug symbols (Linux)
+      if: runner.os == 'Linux'
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        binutils_prefix=""
+        if [ "${{ matrix.id }}" = "linux-armv7" ]; then
+          binutils_prefix="arm-linux-gnueabihf-"
+        fi
+        "${binutils_prefix}objcopy" --only-keep-debug \
+          "build/${{ matrix.executable }}" \
+          "build/${{ matrix.executable }}.debug"
+        "${binutils_prefix}strip" --strip-unneeded "build/${{ matrix.executable }}"
+        "${binutils_prefix}objcopy" \
+          --add-gnu-debuglink="build/${{ matrix.executable }}.debug" \
+          "build/${{ matrix.executable }}"
+    - name: Extract desktop debug symbols (Linux)
+      if: runner.os == 'Linux' && matrix.build_desktop
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        objcopy --only-keep-debug "build/acecode-desktop" "build/acecode-desktop.debug"
+        strip --strip-unneeded "build/acecode-desktop"
+        objcopy --add-gnu-debuglink="build/acecode-desktop.debug" "build/acecode-desktop"
+    - name: Extract debug symbols (macOS)
+      if: runner.os == 'macOS'
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        dsymutil "build/${{ matrix.executable }}" -o "build/${{ matrix.executable }}.dSYM"
+        strip "build/${{ matrix.executable }}"
+    - name: Extract desktop debug symbols (macOS)
+      if: runner.os == 'macOS' && matrix.build_desktop
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        app_exec="build/ACECode.app/Contents/MacOS/ACECode"
+        app_daemon="build/ACECode.app/Contents/MacOS/acecode-daemon"
+        if [ ! -f "$app_exec" ]; then
+          echo "Missing desktop app executable: $app_exec" >&2
+          exit 1
+        fi
+        if [ ! -f "$app_daemon" ]; then
+          echo "Missing desktop app daemon: $app_daemon" >&2
+          exit 1
+        fi
+        dsymutil "$app_exec" -o "build/ACECode.app.dSYM"
+        strip "$app_exec"
+        dsymutil "$app_daemon" -o "build/acecode-daemon.dSYM"
+        strip "$app_daemon"
+    - name: Import Developer ID identities (macOS)
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      id: macos-keychain
+      shell: bash
+      env:
+        MACOS_CERTIFICATE_BASE64: ${{ secrets.MACOS_CERTIFICATE_BASE64 }}
+        MACOS_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
+        MACOS_INSTALLER_CERTIFICATE_BASE64: ${{ secrets.MACOS_INSTALLER_CERTIFICATE_BASE64 }}
+        MACOS_INSTALLER_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_INSTALLER_CERTIFICATE_PASSWORD }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        MACOS_CODESIGN_IDENTITY: ${{ vars.MACOS_CODESIGN_IDENTITY }}
+        MACOS_INSTALLER_SIGNING_IDENTITY: ${{ vars.MACOS_INSTALLER_SIGNING_IDENTITY }}
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        set +x
+        certificate_path="$RUNNER_TEMP/acecode-developer-id.p12"
+        installer_certificate_path="$RUNNER_TEMP/acecode-developer-id-installer.p12"
+        keychain_path="$RUNNER_TEMP/acecode-signing.keychain-db"
+        keychain_password="$(openssl rand -hex 32)"
+
+        printf '%s' "$MACOS_CERTIFICATE_BASE64" | /usr/bin/base64 -D > "$certificate_path"
+        chmod 600 "$certificate_path"
+        if [ "${{ steps.macos-release.outputs.pkg_enabled }}" = "true" ]; then
+          printf '%s' "$MACOS_INSTALLER_CERTIFICATE_BASE64" | /usr/bin/base64 -D > "$installer_certificate_path"
+          chmod 600 "$installer_certificate_path"
+        fi
+        security create-keychain -p "$keychain_password" "$keychain_path"
+        security set-keychain-settings -lut 21600 "$keychain_path"
+        security unlock-keychain -p "$keychain_password" "$keychain_path"
+
+        existing_user_keychains=()
+        while IFS= read -r existing_keychain; do
+          if [ -n "$existing_keychain" ]; then
+            existing_user_keychains+=("$existing_keychain")
+          fi
+        done < <(
+          security list-keychains -d user |
+            sed -E 's/^[[:space:]]*"//; s/"[[:space:]]*$//'
+        )
+        security list-keychains -d user -s \
+          "$keychain_path" \
+          "${existing_user_keychains[@]}"
+
+        security import "$certificate_path" \
+          -k "$keychain_path" \
+          -P "$MACOS_CERTIFICATE_PASSWORD" \
+          -f pkcs12 \
+          -T /usr/bin/codesign \
+          -T /usr/bin/security
+        if [ "${{ steps.macos-release.outputs.pkg_enabled }}" = "true" ]; then
+          security import "$installer_certificate_path" \
+            -k "$keychain_path" \
+            -P "$MACOS_INSTALLER_CERTIFICATE_PASSWORD" \
+            -f pkcs12 \
+            -T /usr/bin/pkgbuild \
+            -T /usr/bin/productbuild \
+            -T /usr/bin/security
+        fi
+        security set-key-partition-list \
+          -S apple-tool:,apple: \
+          -s \
+          -k "$keychain_password" \
+          "$keychain_path"
+
+        identity_record="$(security find-identity -v -p codesigning "$keychain_path" |
+          awk '/Developer ID Application:/ { print; exit }')"
+        identity_fingerprint="$(printf '%s\n' "$identity_record" | awk '{ print $2 }')"
+        identity_name="$(printf '%s\n' "$identity_record" | awk -F '"' '{ print $2 }')"
+        if [[ ! "$identity_fingerprint" =~ ^[[:xdigit:]]{40}$ ]] || [ -z "$identity_name" ]; then
+          echo "::error::No Developer ID Application identity found in the imported certificate"
+          exit 1
+        fi
+        if [ -n "$MACOS_CODESIGN_IDENTITY" ] && [ "$identity_name" != "$MACOS_CODESIGN_IDENTITY" ]; then
+          echo "::error::Imported signing identity does not match MACOS_CODESIGN_IDENTITY"
+          exit 1
+        fi
+        if [ -n "$APPLE_TEAM_ID" ] && [[ "$identity_name" != *"($APPLE_TEAM_ID)" ]]; then
+          echo "::error::Developer ID Application identity does not match APPLE_TEAM_ID"
+          exit 1
+        fi
+
+        if [ "${{ steps.macos-release.outputs.pkg_enabled }}" = "true" ]; then
+          installer_identity_record="$(security find-identity -v -p basic "$keychain_path" |
+            awk '/Developer ID Installer:/ { print; exit }')"
+          installer_identity_fingerprint="$(printf '%s\n' "$installer_identity_record" | awk '{ print $2 }')"
+          installer_identity_name="$(printf '%s\n' "$installer_identity_record" | awk -F '"' '{ print $2 }')"
+          if [[ ! "$installer_identity_fingerprint" =~ ^[[:xdigit:]]{40}$ ]] || [ -z "$installer_identity_name" ]; then
+            echo "::error::No Developer ID Installer identity found in the imported certificate"
+            exit 1
+          fi
+          if [ -n "$MACOS_INSTALLER_SIGNING_IDENTITY" ] && [ "$installer_identity_name" != "$MACOS_INSTALLER_SIGNING_IDENTITY" ]; then
+            echo "::error::Imported Installer identity does not match MACOS_INSTALLER_SIGNING_IDENTITY"
+            exit 1
+          fi
+          if [ -n "$APPLE_TEAM_ID" ] && [[ "$installer_identity_name" != *"($APPLE_TEAM_ID)" ]]; then
+            echo "::error::Developer ID Installer identity does not match APPLE_TEAM_ID"
+            exit 1
+          fi
+          echo "installer_identity=$installer_identity_name" >> "$GITHUB_OUTPUT"
+        fi
+
+        echo "keychain=$keychain_path" >> "$GITHUB_OUTPUT"
+        # Sign by the certificate fingerprint. codesign can fail to resolve a
+        # human-readable identity name inside an isolated temporary keychain.
+        echo "identity=$identity_fingerprint" >> "$GITHUB_OUTPUT"
+    - name: Sign macOS release payloads
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        scripts/macos_codesign.sh \
+          --identity "${{ steps.macos-keychain.outputs.identity }}" \
+          --keychain "${{ steps.macos-keychain.outputs.keychain }}" \
+          --binary "build/${{ matrix.executable }}" \
+          --binary "build/acecode-computer-use" \
+          --app "build/ACECode.app"
+    - name: Notarize and staple macOS app
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      shell: bash
+      env:
+        APPLE_ID: ${{ secrets.APPLE_ID }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      run: |-
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        scripts/macos_notarize_app.sh --app "build/ACECode.app"
+    - name: Test macOS installer integration
+      if: runner.os == 'macOS'
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        bash tests/scripts/macos_installer_test.sh
+        python3 tests/scripts/macos_installer_release_test.py
+    - name: Create current-user macOS PKG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.pkg_enabled == 'true'
+      id: macos-pkg
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        pkg_path="ACECode-${{ steps.package-version.outputs.version }}-${{ matrix.id }}.pkg"
+        scripts/macos_create_pkg.sh \
+          --app "build/ACECode.app" \
+          --output "$pkg_path" \
+          --installer-identity "${{ steps.macos-keychain.outputs.installer_identity }}" \
+          --keychain "${{ steps.macos-keychain.outputs.keychain }}"
+        echo "path=$pkg_path" >> "$GITHUB_OUTPUT"
+    - name: Notarize and validate macOS PKG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.pkg_enabled == 'true'
+      shell: bash
+      env:
+        APPLE_ID: ${{ secrets.APPLE_ID }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      run: |-
+        xcrun() {
+          if [[ "${1:-}" != "stapler" ]]; then
+            command xcrun "$@"
+            return $?
+          fi
+          local result=0
+          for attempt in 1 2 3 4 5 6; do
+            if command xcrun "$@"; then return 0; else result=$?; fi
+            if [[ "$result" != "68" || "$attempt" == "6" ]]; then return "$result"; fi
+            echo "Apple ticket service disconnected (68), retry $attempt/6 in 15 seconds"
+            sleep 15
+          done
+          return "$result"
+        }
+        export -f xcrun
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        scripts/macos_notarize_pkg.sh --pkg "${{ steps.macos-pkg.outputs.path }}"
+    - name: Upload macOS PKG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.pkg_enabled == 'true'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-pkg
+        path: ${{ steps.macos-pkg.outputs.path }}
+        if-no-files-found: error
+    - name: Build signed and notarized macOS installer DMG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      id: macos-dmg
+      shell: bash
+      env:
+        APPLE_ID: ${{ secrets.APPLE_ID }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      run: |
+        xcrun() {
+          if [[ "${1:-}" != "stapler" ]]; then
+            command xcrun "$@"
+            return $?
+          fi
+          local result=0
+          for attempt in 1 2 3 4 5 6; do
+            if command xcrun "$@"; then return 0; else result=$?; fi
+            if [[ "$result" != "68" || "$attempt" == "6" ]]; then return "$result"; fi
+            echo "Apple ticket service disconnected (68), retry $attempt/6 in 15 seconds"
+            sleep 15
+          done
+          return "$result"
+        }
+        export -f xcrun
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        dmg_path="ACECode-${{ steps.package-version.outputs.version }}-${{ matrix.id }}.dmg"
+        bash scripts/macos_create_installer_dmg.sh \
+          --app "build/ACECode.app" \
+          --output "$dmg_path" \
+          --arch "${{ matrix.installer_arch }}" \
+          --identity "${{ steps.macos-keychain.outputs.identity }}" \
+          --keychain "${{ steps.macos-keychain.outputs.keychain }}"
+        echo "path=$dmg_path" >> "$GITHUB_OUTPUT"
+    - name: Create macOS self-update archive
+      if: runner.os == 'macOS'
+      id: macos-update
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        unsigned_suffix=""
+        trust_args=()
+        if [ "${{ steps.macos-release.outputs.enabled }}" = "true" ]; then
+          trust_args+=(--require-trusted)
+        else
+          unsigned_suffix="-unsigned"
+        fi
+        update_path="ACECode-${{ steps.package-version.outputs.version }}-${{ matrix.id }}-update${unsigned_suffix}.zip"
+        scripts/macos_create_update_zip.sh \
+          --app "build/ACECode.app" \
+          --output "$update_path" \
+          "${trust_args[@]}"
+        echo "path=$update_path" >> "$GITHUB_OUTPUT"
+    - name: Package (Unix)
+      if: runner.os != 'Windows'
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        package_dir="dist/acecode-${{ matrix.id }}"
+        mkdir -p "$package_dir"
+
+        validate_models_dev_registry() {
+          registry_dir="$1"
+          file_count="$(find "$registry_dir" -type f | wc -l | tr -d '[:space:]')"
+          if [ "$file_count" != "3" ]; then
+            echo "Expected exactly 3 models.dev files in $registry_dir, found $file_count" >&2
+            exit 1
+          fi
+          for file in api.json MANIFEST.json LICENSE; do
+            if [ ! -f "$registry_dir/$file" ] ||
+               ! cmp -s "assets/models_dev/$file" "$registry_dir/$file"; then
+              echo "Missing or mismatched models.dev package file: $registry_dir/$file" >&2
+              exit 1
+            fi
+          done
+        }
+
+        if [ ! -f "build/${{ matrix.executable }}" ]; then
+          echo "Missing terminal executable: build/${{ matrix.executable }}" >&2
+          exit 1
+        fi
+        cp "build/${{ matrix.executable }}" "$package_dir/"
+        cp README.md README_CN.md "$package_dir/"
+        cmake --install build \
+          --config MinSizeRel \
+          --prefix "$PWD/$package_dir" \
+          --component models_dev_registry
+        cmake --install build \
+          --config MinSizeRel \
+          --prefix "$PWD/$package_dir" \
+          --component default_seed_bundle
+        cmake --install build --config MinSizeRel --prefix "$PWD/$package_dir" --component whatsapp_channel
+        if [ "$RUNNER_OS" = "macOS" ]; then
+          cmake --install build --config MinSizeRel --prefix "$PWD/$package_dir" --component computer_use_runtime
+          test -x "$package_dir/acecode-computer-use"
+          test -x "build/ACECode.app/Contents/MacOS/acecode-computer-use"
+        fi
+        validate_models_dev_registry "$package_dir/share/acecode/models_dev"
+        python3 scripts/verify_seed_bundle.py \
+          --source assets/seed \
+          --packaged "$package_dir/share/acecode/seed"
+
+        if [ "${{ matrix.build_desktop }}" = "true" ]; then
+          if [ "$RUNNER_OS" = "macOS" ]; then
+            if [ ! -d "build/ACECode.app" ]; then
+              echo "Missing desktop app bundle: build/ACECode.app" >&2
+              exit 1
+            fi
+            cp -r "build/ACECode.app" "$package_dir/"
+          else
+            if [ ! -f "build/acecode-desktop" ]; then
+              echo "Missing desktop executable: build/acecode-desktop" >&2
+              exit 1
+            fi
+            cp "build/acecode-desktop" "$package_dir/"
+            cp "build/acecode-logo.png" "$package_dir/"
+          fi
+        fi
+        legacy="$(find "$package_dir" -maxdepth 1 -iname 'ace-browser-*' -print -quit)"
+        if [ -n "$legacy" ]; then
+          echo "Legacy browser artifact must not be packaged: $legacy" >&2
+          exit 1
+        fi
+        tar -C dist -czf "acecode-${{ matrix.id }}.tar.gz" "acecode-${{ matrix.id }}"
+
+        verify_root="$(mktemp -d)"
+        tar -xzf "acecode-${{ matrix.id }}.tar.gz" -C "$verify_root"
+        extracted_package="$verify_root/acecode-${{ matrix.id }}"
+        validate_models_dev_registry "$extracted_package/share/acecode/models_dev"
+        python3 scripts/verify_seed_bundle.py \
+          --source assets/seed \
+          --packaged "$extracted_package/share/acecode/seed"
+        if [ "$RUNNER_OS" = "macOS" ]; then
+          test -x "$extracted_package/acecode-computer-use"
+          test -x "$extracted_package/ACECode.app/Contents/MacOS/acecode-computer-use"
+          validate_models_dev_registry \
+            "$extracted_package/ACECode.app/Contents/Resources/share/acecode/models_dev"
+          python3 scripts/verify_seed_bundle.py \
+            --source assets/seed \
+            --packaged "$extracted_package/ACECode.app/Contents/Resources/share/acecode/seed"
+        fi
+        rm -rf -- "$verify_root"
+    - name: Create Linux self-update archive
+      if: matrix.id == 'linux-x64' || matrix.id == 'linux-arm64'
+      id: linux-update
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        update_path="acecode-${{ steps.package-version.outputs.version }}-${{ matrix.id }}-update.zip"
+        bash scripts/linux_create_update_zip.sh \
+          --package-dir "dist/acecode-${{ matrix.id }}" \
+          --output "$update_path" \
+          --expected-version "${{ steps.package-version.outputs.version }}"
+        echo "path=$update_path" >> "$GITHUB_OUTPUT"
+    - name: Clean up macOS signing material
+      if: always() && runner.os == 'macOS'
+      shell: bash
+      run: |
+        GITHUB_REF=refs/tags/v1.0.5
+        GITHUB_REF_NAME=v1.0.5
+        set +e
+        security delete-keychain "$RUNNER_TEMP/acecode-signing.keychain-db" 2>/dev/null
+        rm -f -- \
+          "$RUNNER_TEMP/acecode-developer-id.p12" \
+          "$RUNNER_TEMP/acecode-developer-id-installer.p12"
+    - name: Package (Windows)
+      if: runner.os == 'Windows'
+      shell: pwsh
+      run: |
+        $packageDir = "dist/acecode-${{ matrix.id }}"
+        New-Item -ItemType Directory -Force -Path $packageDir | Out-Null
+
+        function Assert-ModelsDevRegistry([string] $RegistryDir) {
+          if (-not (Test-Path -LiteralPath $RegistryDir -PathType Container)) {
+            throw "Missing models.dev directory: $RegistryDir"
+          }
+          $actualFiles = @(Get-ChildItem -LiteralPath $RegistryDir -File -Recurse)
+          if ($actualFiles.Count -ne 3) {
+            throw "Expected exactly 3 models.dev files in ${RegistryDir}, found $($actualFiles.Count)"
+          }
+          foreach ($name in @("api.json", "MANIFEST.json", "LICENSE")) {
+            $source = Join-Path "assets/models_dev" $name
+            $packaged = Join-Path $RegistryDir $name
+            if (-not (Test-Path -LiteralPath $packaged -PathType Leaf)) {
+              throw "Missing models.dev package file: $packaged"
+            }
+            $sourceHash = (Get-FileHash -LiteralPath $source -Algorithm SHA256).Hash
+            $packagedHash = (Get-FileHash -LiteralPath $packaged -Algorithm SHA256).Hash
+            if ($sourceHash -ne $packagedHash) {
+              throw "Mismatched models.dev package file: $packaged"
+            }
+          }
+        }
+
+        $terminalExe = "build/${{ matrix.executable }}"
+        if (-not (Test-Path -LiteralPath $terminalExe)) {
+          throw "Missing terminal executable: $terminalExe"
+        }
+        Copy-Item -LiteralPath $terminalExe -Destination "$packageDir/"
+        Copy-Item "README.md","README_CN.md" "$packageDir/"
+        $packageRoot = (Resolve-Path -LiteralPath $packageDir).Path
+        & cmake --install build --config MinSizeRel --prefix $packageRoot --component models_dev_registry
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to install the bundled models.dev registry"
+        }
+        & cmake --install build --config MinSizeRel --prefix $packageRoot --component default_seed_bundle
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to install the default seed bundle"
+        }
+        & cmake --install build --config MinSizeRel --prefix $packageRoot --component whatsapp_channel
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to install the WhatsApp channel bridge"
+        }
+        & cmake --install build --config MinSizeRel --prefix $packageRoot --component computer_use_runtime
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to install the Computer Use runtime"
+        }
+        $computerUseExe = Join-Path $packageRoot "acecode-computer-use.exe"
+        if (-not (Test-Path -LiteralPath $computerUseExe -PathType Leaf) -or
+            (Get-Item -LiteralPath $computerUseExe).Length -eq 0) {
+          throw "Missing Computer Use runtime: $computerUseExe"
+        }
+        Assert-ModelsDevRegistry (Join-Path $packageDir "share/acecode/models_dev")
+        & python scripts/verify_seed_bundle.py `
+          --source assets/seed `
+          --packaged (Join-Path $packageDir "share/acecode/seed")
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to verify the packaged default seed bundle"
+        }
+
+        if ("${{ matrix.build_desktop }}" -eq "true") {
+          $desktopCandidates = @(
+            "build/acecode-desktop.exe",
+            "build/Release/acecode-desktop.exe",
+            "build/Debug/acecode-desktop.exe",
+            "build/RelWithDebInfo/acecode-desktop.exe",
+            "build/MinSizeRel/acecode-desktop.exe"
+          )
+          $desktopExe = $desktopCandidates | Where-Object { Test-Path -LiteralPath $_ } | Select-Object -First 1
+          if (-not $desktopExe) {
+            $desktopExe = Get-ChildItem -Path "build" -Recurse -Filter "acecode-desktop.exe" -File |
+              Select-Object -ExpandProperty FullName -First 1
+          }
+          if (-not $desktopExe) {
+            throw "Missing desktop executable: acecode-desktop.exe"
+          }
+          Copy-Item -LiteralPath $desktopExe -Destination "$packageDir/"
+        }
+        $legacyBrowserArtifact = Get-ChildItem -LiteralPath $packageDir -Filter "ace-browser-*" -Force |
+          Select-Object -First 1
+        if ($legacyBrowserArtifact) {
+          throw "Legacy browser artifact must not be packaged: $($legacyBrowserArtifact.FullName)"
+        }
+        Compress-Archive -Path "$packageDir/*" -DestinationPath "acecode-${{ matrix.id }}.zip" -Force
+
+        $verifyRoot = Join-Path $env:RUNNER_TEMP ("acecode-package-verify-" + [Guid]::NewGuid().ToString("N"))
+        New-Item -ItemType Directory -Path $verifyRoot | Out-Null
+        Expand-Archive -LiteralPath "acecode-${{ matrix.id }}.zip" -DestinationPath $verifyRoot
+        $archivedComputerUseExe = Join-Path $verifyRoot "acecode-computer-use.exe"
+        if (-not (Test-Path -LiteralPath $archivedComputerUseExe -PathType Leaf) -or
+            (Get-FileHash -LiteralPath $archivedComputerUseExe -Algorithm SHA256).Hash -ne
+              (Get-FileHash -LiteralPath $computerUseExe -Algorithm SHA256).Hash) {
+          throw "Archived Computer Use runtime is missing or does not match the build"
+        }
+        Assert-ModelsDevRegistry (Join-Path $verifyRoot "share/acecode/models_dev")
+        & python scripts/verify_seed_bundle.py `
+          --source assets/seed `
+          --packaged (Join-Path $verifyRoot "share/acecode/seed")
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to verify the archived default seed bundle"
+        }
+    - name: Verify Windows ARM64 package
+      if: matrix.id == 'windows-arm64'
+      shell: pwsh
+      run: |
+        $packageDir = "dist/acecode-${{ matrix.id }}"
+        $expectedExecutables = @(
+          "acecode.exe",
+          "acecode-desktop.exe",
+          "acecode-computer-use.exe"
+        )
+        foreach ($name in $expectedExecutables) {
+          $path = Join-Path $packageDir $name
+          if (-not (Test-Path -LiteralPath $path)) {
+            throw "Missing ARM64 package executable: $path"
+          }
+          $headers = (& dumpbin /headers $path | Out-String)
+          if ($LASTEXITCODE -ne 0 -or $headers -notmatch '(?im)\bAA64 machine\b') {
+            throw "$name is not an ARM64 PE executable"
+          }
+          Write-Host "${name}: ARM64"
+        }
+    - name: Upload artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}
+        path: acecode-${{ matrix.id }}.${{ matrix.archive_extension }}
+        if-no-files-found: error
+    - name: Upload Linux self-update archive
+      if: matrix.id == 'linux-x64' || matrix.id == 'linux-arm64'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-update
+        path: ${{ steps.linux-update.outputs.path }}
+        if-no-files-found: error
+    - name: Upload macOS installer DMG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-dmg
+        path: ${{ steps.macos-dmg.outputs.path }}
+        if-no-files-found: error
+    - name: Upload macOS self-update archive
+      if: runner.os == 'macOS'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-update
+        path: ${{ steps.macos-update.outputs.path }}
+        if-no-files-found: error
+    - name: Upload PDB
+      if: runner.os == 'Windows'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-pdb
+        path: build/**/acecode.pdb
+        if-no-files-found: warn
+    - name: Upload desktop PDB
+      if: runner.os == 'Windows' && matrix.build_desktop
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-desktop-pdb
+        path: build/**/acecode-desktop.pdb
+        if-no-files-found: warn
+    - name: Upload debug symbols (Linux)
+      if: runner.os == 'Linux'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-debug
+        path: build/${{ matrix.executable }}.debug
+        if-no-files-found: warn
+    - name: Upload desktop debug symbols (Linux)
+      if: runner.os == 'Linux' && matrix.build_desktop
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-desktop-debug
+        path: build/acecode-desktop.debug
+        if-no-files-found: warn
+    - name: Upload dSYM (macOS)
+      if: runner.os == 'macOS'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-dsym
+        path: build/${{ matrix.executable }}.dSYM
+        if-no-files-found: warn
+    - name: Upload desktop dSYM (macOS)
+      if: runner.os == 'macOS' && matrix.build_desktop
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-desktop-dsym
+        path: |
+          build/ACECode.app.dSYM
+          build/acecode-daemon.dSYM
+        if-no-files-found: warn
diff --git a/.github/workflows/recover-v1.0.6-platform-assets.yml b/.github/workflows/recover-v1.0.6-platform-assets.yml
new file mode 100644
index 000000000..e2973bf8b
--- /dev/null
+++ b/.github/workflows/recover-v1.0.6-platform-assets.yml
@@ -0,0 +1,876 @@
+name: Recover v1.0.6 Windows x64 asset
+'on':
+  push:
+    branches:
+    - codex/recover-v1.0.6-platform-assets
+permissions:
+  contents: read
+  actions: read
+concurrency:
+  group: recover-v1.0.6-windows-x64
+  cancel-in-progress: false
+jobs:
+  build-web-ui:
+    name: web-dist
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        ref: v1.0.6
+    - name: Verify immutable v1.0.6 source
+      shell: bash
+      run: |
+        test "$(git rev-parse HEAD)" = "e090be90c668f5fce760ed9b04d3f9a677d030eb"
+        git diff --exit-code
+    - name: Check bundled models.dev freshness for release
+      if: 'true'
+      shell: bash
+      run: |
+        python3 - <<'PY'
+        import datetime as dt
+        import json
+        from pathlib import Path
+
+        manifest_path = Path("assets/models_dev/MANIFEST.json")
+        try:
+            manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+            generated_at = dt.datetime.fromisoformat(
+                manifest["generated_at"].replace("Z", "+00:00")
+            )
+        except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
+            raise SystemExit(f"Invalid {manifest_path}: {exc}")
+
+        if generated_at.tzinfo is None:
+            raise SystemExit(f"{manifest_path}: generated_at must include a timezone")
+        now = dt.datetime.now(dt.timezone.utc)
+        age = now - generated_at.astimezone(dt.timezone.utc)
+        if age < -dt.timedelta(minutes=5):
+            raise SystemExit(f"{manifest_path}: generated_at is in the future")
+        if age > dt.timedelta(days=30):
+            raise SystemExit(
+                f"Bundled models.dev registry is {age.days} days old; "
+                "run scripts/sync_models_dev before creating a release tag"
+            )
+        print(f"Bundled models.dev registry age: {age.days} days")
+        PY
+    - name: Install pnpm
+      uses: pnpm/action-setup@v4
+      with:
+        version: 10.32.1
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: pnpm
+        cache-dependency-path: web/pnpm-lock.yaml
+    - name: Build web UI
+      shell: bash
+      run: |
+        cd web
+        pnpm install --frozen-lockfile
+        pnpm build
+    - name: Upload web UI
+      uses: actions/upload-artifact@v4
+      with:
+        name: web-dist
+        path: web/dist
+        if-no-files-found: error
+    timeout-minutes: 60
+    env:
+      ACE_RECOVERY_REF: refs/tags/v1.0.6
+      ACE_RECOVERY_REF_NAME: v1.0.6
+  build-and-package:
+    name: ${{ matrix.id }}
+    needs: build-web-ui
+    runs-on: ${{ matrix.os }}
+    env:
+      VCPKG_BINARY_SOURCES: clear;default,readwrite
+      ACE_RECOVERY_REF: refs/tags/v1.0.6
+      ACE_RECOVERY_REF_NAME: v1.0.6
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - id: windows-x64
+          os: windows-2022
+          triplet: x64-windows-static
+          executable: acecode.exe
+          archive_extension: zip
+          msvc_arch: amd64
+          build_desktop: true
+          cmake_extra_args: -DACECODE_BUILD_DESKTOP=ON
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        submodules: recursive
+        ref: v1.0.6
+    - name: Verify immutable v1.0.6 source
+      shell: bash
+      run: |
+        test "$(git rev-parse HEAD)" = "e090be90c668f5fce760ed9b04d3f9a677d030eb"
+        git diff --exit-code
+    - name: Resolve package version
+      id: package-version
+      shell: bash
+      run: |
+        declared_version="$(awk '$1 == "project(acecode" && $2 == "VERSION" { print $3; exit }' CMakeLists.txt)"
+        if [ -z "$declared_version" ]; then
+          echo "::error::Unable to read the ACECode version from CMakeLists.txt"
+          exit 1
+        fi
+        if [[ "$ACE_RECOVERY_REF" == refs/tags/v* && "${ACE_RECOVERY_REF_NAME#v}" != "$declared_version" ]]; then
+          echo "::error::Tag $ACE_RECOVERY_REF_NAME does not match CMake version $declared_version"
+          exit 1
+        fi
+        echo "version=$declared_version" >> "$GITHUB_OUTPUT"
+    - name: Check macOS release credentials
+      if: runner.os == 'macOS'
+      id: macos-release
+      shell: bash
+      env:
+        MACOS_CERTIFICATE_BASE64: ${{ secrets.MACOS_CERTIFICATE_BASE64 }}
+        MACOS_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
+        MACOS_INSTALLER_CERTIFICATE_BASE64: ${{ secrets.MACOS_INSTALLER_CERTIFICATE_BASE64 }}
+        MACOS_INSTALLER_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_INSTALLER_CERTIFICATE_PASSWORD }}
+        APPLE_ID: ${{ secrets.APPLE_ID }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      run: |
+        application_missing=()
+        for name in \
+          MACOS_CERTIFICATE_BASE64 \
+          MACOS_CERTIFICATE_PASSWORD \
+          APPLE_ID \
+          APPLE_TEAM_ID \
+          APPLE_APP_SPECIFIC_PASSWORD; do
+          if [ -z "${!name}" ]; then
+            application_missing+=("$name")
+          fi
+        done
+
+        if [ "${#application_missing[@]}" -ne 0 ]; then
+          if [[ "$ACE_RECOVERY_REF" == refs/tags/v* ]]; then
+            echo "::error::Tagged macOS application releases require secrets: ${application_missing[*]}"
+            exit 1
+          fi
+          echo "::notice::macOS signing/notarization disabled; missing: ${application_missing[*]}"
+          echo "enabled=false" >> "$GITHUB_OUTPUT"
+        else
+          echo "enabled=true" >> "$GITHUB_OUTPUT"
+        fi
+
+        installer_certificate_set=false
+        installer_password_set=false
+        if [ -n "$MACOS_INSTALLER_CERTIFICATE_BASE64" ]; then
+          installer_certificate_set=true
+        fi
+        if [ -n "$MACOS_INSTALLER_CERTIFICATE_PASSWORD" ]; then
+          installer_password_set=true
+        fi
+
+        if [ "$installer_certificate_set" != "$installer_password_set" ]; then
+          echo "::error::macOS Installer credentials must configure both MACOS_INSTALLER_CERTIFICATE_BASE64 and MACOS_INSTALLER_CERTIFICATE_PASSWORD"
+          exit 1
+        fi
+        if [ "$installer_certificate_set" = "true" ]; then
+          if [ "${#application_missing[@]}" -eq 0 ]; then
+            echo "pkg_enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "::notice::macOS PKG creation disabled because application signing/notarization is disabled"
+            echo "pkg_enabled=false" >> "$GITHUB_OUTPUT"
+          fi
+        else
+          if [[ "$ACE_RECOVERY_REF" == refs/tags/v* ]]; then
+            echo "::error::Tagged macOS releases require MACOS_INSTALLER_CERTIFICATE_BASE64 and MACOS_INSTALLER_CERTIFICATE_PASSWORD to build both PKGs"
+            exit 1
+          fi
+          echo "::notice::macOS PKG creation disabled; Developer ID Installer credentials are not configured"
+          echo "pkg_enabled=false" >> "$GITHUB_OUTPUT"
+        fi
+    - name: Configure MSVC
+      if: runner.os == 'Windows'
+      uses: ilammy/msvc-dev-cmd@v1
+      with:
+        arch: ${{ matrix.msvc_arch }}
+    - name: Install Linux ARMv7 cross toolchain
+      if: matrix.id == 'linux-armv7'
+      shell: bash
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y \
+          binutils-arm-linux-gnueabihf \
+          gcc-arm-linux-gnueabihf \
+          g++-arm-linux-gnueabihf \
+          qemu-user
+    - name: Run vcpkg
+      uses: lukka/run-vcpkg@v11
+    - name: Restore vcpkg binary cache
+      uses: actions/cache@v4
+      with:
+        path: ${{ env.VCPKG_DEFAULT_BINARY_CACHE }}
+        key: vcpkg-v2-${{ matrix.os }}-${{ matrix.triplet }}-${{ hashFiles('vcpkg.json', 'vcpkg-configuration.json', 'ports/**')
+          }}
+        restore-keys: |
+          vcpkg-v2-${{ matrix.os }}-${{ matrix.triplet }}-
+    - name: Install Linux desktop dependencies
+      if: runner.os == 'Linux' && matrix.build_desktop
+      shell: bash
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y libwebkit2gtk-4.1-dev
+    - name: Download web UI
+      uses: actions/download-artifact@v4
+      with:
+        name: web-dist
+        path: web/dist
+    - name: Configure
+      shell: bash
+      run: |
+        cmake -S . -B build -G Ninja \
+          -DCMAKE_BUILD_TYPE=MinSizeRel \
+          -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" \
+          -DVCPKG_TARGET_TRIPLET="${{ matrix.triplet }}" \
+          -DBUILD_TESTING=OFF \
+          ${{ matrix.cmake_extra_args }}
+    - name: Build
+      shell: bash
+      run: |
+        cmake --build build --config MinSizeRel --target acecode --parallel 2
+    - name: Build desktop
+      if: matrix.build_desktop
+      shell: bash
+      run: |
+        cmake --build build --config MinSizeRel --target acecode-desktop --parallel 2
+    - name: Verify Linux ARMv7 executable
+      if: matrix.id == 'linux-armv7'
+      shell: bash
+      run: |
+        export LC_ALL=C
+        elf_header="$(arm-linux-gnueabihf-readelf -h build/acecode)"
+        arm_attributes="$(arm-linux-gnueabihf-readelf -A build/acecode)"
+        program_headers="$(arm-linux-gnueabihf-readelf -l build/acecode)"
+
+        printf '%s\n' "$elf_header"
+        printf '%s\n' "$arm_attributes"
+
+        grep -Eq 'Class:[[:space:]]+ELF32' <<<"$elf_header"
+        grep -Eq 'Machine:[[:space:]]+ARM' <<<"$elf_header"
+        grep -Eq 'Tag_CPU_arch:[[:space:]]+v7' <<<"$arm_attributes"
+        grep -Eq 'Tag_ABI_VFP_args:[[:space:]]+VFP registers' <<<"$arm_attributes"
+        grep -Fq '/lib/ld-linux-armhf.so.3' <<<"$program_headers"
+
+        version_output="$(qemu-arm -L /usr/arm-linux-gnueabihf build/acecode --version)"
+        printf '%s\n' "$version_output"
+        grep -Eq '^acecode v[^[:space:]]+$' <<<"$version_output"
+    - name: Verify bundled resources in macOS app
+      if: runner.os == 'macOS' && matrix.build_desktop
+      shell: bash
+      run: |
+        registry_dir="build/ACECode.app/Contents/Resources/share/acecode/models_dev"
+        file_count="$(find "$registry_dir" -type f | wc -l | tr -d '[:space:]')"
+        if [ "$file_count" != "3" ]; then
+          echo "Expected exactly 3 models.dev resources in $registry_dir, found $file_count" >&2
+          exit 1
+        fi
+        for file in api.json MANIFEST.json LICENSE; do
+          if [ ! -f "$registry_dir/$file" ] ||
+             ! cmp -s "assets/models_dev/$file" "$registry_dir/$file"; then
+            echo "Missing or mismatched macOS app models.dev resource: $file" >&2
+            exit 1
+          fi
+        done
+        python3 scripts/verify_seed_bundle.py \
+          --source assets/seed \
+          --packaged build/ACECode.app/Contents/Resources/share/acecode/seed
+    - name: Extract debug symbols (Linux)
+      if: runner.os == 'Linux'
+      shell: bash
+      run: |
+        binutils_prefix=""
+        if [ "${{ matrix.id }}" = "linux-armv7" ]; then
+          binutils_prefix="arm-linux-gnueabihf-"
+        fi
+        "${binutils_prefix}objcopy" --only-keep-debug \
+          "build/${{ matrix.executable }}" \
+          "build/${{ matrix.executable }}.debug"
+        "${binutils_prefix}strip" --strip-unneeded "build/${{ matrix.executable }}"
+        "${binutils_prefix}objcopy" \
+          --add-gnu-debuglink="build/${{ matrix.executable }}.debug" \
+          "build/${{ matrix.executable }}"
+    - name: Extract desktop debug symbols (Linux)
+      if: runner.os == 'Linux' && matrix.build_desktop
+      shell: bash
+      run: |
+        objcopy --only-keep-debug "build/acecode-desktop" "build/acecode-desktop.debug"
+        strip --strip-unneeded "build/acecode-desktop"
+        objcopy --add-gnu-debuglink="build/acecode-desktop.debug" "build/acecode-desktop"
+    - name: Extract debug symbols (macOS)
+      if: runner.os == 'macOS'
+      shell: bash
+      run: |
+        dsymutil "build/${{ matrix.executable }}" -o "build/${{ matrix.executable }}.dSYM"
+        strip "build/${{ matrix.executable }}"
+    - name: Extract desktop debug symbols (macOS)
+      if: runner.os == 'macOS' && matrix.build_desktop
+      shell: bash
+      run: |
+        app_exec="build/ACECode.app/Contents/MacOS/ACECode"
+        app_daemon="build/ACECode.app/Contents/MacOS/acecode-daemon"
+        if [ ! -f "$app_exec" ]; then
+          echo "Missing desktop app executable: $app_exec" >&2
+          exit 1
+        fi
+        if [ ! -f "$app_daemon" ]; then
+          echo "Missing desktop app daemon: $app_daemon" >&2
+          exit 1
+        fi
+        dsymutil "$app_exec" -o "build/ACECode.app.dSYM"
+        strip "$app_exec"
+        dsymutil "$app_daemon" -o "build/acecode-daemon.dSYM"
+        strip "$app_daemon"
+    - name: Import Developer ID identities (macOS)
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      id: macos-keychain
+      shell: bash
+      env:
+        MACOS_CERTIFICATE_BASE64: ${{ secrets.MACOS_CERTIFICATE_BASE64 }}
+        MACOS_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
+        MACOS_INSTALLER_CERTIFICATE_BASE64: ${{ secrets.MACOS_INSTALLER_CERTIFICATE_BASE64 }}
+        MACOS_INSTALLER_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_INSTALLER_CERTIFICATE_PASSWORD }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        MACOS_CODESIGN_IDENTITY: ${{ vars.MACOS_CODESIGN_IDENTITY }}
+        MACOS_INSTALLER_SIGNING_IDENTITY: ${{ vars.MACOS_INSTALLER_SIGNING_IDENTITY }}
+      run: |
+        set +x
+        certificate_path="$RUNNER_TEMP/acecode-developer-id.p12"
+        installer_certificate_path="$RUNNER_TEMP/acecode-developer-id-installer.p12"
+        keychain_path="$RUNNER_TEMP/acecode-signing.keychain-db"
+        keychain_password="$(openssl rand -hex 32)"
+
+        printf '%s' "$MACOS_CERTIFICATE_BASE64" | /usr/bin/base64 -D > "$certificate_path"
+        chmod 600 "$certificate_path"
+        if [ "${{ steps.macos-release.outputs.pkg_enabled }}" = "true" ]; then
+          printf '%s' "$MACOS_INSTALLER_CERTIFICATE_BASE64" | /usr/bin/base64 -D > "$installer_certificate_path"
+          chmod 600 "$installer_certificate_path"
+        fi
+        security create-keychain -p "$keychain_password" "$keychain_path"
+        security set-keychain-settings -lut 21600 "$keychain_path"
+        security unlock-keychain -p "$keychain_password" "$keychain_path"
+
+        existing_user_keychains=()
+        while IFS= read -r existing_keychain; do
+          if [ -n "$existing_keychain" ]; then
+            existing_user_keychains+=("$existing_keychain")
+          fi
+        done < <(
+          security list-keychains -d user |
+            sed -E 's/^[[:space:]]*"//; s/"[[:space:]]*$//'
+        )
+        security list-keychains -d user -s \
+          "$keychain_path" \
+          "${existing_user_keychains[@]}"
+
+        security import "$certificate_path" \
+          -k "$keychain_path" \
+          -P "$MACOS_CERTIFICATE_PASSWORD" \
+          -f pkcs12 \
+          -T /usr/bin/codesign \
+          -T /usr/bin/security
+        if [ "${{ steps.macos-release.outputs.pkg_enabled }}" = "true" ]; then
+          security import "$installer_certificate_path" \
+            -k "$keychain_path" \
+            -P "$MACOS_INSTALLER_CERTIFICATE_PASSWORD" \
+            -f pkcs12 \
+            -T /usr/bin/pkgbuild \
+            -T /usr/bin/productbuild \
+            -T /usr/bin/security
+        fi
+        security set-key-partition-list \
+          -S apple-tool:,apple: \
+          -s \
+          -k "$keychain_password" \
+          "$keychain_path"
+
+        identity_record="$(security find-identity -v -p codesigning "$keychain_path" |
+          awk '/Developer ID Application:/ { print; exit }')"
+        identity_fingerprint="$(printf '%s\n' "$identity_record" | awk '{ print $2 }')"
+        identity_name="$(printf '%s\n' "$identity_record" | awk -F '"' '{ print $2 }')"
+        if [[ ! "$identity_fingerprint" =~ ^[[:xdigit:]]{40}$ ]] || [ -z "$identity_name" ]; then
+          echo "::error::No Developer ID Application identity found in the imported certificate"
+          exit 1
+        fi
+        if [ -n "$MACOS_CODESIGN_IDENTITY" ] && [ "$identity_name" != "$MACOS_CODESIGN_IDENTITY" ]; then
+          echo "::error::Imported signing identity does not match MACOS_CODESIGN_IDENTITY"
+          exit 1
+        fi
+        if [ -n "$APPLE_TEAM_ID" ] && [[ "$identity_name" != *"($APPLE_TEAM_ID)" ]]; then
+          echo "::error::Developer ID Application identity does not match APPLE_TEAM_ID"
+          exit 1
+        fi
+
+        if [ "${{ steps.macos-release.outputs.pkg_enabled }}" = "true" ]; then
+          installer_identity_record="$(security find-identity -v -p basic "$keychain_path" |
+            awk '/Developer ID Installer:/ { print; exit }')"
+          installer_identity_fingerprint="$(printf '%s\n' "$installer_identity_record" | awk '{ print $2 }')"
+          installer_identity_name="$(printf '%s\n' "$installer_identity_record" | awk -F '"' '{ print $2 }')"
+          if [[ ! "$installer_identity_fingerprint" =~ ^[[:xdigit:]]{40}$ ]] || [ -z "$installer_identity_name" ]; then
+            echo "::error::No Developer ID Installer identity found in the imported certificate"
+            exit 1
+          fi
+          if [ -n "$MACOS_INSTALLER_SIGNING_IDENTITY" ] && [ "$installer_identity_name" != "$MACOS_INSTALLER_SIGNING_IDENTITY" ]; then
+            echo "::error::Imported Installer identity does not match MACOS_INSTALLER_SIGNING_IDENTITY"
+            exit 1
+          fi
+          if [ -n "$APPLE_TEAM_ID" ] && [[ "$installer_identity_name" != *"($APPLE_TEAM_ID)" ]]; then
+            echo "::error::Developer ID Installer identity does not match APPLE_TEAM_ID"
+            exit 1
+          fi
+          echo "installer_identity=$installer_identity_name" >> "$GITHUB_OUTPUT"
+        fi
+
+        echo "keychain=$keychain_path" >> "$GITHUB_OUTPUT"
+        # Sign by the certificate fingerprint. codesign can fail to resolve a
+        # human-readable identity name inside an isolated temporary keychain.
+        echo "identity=$identity_fingerprint" >> "$GITHUB_OUTPUT"
+    - name: Sign macOS release payloads
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      shell: bash
+      run: |
+        scripts/macos_codesign.sh \
+          --identity "${{ steps.macos-keychain.outputs.identity }}" \
+          --keychain "${{ steps.macos-keychain.outputs.keychain }}" \
+          --binary "build/${{ matrix.executable }}" \
+          --binary "build/acecode-computer-use" \
+          --app "build/ACECode.app"
+    - name: Notarize and staple macOS app
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      shell: bash
+      env:
+        APPLE_ID: ${{ secrets.APPLE_ID }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      run: |-
+        xcrun() {
+          if [[ "${1:-}" != "stapler" ]]; then
+            command xcrun "$@"
+            return $?
+          fi
+          local result=0
+          for attempt in 1 2 3 4 5 6; do
+            if command xcrun "$@"; then return 0; else result=$?; fi
+            if [[ "$result" != "68" || "$attempt" == "6" ]]; then return "$result"; fi
+            echo "Apple ticket service disconnected (68), retry $attempt/6 in 15 seconds"
+            sleep 15
+          done
+          return "$result"
+        }
+        export -f xcrun
+        scripts/macos_notarize_app.sh --app "build/ACECode.app"
+    - name: Test macOS installer integration
+      if: runner.os == 'macOS'
+      shell: bash
+      run: |
+        bash tests/scripts/macos_installer_test.sh
+        python3 tests/scripts/macos_installer_release_test.py
+    - name: Create current-user macOS PKG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.pkg_enabled == 'true'
+      id: macos-pkg
+      shell: bash
+      run: |
+        pkg_path="ACECode-${{ steps.package-version.outputs.version }}-${{ matrix.id }}.pkg"
+        scripts/macos_create_pkg.sh \
+          --app "build/ACECode.app" \
+          --output "$pkg_path" \
+          --installer-identity "${{ steps.macos-keychain.outputs.installer_identity }}" \
+          --keychain "${{ steps.macos-keychain.outputs.keychain }}"
+        echo "path=$pkg_path" >> "$GITHUB_OUTPUT"
+    - name: Notarize and validate macOS PKG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.pkg_enabled == 'true'
+      shell: bash
+      env:
+        APPLE_ID: ${{ secrets.APPLE_ID }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      run: |-
+        xcrun() {
+          if [[ "${1:-}" != "stapler" ]]; then
+            command xcrun "$@"
+            return $?
+          fi
+          local result=0
+          for attempt in 1 2 3 4 5 6; do
+            if command xcrun "$@"; then return 0; else result=$?; fi
+            if [[ "$result" != "68" || "$attempt" == "6" ]]; then return "$result"; fi
+            echo "Apple ticket service disconnected (68), retry $attempt/6 in 15 seconds"
+            sleep 15
+          done
+          return "$result"
+        }
+        export -f xcrun
+        scripts/macos_notarize_pkg.sh --pkg "${{ steps.macos-pkg.outputs.path }}"
+    - name: Upload macOS PKG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.pkg_enabled == 'true'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-pkg
+        path: ${{ steps.macos-pkg.outputs.path }}
+        if-no-files-found: error
+    - name: Build signed and notarized macOS installer DMG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      id: macos-dmg
+      shell: bash
+      env:
+        APPLE_ID: ${{ secrets.APPLE_ID }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      run: |
+        xcrun() {
+          if [[ "${1:-}" != "stapler" ]]; then
+            command xcrun "$@"
+            return $?
+          fi
+          local result=0
+          for attempt in 1 2 3 4 5 6; do
+            if command xcrun "$@"; then return 0; else result=$?; fi
+            if [[ "$result" != "68" || "$attempt" == "6" ]]; then return "$result"; fi
+            echo "Apple ticket service disconnected (68), retry $attempt/6 in 15 seconds"
+            sleep 15
+          done
+          return "$result"
+        }
+        export -f xcrun
+        dmg_path="ACECode-${{ steps.package-version.outputs.version }}-${{ matrix.id }}.dmg"
+        bash scripts/macos_create_installer_dmg.sh \
+          --app "build/ACECode.app" \
+          --output "$dmg_path" \
+          --arch "${{ matrix.installer_arch }}" \
+          --identity "${{ steps.macos-keychain.outputs.identity }}" \
+          --keychain "${{ steps.macos-keychain.outputs.keychain }}"
+        echo "path=$dmg_path" >> "$GITHUB_OUTPUT"
+    - name: Create macOS self-update archive
+      if: runner.os == 'macOS'
+      id: macos-update
+      shell: bash
+      run: |
+        unsigned_suffix=""
+        trust_args=()
+        if [ "${{ steps.macos-release.outputs.enabled }}" = "true" ]; then
+          trust_args+=(--require-trusted)
+        else
+          unsigned_suffix="-unsigned"
+        fi
+        update_path="ACECode-${{ steps.package-version.outputs.version }}-${{ matrix.id }}-update${unsigned_suffix}.zip"
+        scripts/macos_create_update_zip.sh \
+          --app "build/ACECode.app" \
+          --output "$update_path" \
+          "${trust_args[@]}"
+        echo "path=$update_path" >> "$GITHUB_OUTPUT"
+    - name: Package (Unix)
+      if: runner.os != 'Windows'
+      shell: bash
+      run: |
+        package_dir="dist/acecode-${{ matrix.id }}"
+        mkdir -p "$package_dir"
+
+        validate_models_dev_registry() {
+          registry_dir="$1"
+          file_count="$(find "$registry_dir" -type f | wc -l | tr -d '[:space:]')"
+          if [ "$file_count" != "3" ]; then
+            echo "Expected exactly 3 models.dev files in $registry_dir, found $file_count" >&2
+            exit 1
+          fi
+          for file in api.json MANIFEST.json LICENSE; do
+            if [ ! -f "$registry_dir/$file" ] ||
+               ! cmp -s "assets/models_dev/$file" "$registry_dir/$file"; then
+              echo "Missing or mismatched models.dev package file: $registry_dir/$file" >&2
+              exit 1
+            fi
+          done
+        }
+
+        if [ ! -f "build/${{ matrix.executable }}" ]; then
+          echo "Missing terminal executable: build/${{ matrix.executable }}" >&2
+          exit 1
+        fi
+        cp "build/${{ matrix.executable }}" "$package_dir/"
+        cp README.md README_CN.md "$package_dir/"
+        cmake --install build \
+          --config MinSizeRel \
+          --prefix "$PWD/$package_dir" \
+          --component models_dev_registry
+        cmake --install build \
+          --config MinSizeRel \
+          --prefix "$PWD/$package_dir" \
+          --component default_seed_bundle
+        cmake --install build --config MinSizeRel --prefix "$PWD/$package_dir" --component whatsapp_channel
+        if [ "$RUNNER_OS" = "macOS" ]; then
+          cmake --install build --config MinSizeRel --prefix "$PWD/$package_dir" --component computer_use_runtime
+          test -x "$package_dir/acecode-computer-use"
+          test -x "build/ACECode.app/Contents/MacOS/acecode-computer-use"
+        fi
+        validate_models_dev_registry "$package_dir/share/acecode/models_dev"
+        python3 scripts/verify_seed_bundle.py \
+          --source assets/seed \
+          --packaged "$package_dir/share/acecode/seed"
+
+        if [ "${{ matrix.build_desktop }}" = "true" ]; then
+          if [ "$RUNNER_OS" = "macOS" ]; then
+            if [ ! -d "build/ACECode.app" ]; then
+              echo "Missing desktop app bundle: build/ACECode.app" >&2
+              exit 1
+            fi
+            cp -r "build/ACECode.app" "$package_dir/"
+          else
+            if [ ! -f "build/acecode-desktop" ]; then
+              echo "Missing desktop executable: build/acecode-desktop" >&2
+              exit 1
+            fi
+            cp "build/acecode-desktop" "$package_dir/"
+            cp "build/acecode-logo.png" "$package_dir/"
+          fi
+        fi
+        legacy="$(find "$package_dir" -maxdepth 1 -iname 'ace-browser-*' -print -quit)"
+        if [ -n "$legacy" ]; then
+          echo "Legacy browser artifact must not be packaged: $legacy" >&2
+          exit 1
+        fi
+        tar -C dist -czf "acecode-${{ matrix.id }}.tar.gz" "acecode-${{ matrix.id }}"
+
+        verify_root="$(mktemp -d)"
+        tar -xzf "acecode-${{ matrix.id }}.tar.gz" -C "$verify_root"
+        extracted_package="$verify_root/acecode-${{ matrix.id }}"
+        validate_models_dev_registry "$extracted_package/share/acecode/models_dev"
+        python3 scripts/verify_seed_bundle.py \
+          --source assets/seed \
+          --packaged "$extracted_package/share/acecode/seed"
+        if [ "$RUNNER_OS" = "macOS" ]; then
+          test -x "$extracted_package/acecode-computer-use"
+          test -x "$extracted_package/ACECode.app/Contents/MacOS/acecode-computer-use"
+          validate_models_dev_registry \
+            "$extracted_package/ACECode.app/Contents/Resources/share/acecode/models_dev"
+          python3 scripts/verify_seed_bundle.py \
+            --source assets/seed \
+            --packaged "$extracted_package/ACECode.app/Contents/Resources/share/acecode/seed"
+        fi
+        rm -rf -- "$verify_root"
+    - name: Create Linux self-update archive
+      if: matrix.id == 'linux-x64' || matrix.id == 'linux-arm64'
+      id: linux-update
+      shell: bash
+      run: |
+        update_path="acecode-${{ steps.package-version.outputs.version }}-${{ matrix.id }}-update.zip"
+        bash scripts/linux_create_update_zip.sh \
+          --package-dir "dist/acecode-${{ matrix.id }}" \
+          --output "$update_path" \
+          --expected-version "${{ steps.package-version.outputs.version }}"
+        echo "path=$update_path" >> "$GITHUB_OUTPUT"
+    - name: Clean up macOS signing material
+      if: always() && runner.os == 'macOS'
+      shell: bash
+      run: |
+        set +e
+        security delete-keychain "$RUNNER_TEMP/acecode-signing.keychain-db" 2>/dev/null
+        rm -f -- \
+          "$RUNNER_TEMP/acecode-developer-id.p12" \
+          "$RUNNER_TEMP/acecode-developer-id-installer.p12"
+    - name: Package (Windows)
+      if: runner.os == 'Windows'
+      shell: pwsh
+      run: |
+        $packageDir = "dist/acecode-${{ matrix.id }}"
+        New-Item -ItemType Directory -Force -Path $packageDir | Out-Null
+
+        function Assert-ModelsDevRegistry([string] $RegistryDir) {
+          if (-not (Test-Path -LiteralPath $RegistryDir -PathType Container)) {
+            throw "Missing models.dev directory: $RegistryDir"
+          }
+          $actualFiles = @(Get-ChildItem -LiteralPath $RegistryDir -File -Recurse)
+          if ($actualFiles.Count -ne 3) {
+            throw "Expected exactly 3 models.dev files in ${RegistryDir}, found $($actualFiles.Count)"
+          }
+          foreach ($name in @("api.json", "MANIFEST.json", "LICENSE")) {
+            $source = Join-Path "assets/models_dev" $name
+            $packaged = Join-Path $RegistryDir $name
+            if (-not (Test-Path -LiteralPath $packaged -PathType Leaf)) {
+              throw "Missing models.dev package file: $packaged"
+            }
+            $sourceHash = (Get-FileHash -LiteralPath $source -Algorithm SHA256).Hash
+            $packagedHash = (Get-FileHash -LiteralPath $packaged -Algorithm SHA256).Hash
+            if ($sourceHash -ne $packagedHash) {
+              throw "Mismatched models.dev package file: $packaged"
+            }
+          }
+        }
+
+        $terminalExe = "build/${{ matrix.executable }}"
+        if (-not (Test-Path -LiteralPath $terminalExe)) {
+          throw "Missing terminal executable: $terminalExe"
+        }
+        Copy-Item -LiteralPath $terminalExe -Destination "$packageDir/"
+        Copy-Item "README.md","README_CN.md" "$packageDir/"
+        $packageRoot = (Resolve-Path -LiteralPath $packageDir).Path
+        & cmake --install build --config MinSizeRel --prefix $packageRoot --component models_dev_registry
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to install the bundled models.dev registry"
+        }
+        & cmake --install build --config MinSizeRel --prefix $packageRoot --component default_seed_bundle
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to install the default seed bundle"
+        }
+        & cmake --install build --config MinSizeRel --prefix $packageRoot --component whatsapp_channel
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to install the WhatsApp channel bridge"
+        }
+        & cmake --install build --config MinSizeRel --prefix $packageRoot --component computer_use_runtime
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to install the Computer Use runtime"
+        }
+        $computerUseExe = Join-Path $packageRoot "acecode-computer-use.exe"
+        if (-not (Test-Path -LiteralPath $computerUseExe -PathType Leaf) -or
+            (Get-Item -LiteralPath $computerUseExe).Length -eq 0) {
+          throw "Missing Computer Use runtime: $computerUseExe"
+        }
+        Assert-ModelsDevRegistry (Join-Path $packageDir "share/acecode/models_dev")
+        & python scripts/verify_seed_bundle.py `
+          --source assets/seed `
+          --packaged (Join-Path $packageDir "share/acecode/seed")
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to verify the packaged default seed bundle"
+        }
+
+        if ("${{ matrix.build_desktop }}" -eq "true") {
+          $desktopCandidates = @(
+            "build/acecode-desktop.exe",
+            "build/Release/acecode-desktop.exe",
+            "build/Debug/acecode-desktop.exe",
+            "build/RelWithDebInfo/acecode-desktop.exe",
+            "build/MinSizeRel/acecode-desktop.exe"
+          )
+          $desktopExe = $desktopCandidates | Where-Object { Test-Path -LiteralPath $_ } | Select-Object -First 1
+          if (-not $desktopExe) {
+            $desktopExe = Get-ChildItem -Path "build" -Recurse -Filter "acecode-desktop.exe" -File |
+              Select-Object -ExpandProperty FullName -First 1
+          }
+          if (-not $desktopExe) {
+            throw "Missing desktop executable: acecode-desktop.exe"
+          }
+          Copy-Item -LiteralPath $desktopExe -Destination "$packageDir/"
+        }
+        $legacyBrowserArtifact = Get-ChildItem -LiteralPath $packageDir -Filter "ace-browser-*" -Force |
+          Select-Object -First 1
+        if ($legacyBrowserArtifact) {
+          throw "Legacy browser artifact must not be packaged: $($legacyBrowserArtifact.FullName)"
+        }
+        Compress-Archive -Path "$packageDir/*" -DestinationPath "acecode-${{ matrix.id }}.zip" -Force
+
+        $verifyRoot = Join-Path $env:RUNNER_TEMP ("acecode-package-verify-" + [Guid]::NewGuid().ToString("N"))
+        New-Item -ItemType Directory -Path $verifyRoot | Out-Null
+        Expand-Archive -LiteralPath "acecode-${{ matrix.id }}.zip" -DestinationPath $verifyRoot
+        $archivedComputerUseExe = Join-Path $verifyRoot "acecode-computer-use.exe"
+        if (-not (Test-Path -LiteralPath $archivedComputerUseExe -PathType Leaf) -or
+            (Get-FileHash -LiteralPath $archivedComputerUseExe -Algorithm SHA256).Hash -ne
+              (Get-FileHash -LiteralPath $computerUseExe -Algorithm SHA256).Hash) {
+          throw "Archived Computer Use runtime is missing or does not match the build"
+        }
+        Assert-ModelsDevRegistry (Join-Path $verifyRoot "share/acecode/models_dev")
+        & python scripts/verify_seed_bundle.py `
+          --source assets/seed `
+          --packaged (Join-Path $verifyRoot "share/acecode/seed")
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to verify the archived default seed bundle"
+        }
+    - name: Verify Windows ARM64 package
+      if: matrix.id == 'windows-arm64'
+      shell: pwsh
+      run: |
+        $packageDir = "dist/acecode-${{ matrix.id }}"
+        $expectedExecutables = @(
+          "acecode.exe",
+          "acecode-desktop.exe",
+          "acecode-computer-use.exe"
+        )
+        foreach ($name in $expectedExecutables) {
+          $path = Join-Path $packageDir $name
+          if (-not (Test-Path -LiteralPath $path)) {
+            throw "Missing ARM64 package executable: $path"
+          }
+          $headers = (& dumpbin /headers $path | Out-String)
+          if ($LASTEXITCODE -ne 0 -or $headers -notmatch '(?im)\bAA64 machine\b') {
+            throw "$name is not an ARM64 PE executable"
+          }
+          Write-Host "${name}: ARM64"
+        }
+    - name: Upload artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}
+        path: acecode-${{ matrix.id }}.${{ matrix.archive_extension }}
+        if-no-files-found: error
+    - name: Upload Linux self-update archive
+      if: matrix.id == 'linux-x64' || matrix.id == 'linux-arm64'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-update
+        path: ${{ steps.linux-update.outputs.path }}
+        if-no-files-found: error
+    - name: Upload macOS installer DMG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-dmg
+        path: ${{ steps.macos-dmg.outputs.path }}
+        if-no-files-found: error
+    - name: Upload macOS self-update archive
+      if: runner.os == 'macOS'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-update
+        path: ${{ steps.macos-update.outputs.path }}
+        if-no-files-found: error
+    - name: Upload PDB
+      if: runner.os == 'Windows'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-pdb
+        path: build/**/acecode.pdb
+        if-no-files-found: warn
+    - name: Upload desktop PDB
+      if: runner.os == 'Windows' && matrix.build_desktop
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-desktop-pdb
+        path: build/**/acecode-desktop.pdb
+        if-no-files-found: warn
+    - name: Upload debug symbols (Linux)
+      if: runner.os == 'Linux'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-debug
+        path: build/${{ matrix.executable }}.debug
+        if-no-files-found: warn
+    - name: Upload desktop debug symbols (Linux)
+      if: runner.os == 'Linux' && matrix.build_desktop
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-desktop-debug
+        path: build/acecode-desktop.debug
+        if-no-files-found: warn
+    - name: Upload dSYM (macOS)
+      if: runner.os == 'macOS'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-dsym
+        path: build/${{ matrix.executable }}.dSYM
+        if-no-files-found: warn
+    - name: Upload desktop dSYM (macOS)
+      if: runner.os == 'macOS' && matrix.build_desktop
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-desktop-dsym
+        path: |
+          build/ACECode.app.dSYM
+          build/acecode-daemon.dSYM
+        if-no-files-found: warn
+    timeout-minutes: 90
diff --git a/.github/workflows/recover-v1.0.7-platform-assets.yml b/.github/workflows/recover-v1.0.7-platform-assets.yml
new file mode 100644
index 000000000..f6bbfac7f
--- /dev/null
+++ b/.github/workflows/recover-v1.0.7-platform-assets.yml
@@ -0,0 +1,919 @@
+name: Recover v1.0.7 macOS x64 assets
+'on':
+  push:
+    branches:
+    - claude/recover-v1.0.7-platform-assets
+permissions:
+  contents: read
+  actions: read
+concurrency:
+  group: recover-v1.0.7-macos-x64
+  cancel-in-progress: false
+jobs:
+  build-web-ui:
+    name: web-dist
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        ref: v1.0.7
+    - name: Verify immutable v1.0.7 source
+      shell: bash
+      run: |
+        test "$(git rev-parse HEAD)" = "bb779f1f81e55536e56d21c3e5d66be1b2c1158e"
+        git diff --exit-code
+    - name: Check bundled models.dev freshness for release
+      if: 'true'
+      shell: bash
+      run: |
+        python3 - <<'PY'
+        import datetime as dt
+        import json
+        from pathlib import Path
+
+        manifest_path = Path("assets/models_dev/MANIFEST.json")
+        try:
+            manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+            generated_at = dt.datetime.fromisoformat(
+                manifest["generated_at"].replace("Z", "+00:00")
+            )
+        except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
+            raise SystemExit(f"Invalid {manifest_path}: {exc}")
+
+        if generated_at.tzinfo is None:
+            raise SystemExit(f"{manifest_path}: generated_at must include a timezone")
+        now = dt.datetime.now(dt.timezone.utc)
+        age = now - generated_at.astimezone(dt.timezone.utc)
+        if age < -dt.timedelta(minutes=5):
+            raise SystemExit(f"{manifest_path}: generated_at is in the future")
+        if age > dt.timedelta(days=30):
+            raise SystemExit(
+                f"Bundled models.dev registry is {age.days} days old; "
+                "run scripts/sync_models_dev before creating a release tag"
+            )
+        print(f"Bundled models.dev registry age: {age.days} days")
+        PY
+    - name: Install pnpm
+      uses: pnpm/action-setup@v4
+      with:
+        version: 10.32.1
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: pnpm
+        cache-dependency-path: web/pnpm-lock.yaml
+    - name: Build web UI
+      shell: bash
+      run: |
+        cd web
+        pnpm install --frozen-lockfile
+        pnpm build
+    - name: Upload web UI
+      uses: actions/upload-artifact@v4
+      with:
+        name: web-dist
+        path: web/dist
+        if-no-files-found: error
+    timeout-minutes: 60
+    env:
+      ACE_RECOVERY_REF: refs/tags/v1.0.7
+      ACE_RECOVERY_REF_NAME: v1.0.7
+  build-and-package:
+    name: ${{ matrix.id }}
+    needs: build-web-ui
+    runs-on: ${{ matrix.os }}
+    env:
+      VCPKG_BINARY_SOURCES: clear;default,readwrite
+      ACE_RECOVERY_REF: refs/tags/v1.0.7
+      ACE_RECOVERY_REF_NAME: v1.0.7
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - id: macos-x64
+          os: macos-15
+          installer_arch: x64
+          triplet: x64-osx
+          executable: acecode
+          archive_extension: tar.gz
+          build_desktop: true
+          cmake_extra_args: -DCMAKE_OSX_ARCHITECTURES=x86_64 -DACECODE_BUILD_DESKTOP=ON
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        submodules: recursive
+        ref: v1.0.7
+    - name: Verify immutable v1.0.7 source
+      shell: bash
+      run: |
+        test "$(git rev-parse HEAD)" = "bb779f1f81e55536e56d21c3e5d66be1b2c1158e"
+        git diff --exit-code
+    - name: Resolve package version
+      id: package-version
+      shell: bash
+      run: |
+        declared_version="$(awk '$1 == "project(acecode" && $2 == "VERSION" { print $3; exit }' CMakeLists.txt)"
+        if [ -z "$declared_version" ]; then
+          echo "::error::Unable to read the ACECode version from CMakeLists.txt"
+          exit 1
+        fi
+        if [[ "$ACE_RECOVERY_REF" == refs/tags/v* && "${ACE_RECOVERY_REF_NAME#v}" != "$declared_version" ]]; then
+          echo "::error::Tag $ACE_RECOVERY_REF_NAME does not match CMake version $declared_version"
+          exit 1
+        fi
+        echo "version=$declared_version" >> "$GITHUB_OUTPUT"
+    - name: Check macOS release credentials
+      if: runner.os == 'macOS'
+      id: macos-release
+      shell: bash
+      env:
+        MACOS_CERTIFICATE_BASE64: ${{ secrets.MACOS_CERTIFICATE_BASE64 }}
+        MACOS_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
+        MACOS_INSTALLER_CERTIFICATE_BASE64: ${{ secrets.MACOS_INSTALLER_CERTIFICATE_BASE64 }}
+        MACOS_INSTALLER_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_INSTALLER_CERTIFICATE_PASSWORD }}
+        APPLE_ID: ${{ secrets.APPLE_ID }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      run: |
+        application_missing=()
+        for name in \
+          MACOS_CERTIFICATE_BASE64 \
+          MACOS_CERTIFICATE_PASSWORD \
+          APPLE_ID \
+          APPLE_TEAM_ID \
+          APPLE_APP_SPECIFIC_PASSWORD; do
+          if [ -z "${!name}" ]; then
+            application_missing+=("$name")
+          fi
+        done
+
+        if [ "${#application_missing[@]}" -ne 0 ]; then
+          if [[ "$ACE_RECOVERY_REF" == refs/tags/v* ]]; then
+            echo "::error::Tagged macOS application releases require secrets: ${application_missing[*]}"
+            exit 1
+          fi
+          echo "::notice::macOS signing/notarization disabled; missing: ${application_missing[*]}"
+          echo "enabled=false" >> "$GITHUB_OUTPUT"
+        else
+          echo "enabled=true" >> "$GITHUB_OUTPUT"
+        fi
+
+        installer_certificate_set=false
+        installer_password_set=false
+        if [ -n "$MACOS_INSTALLER_CERTIFICATE_BASE64" ]; then
+          installer_certificate_set=true
+        fi
+        if [ -n "$MACOS_INSTALLER_CERTIFICATE_PASSWORD" ]; then
+          installer_password_set=true
+        fi
+
+        if [ "$installer_certificate_set" != "$installer_password_set" ]; then
+          echo "::error::macOS Installer credentials must configure both MACOS_INSTALLER_CERTIFICATE_BASE64 and MACOS_INSTALLER_CERTIFICATE_PASSWORD"
+          exit 1
+        fi
+        if [ "$installer_certificate_set" = "true" ]; then
+          if [ "${#application_missing[@]}" -eq 0 ]; then
+            echo "pkg_enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "::notice::macOS PKG creation disabled because application signing/notarization is disabled"
+            echo "pkg_enabled=false" >> "$GITHUB_OUTPUT"
+          fi
+        else
+          if [[ "$ACE_RECOVERY_REF" == refs/tags/v* ]]; then
+            echo "::error::Tagged macOS releases require MACOS_INSTALLER_CERTIFICATE_BASE64 and MACOS_INSTALLER_CERTIFICATE_PASSWORD to build both PKGs"
+            exit 1
+          fi
+          echo "::notice::macOS PKG creation disabled; Developer ID Installer credentials are not configured"
+          echo "pkg_enabled=false" >> "$GITHUB_OUTPUT"
+        fi
+    - name: Configure MSVC
+      if: runner.os == 'Windows'
+      uses: ilammy/msvc-dev-cmd@v1
+      with:
+        arch: ${{ matrix.msvc_arch }}
+    - name: Install Linux ARMv7 cross toolchain
+      if: matrix.id == 'linux-armv7'
+      shell: bash
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y \
+          binutils-arm-linux-gnueabihf \
+          gcc-arm-linux-gnueabihf \
+          g++-arm-linux-gnueabihf \
+          qemu-user
+    - name: Run vcpkg
+      uses: lukka/run-vcpkg@v11
+    - name: Restore vcpkg binary cache
+      uses: actions/cache@v4
+      with:
+        path: ${{ env.VCPKG_DEFAULT_BINARY_CACHE }}
+        key: vcpkg-v2-${{ matrix.os }}-${{ matrix.triplet }}-${{ hashFiles('vcpkg.json', 'vcpkg-configuration.json', 'ports/**')
+          }}
+        restore-keys: |
+          vcpkg-v2-${{ matrix.os }}-${{ matrix.triplet }}-
+    - name: Install Linux desktop dependencies
+      if: runner.os == 'Linux' && matrix.build_desktop
+      shell: bash
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y libwebkit2gtk-4.1-dev
+    - name: Download web UI
+      uses: actions/download-artifact@v4
+      with:
+        name: web-dist
+        path: web/dist
+    - name: Configure
+      shell: bash
+      run: |
+        cmake -S . -B build -G Ninja \
+          -DCMAKE_BUILD_TYPE=MinSizeRel \
+          -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" \
+          -DVCPKG_TARGET_TRIPLET="${{ matrix.triplet }}" \
+          -DBUILD_TESTING=OFF \
+          ${{ matrix.cmake_extra_args }}
+    - name: Build
+      shell: bash
+      run: cmake --build build --config MinSizeRel --target acecode
+    - name: Build desktop
+      if: matrix.build_desktop
+      shell: bash
+      run: cmake --build build --config MinSizeRel --target acecode-desktop
+    - name: Verify Linux ARMv7 executable
+      if: matrix.id == 'linux-armv7'
+      shell: bash
+      run: |
+        export LC_ALL=C
+        elf_header="$(arm-linux-gnueabihf-readelf -h build/acecode)"
+        arm_attributes="$(arm-linux-gnueabihf-readelf -A build/acecode)"
+        program_headers="$(arm-linux-gnueabihf-readelf -l build/acecode)"
+
+        printf '%s\n' "$elf_header"
+        printf '%s\n' "$arm_attributes"
+
+        grep -Eq 'Class:[[:space:]]+ELF32' <<<"$elf_header"
+        grep -Eq 'Machine:[[:space:]]+ARM' <<<"$elf_header"
+        grep -Eq 'Tag_CPU_arch:[[:space:]]+v7' <<<"$arm_attributes"
+        grep -Eq 'Tag_ABI_VFP_args:[[:space:]]+VFP registers' <<<"$arm_attributes"
+        grep -Fq '/lib/ld-linux-armhf.so.3' <<<"$program_headers"
+
+        version_output="$(qemu-arm -L /usr/arm-linux-gnueabihf build/acecode --version)"
+        printf '%s\n' "$version_output"
+        grep -Eq '^acecode v[^[:space:]]+$' <<<"$version_output"
+    - name: Verify bundled resources in macOS app
+      if: runner.os == 'macOS' && matrix.build_desktop
+      shell: bash
+      run: |
+        registry_dir="build/ACECode.app/Contents/Resources/share/acecode/models_dev"
+        file_count="$(find "$registry_dir" -type f | wc -l | tr -d '[:space:]')"
+        if [ "$file_count" != "3" ]; then
+          echo "Expected exactly 3 models.dev resources in $registry_dir, found $file_count" >&2
+          exit 1
+        fi
+        for file in api.json MANIFEST.json LICENSE; do
+          if [ ! -f "$registry_dir/$file" ] ||
+             ! cmp -s "assets/models_dev/$file" "$registry_dir/$file"; then
+            echo "Missing or mismatched macOS app models.dev resource: $file" >&2
+            exit 1
+          fi
+        done
+        python3 scripts/verify_seed_bundle.py \
+          --source assets/seed \
+          --packaged build/ACECode.app/Contents/Resources/share/acecode/seed
+    - name: Extract debug symbols (Linux)
+      if: runner.os == 'Linux'
+      shell: bash
+      run: |
+        binutils_prefix=""
+        if [ "${{ matrix.id }}" = "linux-armv7" ]; then
+          binutils_prefix="arm-linux-gnueabihf-"
+        fi
+        "${binutils_prefix}objcopy" --only-keep-debug \
+          "build/${{ matrix.executable }}" \
+          "build/${{ matrix.executable }}.debug"
+        "${binutils_prefix}strip" --strip-unneeded "build/${{ matrix.executable }}"
+        "${binutils_prefix}objcopy" \
+          --add-gnu-debuglink="build/${{ matrix.executable }}.debug" \
+          "build/${{ matrix.executable }}"
+    - name: Extract desktop debug symbols (Linux)
+      if: runner.os == 'Linux' && matrix.build_desktop
+      shell: bash
+      run: |
+        objcopy --only-keep-debug "build/acecode-desktop" "build/acecode-desktop.debug"
+        strip --strip-unneeded "build/acecode-desktop"
+        objcopy --add-gnu-debuglink="build/acecode-desktop.debug" "build/acecode-desktop"
+    - name: Extract debug symbols (macOS)
+      if: runner.os == 'macOS'
+      shell: bash
+      run: |
+        dsymutil "build/${{ matrix.executable }}" -o "build/${{ matrix.executable }}.dSYM"
+        strip "build/${{ matrix.executable }}"
+    - name: Extract desktop debug symbols (macOS)
+      if: runner.os == 'macOS' && matrix.build_desktop
+      shell: bash
+      run: |
+        app_exec="build/ACECode.app/Contents/MacOS/ACECode"
+        app_daemon="build/ACECode.app/Contents/MacOS/acecode-daemon"
+        if [ ! -f "$app_exec" ]; then
+          echo "Missing desktop app executable: $app_exec" >&2
+          exit 1
+        fi
+        if [ ! -f "$app_daemon" ]; then
+          echo "Missing desktop app daemon: $app_daemon" >&2
+          exit 1
+        fi
+        dsymutil "$app_exec" -o "build/ACECode.app.dSYM"
+        strip "$app_exec"
+        dsymutil "$app_daemon" -o "build/acecode-daemon.dSYM"
+        strip "$app_daemon"
+    - name: Import Developer ID identities (macOS)
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      id: macos-keychain
+      shell: bash
+      env:
+        MACOS_CERTIFICATE_BASE64: ${{ secrets.MACOS_CERTIFICATE_BASE64 }}
+        MACOS_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
+        MACOS_INSTALLER_CERTIFICATE_BASE64: ${{ secrets.MACOS_INSTALLER_CERTIFICATE_BASE64 }}
+        MACOS_INSTALLER_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_INSTALLER_CERTIFICATE_PASSWORD }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        MACOS_CODESIGN_IDENTITY: ${{ vars.MACOS_CODESIGN_IDENTITY }}
+        MACOS_INSTALLER_SIGNING_IDENTITY: ${{ vars.MACOS_INSTALLER_SIGNING_IDENTITY }}
+      run: |
+        set +x
+        certificate_path="$RUNNER_TEMP/acecode-developer-id.p12"
+        installer_certificate_path="$RUNNER_TEMP/acecode-developer-id-installer.p12"
+        keychain_path="$RUNNER_TEMP/acecode-signing.keychain-db"
+        keychain_password="$(openssl rand -hex 32)"
+
+        printf '%s' "$MACOS_CERTIFICATE_BASE64" | /usr/bin/base64 -D > "$certificate_path"
+        chmod 600 "$certificate_path"
+        if [ "${{ steps.macos-release.outputs.pkg_enabled }}" = "true" ]; then
+          printf '%s' "$MACOS_INSTALLER_CERTIFICATE_BASE64" | /usr/bin/base64 -D > "$installer_certificate_path"
+          chmod 600 "$installer_certificate_path"
+        fi
+        security create-keychain -p "$keychain_password" "$keychain_path"
+        security set-keychain-settings -lut 21600 "$keychain_path"
+        security unlock-keychain -p "$keychain_password" "$keychain_path"
+
+        existing_user_keychains=()
+        while IFS= read -r existing_keychain; do
+          if [ -n "$existing_keychain" ]; then
+            existing_user_keychains+=("$existing_keychain")
+          fi
+        done < <(
+          security list-keychains -d user |
+            sed -E 's/^[[:space:]]*"//; s/"[[:space:]]*$//'
+        )
+        security list-keychains -d user -s \
+          "$keychain_path" \
+          "${existing_user_keychains[@]}"
+
+        security import "$certificate_path" \
+          -k "$keychain_path" \
+          -P "$MACOS_CERTIFICATE_PASSWORD" \
+          -f pkcs12 \
+          -T /usr/bin/codesign \
+          -T /usr/bin/security
+        if [ "${{ steps.macos-release.outputs.pkg_enabled }}" = "true" ]; then
+          security import "$installer_certificate_path" \
+            -k "$keychain_path" \
+            -P "$MACOS_INSTALLER_CERTIFICATE_PASSWORD" \
+            -f pkcs12 \
+            -T /usr/bin/pkgbuild \
+            -T /usr/bin/productbuild \
+            -T /usr/bin/security
+        fi
+        security set-key-partition-list \
+          -S apple-tool:,apple: \
+          -s \
+          -k "$keychain_password" \
+          "$keychain_path"
+
+        identity_record="$(security find-identity -v -p codesigning "$keychain_path" |
+          awk '/Developer ID Application:/ { print; exit }')"
+        identity_fingerprint="$(printf '%s\n' "$identity_record" | awk '{ print $2 }')"
+        identity_name="$(printf '%s\n' "$identity_record" | awk -F '"' '{ print $2 }')"
+        if [[ ! "$identity_fingerprint" =~ ^[[:xdigit:]]{40}$ ]] || [ -z "$identity_name" ]; then
+          echo "::error::No Developer ID Application identity found in the imported certificate"
+          exit 1
+        fi
+        if [ -n "$MACOS_CODESIGN_IDENTITY" ] && [ "$identity_name" != "$MACOS_CODESIGN_IDENTITY" ]; then
+          echo "::error::Imported signing identity does not match MACOS_CODESIGN_IDENTITY"
+          exit 1
+        fi
+        if [ -n "$APPLE_TEAM_ID" ] && [[ "$identity_name" != *"($APPLE_TEAM_ID)" ]]; then
+          echo "::error::Developer ID Application identity does not match APPLE_TEAM_ID"
+          exit 1
+        fi
+
+        if [ "${{ steps.macos-release.outputs.pkg_enabled }}" = "true" ]; then
+          installer_identity_record="$(security find-identity -v -p basic "$keychain_path" |
+            awk '/Developer ID Installer:/ { print; exit }')"
+          installer_identity_fingerprint="$(printf '%s\n' "$installer_identity_record" | awk '{ print $2 }')"
+          installer_identity_name="$(printf '%s\n' "$installer_identity_record" | awk -F '"' '{ print $2 }')"
+          if [[ ! "$installer_identity_fingerprint" =~ ^[[:xdigit:]]{40}$ ]] || [ -z "$installer_identity_name" ]; then
+            echo "::error::No Developer ID Installer identity found in the imported certificate"
+            exit 1
+          fi
+          if [ -n "$MACOS_INSTALLER_SIGNING_IDENTITY" ] && [ "$installer_identity_name" != "$MACOS_INSTALLER_SIGNING_IDENTITY" ]; then
+            echo "::error::Imported Installer identity does not match MACOS_INSTALLER_SIGNING_IDENTITY"
+            exit 1
+          fi
+          if [ -n "$APPLE_TEAM_ID" ] && [[ "$installer_identity_name" != *"($APPLE_TEAM_ID)" ]]; then
+            echo "::error::Developer ID Installer identity does not match APPLE_TEAM_ID"
+            exit 1
+          fi
+          echo "installer_identity=$installer_identity_name" >> "$GITHUB_OUTPUT"
+        fi
+
+        echo "keychain=$keychain_path" >> "$GITHUB_OUTPUT"
+        # Sign by the certificate fingerprint. codesign can fail to resolve a
+        # human-readable identity name inside an isolated temporary keychain.
+        echo "identity=$identity_fingerprint" >> "$GITHUB_OUTPUT"
+    - name: Sign macOS release payloads
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      shell: bash
+      run: |
+        xcrun() {
+          if [[ "${1:-}" != "stapler" ]]; then
+            command xcrun "$@"
+            return $?
+          fi
+          local result=0
+          for attempt in 1 2 3 4 5 6; do
+            if command xcrun "$@"; then return 0; else result=$?; fi
+            if [[ "$result" != "68" || "$attempt" == "6" ]]; then return "$result"; fi
+            echo "Apple ticket service disconnected (68), retry $attempt/6 in 15 seconds"
+            sleep 15
+          done
+          return "$result"
+        }
+        export -f xcrun
+        scripts/macos_codesign.sh \
+          --identity "${{ steps.macos-keychain.outputs.identity }}" \
+          --keychain "${{ steps.macos-keychain.outputs.keychain }}" \
+          --binary "build/${{ matrix.executable }}" \
+          --binary "build/acecode-computer-use" \
+          --app "build/ACECode.app"
+    - name: Notarize and staple macOS app
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      shell: bash
+      env:
+        APPLE_ID: ${{ secrets.APPLE_ID }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      run: |-
+        xcrun() {
+          if [[ "${1:-}" != "stapler" ]]; then
+            command xcrun "$@"
+            return $?
+          fi
+          local result=0
+          for attempt in 1 2 3 4 5 6; do
+            if command xcrun "$@"; then return 0; else result=$?; fi
+            if [[ "$result" != "68" || "$attempt" == "6" ]]; then return "$result"; fi
+            echo "Apple ticket service disconnected (68), retry $attempt/6 in 15 seconds"
+            sleep 15
+          done
+          return "$result"
+        }
+        export -f xcrun
+        scripts/macos_notarize_app.sh --app "build/ACECode.app"
+    - name: Test macOS installer integration
+      if: runner.os == 'macOS'
+      shell: bash
+      run: |
+        bash tests/scripts/macos_installer_test.sh
+        python3 tests/scripts/macos_installer_release_test.py
+    - name: Create current-user macOS PKG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.pkg_enabled == 'true'
+      id: macos-pkg
+      shell: bash
+      run: |
+        xcrun() {
+          if [[ "${1:-}" != "stapler" ]]; then
+            command xcrun "$@"
+            return $?
+          fi
+          local result=0
+          for attempt in 1 2 3 4 5 6; do
+            if command xcrun "$@"; then return 0; else result=$?; fi
+            if [[ "$result" != "68" || "$attempt" == "6" ]]; then return "$result"; fi
+            echo "Apple ticket service disconnected (68), retry $attempt/6 in 15 seconds"
+            sleep 15
+          done
+          return "$result"
+        }
+        export -f xcrun
+        pkg_path="ACECode-${{ steps.package-version.outputs.version }}-${{ matrix.id }}.pkg"
+        scripts/macos_create_pkg.sh \
+          --app "build/ACECode.app" \
+          --output "$pkg_path" \
+          --installer-identity "${{ steps.macos-keychain.outputs.installer_identity }}" \
+          --keychain "${{ steps.macos-keychain.outputs.keychain }}"
+        echo "path=$pkg_path" >> "$GITHUB_OUTPUT"
+    - name: Notarize and validate macOS PKG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.pkg_enabled == 'true'
+      shell: bash
+      env:
+        APPLE_ID: ${{ secrets.APPLE_ID }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      run: |-
+        xcrun() {
+          if [[ "${1:-}" != "stapler" ]]; then
+            command xcrun "$@"
+            return $?
+          fi
+          local result=0
+          for attempt in 1 2 3 4 5 6; do
+            if command xcrun "$@"; then return 0; else result=$?; fi
+            if [[ "$result" != "68" || "$attempt" == "6" ]]; then return "$result"; fi
+            echo "Apple ticket service disconnected (68), retry $attempt/6 in 15 seconds"
+            sleep 15
+          done
+          return "$result"
+        }
+        export -f xcrun
+        scripts/macos_notarize_pkg.sh --pkg "${{ steps.macos-pkg.outputs.path }}"
+    - name: Upload macOS PKG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.pkg_enabled == 'true'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-pkg
+        path: ${{ steps.macos-pkg.outputs.path }}
+        if-no-files-found: error
+    - name: Build signed and notarized macOS installer DMG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      id: macos-dmg
+      shell: bash
+      env:
+        APPLE_ID: ${{ secrets.APPLE_ID }}
+        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      run: |
+        xcrun() {
+          if [[ "${1:-}" != "stapler" ]]; then
+            command xcrun "$@"
+            return $?
+          fi
+          local result=0
+          for attempt in 1 2 3 4 5 6; do
+            if command xcrun "$@"; then return 0; else result=$?; fi
+            if [[ "$result" != "68" || "$attempt" == "6" ]]; then return "$result"; fi
+            echo "Apple ticket service disconnected (68), retry $attempt/6 in 15 seconds"
+            sleep 15
+          done
+          return "$result"
+        }
+        export -f xcrun
+        dmg_path="ACECode-${{ steps.package-version.outputs.version }}-${{ matrix.id }}.dmg"
+        bash scripts/macos_create_installer_dmg.sh \
+          --app "build/ACECode.app" \
+          --output "$dmg_path" \
+          --arch "${{ matrix.installer_arch }}" \
+          --identity "${{ steps.macos-keychain.outputs.identity }}" \
+          --keychain "${{ steps.macos-keychain.outputs.keychain }}"
+        echo "path=$dmg_path" >> "$GITHUB_OUTPUT"
+    - name: Create macOS self-update archive
+      if: runner.os == 'macOS'
+      id: macos-update
+      shell: bash
+      run: |
+        xcrun() {
+          if [[ "${1:-}" != "stapler" ]]; then
+            command xcrun "$@"
+            return $?
+          fi
+          local result=0
+          for attempt in 1 2 3 4 5 6; do
+            if command xcrun "$@"; then return 0; else result=$?; fi
+            if [[ "$result" != "68" || "$attempt" == "6" ]]; then return "$result"; fi
+            echo "Apple ticket service disconnected (68), retry $attempt/6 in 15 seconds"
+            sleep 15
+          done
+          return "$result"
+        }
+        export -f xcrun
+        unsigned_suffix=""
+        trust_args=()
+        if [ "${{ steps.macos-release.outputs.enabled }}" = "true" ]; then
+          trust_args+=(--require-trusted)
+        else
+          unsigned_suffix="-unsigned"
+        fi
+        update_path="ACECode-${{ steps.package-version.outputs.version }}-${{ matrix.id }}-update${unsigned_suffix}.zip"
+        scripts/macos_create_update_zip.sh \
+          --app "build/ACECode.app" \
+          --output "$update_path" \
+          "${trust_args[@]}"
+        echo "path=$update_path" >> "$GITHUB_OUTPUT"
+    - name: Package (Unix)
+      if: runner.os != 'Windows'
+      shell: bash
+      run: |
+        package_dir="dist/acecode-${{ matrix.id }}"
+        mkdir -p "$package_dir"
+
+        validate_models_dev_registry() {
+          registry_dir="$1"
+          file_count="$(find "$registry_dir" -type f | wc -l | tr -d '[:space:]')"
+          if [ "$file_count" != "3" ]; then
+            echo "Expected exactly 3 models.dev files in $registry_dir, found $file_count" >&2
+            exit 1
+          fi
+          for file in api.json MANIFEST.json LICENSE; do
+            if [ ! -f "$registry_dir/$file" ] ||
+               ! cmp -s "assets/models_dev/$file" "$registry_dir/$file"; then
+              echo "Missing or mismatched models.dev package file: $registry_dir/$file" >&2
+              exit 1
+            fi
+          done
+        }
+
+        if [ ! -f "build/${{ matrix.executable }}" ]; then
+          echo "Missing terminal executable: build/${{ matrix.executable }}" >&2
+          exit 1
+        fi
+        cp "build/${{ matrix.executable }}" "$package_dir/"
+        cp README.md README_CN.md "$package_dir/"
+        cmake --install build \
+          --config MinSizeRel \
+          --prefix "$PWD/$package_dir" \
+          --component models_dev_registry
+        cmake --install build \
+          --config MinSizeRel \
+          --prefix "$PWD/$package_dir" \
+          --component default_seed_bundle
+        cmake --install build --config MinSizeRel --prefix "$PWD/$package_dir" --component whatsapp_channel
+        if [ "$RUNNER_OS" = "macOS" ]; then
+          cmake --install build --config MinSizeRel --prefix "$PWD/$package_dir" --component computer_use_runtime
+          test -x "$package_dir/acecode-computer-use"
+          test -x "build/ACECode.app/Contents/MacOS/acecode-computer-use"
+        fi
+        validate_models_dev_registry "$package_dir/share/acecode/models_dev"
+        python3 scripts/verify_seed_bundle.py \
+          --source assets/seed \
+          --packaged "$package_dir/share/acecode/seed"
+
+        if [ "${{ matrix.build_desktop }}" = "true" ]; then
+          if [ "$RUNNER_OS" = "macOS" ]; then
+            if [ ! -d "build/ACECode.app" ]; then
+              echo "Missing desktop app bundle: build/ACECode.app" >&2
+              exit 1
+            fi
+            cp -r "build/ACECode.app" "$package_dir/"
+          else
+            if [ ! -f "build/acecode-desktop" ]; then
+              echo "Missing desktop executable: build/acecode-desktop" >&2
+              exit 1
+            fi
+            cp "build/acecode-desktop" "$package_dir/"
+            cp "build/acecode-logo.png" "$package_dir/"
+          fi
+        fi
+        legacy="$(find "$package_dir" -maxdepth 1 -iname 'ace-browser-*' -print -quit)"
+        if [ -n "$legacy" ]; then
+          echo "Legacy browser artifact must not be packaged: $legacy" >&2
+          exit 1
+        fi
+        tar -C dist -czf "acecode-${{ matrix.id }}.tar.gz" "acecode-${{ matrix.id }}"
+
+        verify_root="$(mktemp -d)"
+        tar -xzf "acecode-${{ matrix.id }}.tar.gz" -C "$verify_root"
+        extracted_package="$verify_root/acecode-${{ matrix.id }}"
+        validate_models_dev_registry "$extracted_package/share/acecode/models_dev"
+        python3 scripts/verify_seed_bundle.py \
+          --source assets/seed \
+          --packaged "$extracted_package/share/acecode/seed"
+        if [ "$RUNNER_OS" = "macOS" ]; then
+          test -x "$extracted_package/acecode-computer-use"
+          test -x "$extracted_package/ACECode.app/Contents/MacOS/acecode-computer-use"
+          validate_models_dev_registry \
+            "$extracted_package/ACECode.app/Contents/Resources/share/acecode/models_dev"
+          python3 scripts/verify_seed_bundle.py \
+            --source assets/seed \
+            --packaged "$extracted_package/ACECode.app/Contents/Resources/share/acecode/seed"
+        fi
+        rm -rf -- "$verify_root"
+    - name: Create Linux self-update archive
+      if: matrix.id == 'linux-x64' || matrix.id == 'linux-arm64'
+      id: linux-update
+      shell: bash
+      run: |
+        update_path="acecode-${{ steps.package-version.outputs.version }}-${{ matrix.id }}-update.zip"
+        bash scripts/linux_create_update_zip.sh \
+          --package-dir "dist/acecode-${{ matrix.id }}" \
+          --output "$update_path" \
+          --expected-version "${{ steps.package-version.outputs.version }}"
+        echo "path=$update_path" >> "$GITHUB_OUTPUT"
+    - name: Clean up macOS signing material
+      if: always() && runner.os == 'macOS'
+      shell: bash
+      run: |
+        set +e
+        security delete-keychain "$RUNNER_TEMP/acecode-signing.keychain-db" 2>/dev/null
+        rm -f -- \
+          "$RUNNER_TEMP/acecode-developer-id.p12" \
+          "$RUNNER_TEMP/acecode-developer-id-installer.p12"
+    - name: Package (Windows)
+      if: runner.os == 'Windows'
+      shell: pwsh
+      run: |
+        $packageDir = "dist/acecode-${{ matrix.id }}"
+        New-Item -ItemType Directory -Force -Path $packageDir | Out-Null
+
+        function Assert-ModelsDevRegistry([string] $RegistryDir) {
+          if (-not (Test-Path -LiteralPath $RegistryDir -PathType Container)) {
+            throw "Missing models.dev directory: $RegistryDir"
+          }
+          $actualFiles = @(Get-ChildItem -LiteralPath $RegistryDir -File -Recurse)
+          if ($actualFiles.Count -ne 3) {
+            throw "Expected exactly 3 models.dev files in ${RegistryDir}, found $($actualFiles.Count)"
+          }
+          foreach ($name in @("api.json", "MANIFEST.json", "LICENSE")) {
+            $source = Join-Path "assets/models_dev" $name
+            $packaged = Join-Path $RegistryDir $name
+            if (-not (Test-Path -LiteralPath $packaged -PathType Leaf)) {
+              throw "Missing models.dev package file: $packaged"
+            }
+            $sourceHash = (Get-FileHash -LiteralPath $source -Algorithm SHA256).Hash
+            $packagedHash = (Get-FileHash -LiteralPath $packaged -Algorithm SHA256).Hash
+            if ($sourceHash -ne $packagedHash) {
+              throw "Mismatched models.dev package file: $packaged"
+            }
+          }
+        }
+
+        $terminalExe = "build/${{ matrix.executable }}"
+        if (-not (Test-Path -LiteralPath $terminalExe)) {
+          throw "Missing terminal executable: $terminalExe"
+        }
+        Copy-Item -LiteralPath $terminalExe -Destination "$packageDir/"
+        Copy-Item "README.md","README_CN.md" "$packageDir/"
+        $packageRoot = (Resolve-Path -LiteralPath $packageDir).Path
+        & cmake --install build --config MinSizeRel --prefix $packageRoot --component models_dev_registry
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to install the bundled models.dev registry"
+        }
+        & cmake --install build --config MinSizeRel --prefix $packageRoot --component default_seed_bundle
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to install the default seed bundle"
+        }
+        & cmake --install build --config MinSizeRel --prefix $packageRoot --component whatsapp_channel
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to install the WhatsApp channel bridge"
+        }
+        & cmake --install build --config MinSizeRel --prefix $packageRoot --component computer_use_runtime
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to install the Computer Use runtime"
+        }
+        $computerUseExe = Join-Path $packageRoot "acecode-computer-use.exe"
+        if (-not (Test-Path -LiteralPath $computerUseExe -PathType Leaf) -or
+            (Get-Item -LiteralPath $computerUseExe).Length -eq 0) {
+          throw "Missing Computer Use runtime: $computerUseExe"
+        }
+        Assert-ModelsDevRegistry (Join-Path $packageDir "share/acecode/models_dev")
+        & python scripts/verify_seed_bundle.py `
+          --source assets/seed `
+          --packaged (Join-Path $packageDir "share/acecode/seed")
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to verify the packaged default seed bundle"
+        }
+
+        if ("${{ matrix.build_desktop }}" -eq "true") {
+          $desktopCandidates = @(
+            "build/acecode-desktop.exe",
+            "build/Release/acecode-desktop.exe",
+            "build/Debug/acecode-desktop.exe",
+            "build/RelWithDebInfo/acecode-desktop.exe",
+            "build/MinSizeRel/acecode-desktop.exe"
+          )
+          $desktopExe = $desktopCandidates | Where-Object { Test-Path -LiteralPath $_ } | Select-Object -First 1
+          if (-not $desktopExe) {
+            $desktopExe = Get-ChildItem -Path "build" -Recurse -Filter "acecode-desktop.exe" -File |
+              Select-Object -ExpandProperty FullName -First 1
+          }
+          if (-not $desktopExe) {
+            throw "Missing desktop executable: acecode-desktop.exe"
+          }
+          Copy-Item -LiteralPath $desktopExe -Destination "$packageDir/"
+        }
+        $legacyBrowserArtifact = Get-ChildItem -LiteralPath $packageDir -Filter "ace-browser-*" -Force |
+          Select-Object -First 1
+        if ($legacyBrowserArtifact) {
+          throw "Legacy browser artifact must not be packaged: $($legacyBrowserArtifact.FullName)"
+        }
+        Compress-Archive -Path "$packageDir/*" -DestinationPath "acecode-${{ matrix.id }}.zip" -Force
+
+        $verifyRoot = Join-Path $env:RUNNER_TEMP ("acecode-package-verify-" + [Guid]::NewGuid().ToString("N"))
+        New-Item -ItemType Directory -Path $verifyRoot | Out-Null
+        Expand-Archive -LiteralPath "acecode-${{ matrix.id }}.zip" -DestinationPath $verifyRoot
+        $archivedComputerUseExe = Join-Path $verifyRoot "acecode-computer-use.exe"
+        if (-not (Test-Path -LiteralPath $archivedComputerUseExe -PathType Leaf) -or
+            (Get-FileHash -LiteralPath $archivedComputerUseExe -Algorithm SHA256).Hash -ne
+              (Get-FileHash -LiteralPath $computerUseExe -Algorithm SHA256).Hash) {
+          throw "Archived Computer Use runtime is missing or does not match the build"
+        }
+        Assert-ModelsDevRegistry (Join-Path $verifyRoot "share/acecode/models_dev")
+        & python scripts/verify_seed_bundle.py `
+          --source assets/seed `
+          --packaged (Join-Path $verifyRoot "share/acecode/seed")
+        if ($LASTEXITCODE -ne 0) {
+          throw "Failed to verify the archived default seed bundle"
+        }
+    - name: Verify Windows ARM64 package
+      if: matrix.id == 'windows-arm64'
+      shell: pwsh
+      run: |
+        $packageDir = "dist/acecode-${{ matrix.id }}"
+        $expectedExecutables = @(
+          "acecode.exe",
+          "acecode-desktop.exe",
+          "acecode-computer-use.exe"
+        )
+        foreach ($name in $expectedExecutables) {
+          $path = Join-Path $packageDir $name
+          if (-not (Test-Path -LiteralPath $path)) {
+            throw "Missing ARM64 package executable: $path"
+          }
+          $headers = (& dumpbin /headers $path | Out-String)
+          if ($LASTEXITCODE -ne 0 -or $headers -notmatch '(?im)\bAA64 machine\b') {
+            throw "$name is not an ARM64 PE executable"
+          }
+          Write-Host "${name}: ARM64"
+        }
+    - name: Upload artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}
+        path: acecode-${{ matrix.id }}.${{ matrix.archive_extension }}
+        if-no-files-found: error
+    - name: Upload Linux self-update archive
+      if: matrix.id == 'linux-x64' || matrix.id == 'linux-arm64'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-update
+        path: ${{ steps.linux-update.outputs.path }}
+        if-no-files-found: error
+    - name: Upload macOS installer DMG
+      if: runner.os == 'macOS' && steps.macos-release.outputs.enabled == 'true'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-dmg
+        path: ${{ steps.macos-dmg.outputs.path }}
+        if-no-files-found: error
+    - name: Upload macOS self-update archive
+      if: runner.os == 'macOS'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-update
+        path: ${{ steps.macos-update.outputs.path }}
+        if-no-files-found: error
+    - name: Upload PDB
+      if: runner.os == 'Windows'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-pdb
+        path: build/**/acecode.pdb
+        if-no-files-found: warn
+    - name: Upload desktop PDB
+      if: runner.os == 'Windows' && matrix.build_desktop
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-desktop-pdb
+        path: build/**/acecode-desktop.pdb
+        if-no-files-found: warn
+    - name: Upload debug symbols (Linux)
+      if: runner.os == 'Linux'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-debug
+        path: build/${{ matrix.executable }}.debug
+        if-no-files-found: warn
+    - name: Upload desktop debug symbols (Linux)
+      if: runner.os == 'Linux' && matrix.build_desktop
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-desktop-debug
+        path: build/acecode-desktop.debug
+        if-no-files-found: warn
+    - name: Upload dSYM (macOS)
+      if: runner.os == 'macOS'
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-dsym
+        path: build/${{ matrix.executable }}.dSYM
+        if-no-files-found: warn
+    - name: Upload desktop dSYM (macOS)
+      if: runner.os == 'macOS' && matrix.build_desktop
+      uses: actions/upload-artifact@v4
+      with:
+        name: acecode-${{ matrix.id }}-desktop-dsym
+        path: |
+          build/ACECode.app.dSYM
+          build/acecode-daemon.dSYM
+        if-no-files-found: warn
+    timeout-minutes: 60
diff --git a/assets/desktop_pet/agent_office_pet.html b/assets/desktop_pet/agent_office_pet.html
index 5e735c00a..b3c797e61 100644
--- a/assets/desktop_pet/agent_office_pet.html
+++ b/assets/desktop_pet/agent_office_pet.html
@@ -18,7 +18,8 @@
 .ov{position:absolute;inset:0;pointer-events:none;line-height:1.4}
 .scene canvas.up{position:absolute;inset:0;image-rendering:auto;pointer-events:none}
 .grip{position:absolute;left:calc(11 / 344 * 100%);top:calc(112 / 252 * 100%);width:16px;height:16px;cursor:nwse-resize;opacity:0;transition:opacity .15s;z-index:3}
-.scene:hover .grip{opacity:.95}
+/* The resize handle stays hidden (but hit-testable) until the pointer is on it. */
+.grip:hover{opacity:.95}
 .grip svg{display:block;width:100%;height:100%}
 .zoom-badge{position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);background:#27324f;color:#fff;font-weight:700;border-radius:6px;padding:2px 9px;font-size:13px;pointer-events:none;z-index:4}
 .bub{position:absolute;left:0;top:0;z-index:2;display:flex;align-items:center;gap:3px;max-width:min(64vw,calc(var(--k) * 150px));background:#fff;color:#1b2540;border:2px solid #27324f;border-radius:6px;padding:1px 6px 2px;font-size:max(10px,calc(var(--k) * 6.2px));font-weight:700;white-space:nowrap;box-shadow:2px 2px 0 rgba(20,24,40,.28)}
diff --git a/assets/desktop_pet/classic/README.md b/assets/desktop_pet/classic/README.md
index e0ad9a051..4ea450718 100644
--- a/assets/desktop_pet/classic/README.md
+++ b/assets/desktop_pet/classic/README.md
@@ -2,4 +2,8 @@
 
 Clippy（43 个动作）与 Rover（29 个动作）原始 PNG 精灵图和动作数据来自 [clippyjs/clippy.js](https://github.com/clippyjs/clippy.js)，固定提交和 SHA-256 见 `sources.json`。`preview.png` 直接裁取原图的 RestPose 首帧，仅用于设置中的预览。
 
+## 趴边偷看（clippy/peek.png、rover/peek.png）
+
+宠物拖到屏幕左/右边缘吸附后改用各自目录下的 `peek.png`：两帧并排（左睁眼、右闭眼），透明背景，画面右缘就是它躲着的那条屏幕边（贴左边时页面水平镜像）。不来自上游项目，2026-10-16 用 Codex 的内置图像生成（codex-cli 0.162）绘制，以本目录精灵图的整张图与 RestPose / Idle 首帧作为风格参考，要求同一角色设计与画风：回形针把上半截钢丝和两只大眼睛从画面右缘探进来，rover 探出脑袋、两只前爪扒着右缘。闭眼帧由同一张图做「只闭眼、其余不变」的编辑，再只把眼睛区域贴回睁眼图，眨眼时其余像素不动。处理：纯绿背景抠成透明并去绿边，两帧同裁，按眼睛大小与原帧一致缩到精灵分辨率（回形针 29×75、rover 41×56 每帧），alpha 只留全透明 / 不透明，颜色映射到对应 `map.png` 实际用到、且不偏绿的调色板颜色，所以和原帧一样是不平滑放大的像素画。换图时要按眼睛重新量缩放，页面里的倍数见 `classic_pet.js` 的 `PEEK` 表。
+
 角色由 Microsoft 创作；上游代码许可保存在 `MIT-LICENSE.txt`。ACECode 自有播放器不依赖上游 jQuery 播放器，不播放原始音效。素材随本地程序打包，运行时没有 CDN 请求。
diff --git a/assets/desktop_pet/classic/clippy/peek.png b/assets/desktop_pet/classic/clippy/peek.png
new file mode 100644
index 000000000..9a0c54922
Binary files /dev/null and b/assets/desktop_pet/classic/clippy/peek.png differ
diff --git a/assets/desktop_pet/classic/rover/peek.png b/assets/desktop_pet/classic/rover/peek.png
new file mode 100644
index 000000000..9a382c6ec
Binary files /dev/null and b/assets/desktop_pet/classic/rover/peek.png differ
diff --git a/assets/desktop_pet/classic_pet.html b/assets/desktop_pet/classic_pet.html
index c28d2d78e..b205f13c3 100644
--- a/assets/desktop_pet/classic_pet.html
+++ b/assets/desktop_pet/classic_pet.html
@@ -21,7 +21,11 @@
    box, and Windows clips painting to it, so a shadow running past it is cut off hard. */
 /* Card text is the ACECode transcript body text: same family, size and line height (the main
    window sends its live values with every snapshot, following its font-size setting). */
-.stack{position:absolute;left:0;right:0;bottom:calc(58% - 10px);z-index:3;padding:12px max(4%,16px) 26px;font:var(--pet-font-size)/1.6 var(--pet-font)}
+/* In a small window the cards would run past the top edge: --stack-fit (set by fitStack) shrinks
+   them, down to 9px text, and .pinned holds them at the top edge when even that is too tall. */
+.stack{position:absolute;left:0;right:0;bottom:calc(58% - 10px);z-index:3;padding:calc(12px * var(--stack-fit, 1)) max(4%,16px) calc(26px * var(--stack-fit, 1));
+  font:calc(var(--pet-font-size) * var(--stack-fit, 1))/1.6 var(--pet-font)}
+.stack.collapsed.pinned{bottom:auto;top:0}
 .stack.expanded{bottom:auto;top:0;max-height:100%;overflow-y:auto;scrollbar-width:thin}
 .deck{position:relative;isolation:isolate;display:flex;flex-direction:column;gap:6px}
 .stack.collapsed .card:not(:first-child){display:none}
@@ -34,7 +38,8 @@
 .text{flex:1;min-width:0}
 .head{display:flex;align-items:center;gap:.4em;font-weight:700}
 .name{min-width:0;overflow:hidden;white-space:nowrap;text-overflow:ellipsis}
-.body{margin-top:.1em;color:var(--card-muted);overflow:hidden;white-space:nowrap;text-overflow:ellipsis}
+/* A block box: on an inline span the ellipsis does nothing and long text runs under the stop button. */
+.body{display:block;margin-top:.1em;color:var(--card-muted);overflow:hidden;white-space:nowrap;text-overflow:ellipsis}
 .icon{flex:none;width:1.1em;height:1.1em;display:grid;place-items:center}
 .icon svg{width:100%;height:100%}
 .spinner{width:.9em;height:.9em;border:2px solid var(--card-button);border-top-color:var(--idle);border-radius:50%;animation:spin .9s linear infinite}
@@ -46,8 +51,10 @@
   box-shadow:0 1px 3px rgba(0,0,0,.25);display:none;place-items:center;cursor:pointer;padding:0;font:inherit;font-weight:700;line-height:1}
 .card:hover .dismiss,.card:focus-within .dismiss{display:grid}
 .stack.collapsed.layers .card .dismiss{display:none}
-.grip{position:absolute;left:calc(11 / 344 * 100%);top:calc(112 / 252 * 100%);width:16px;height:16px;cursor:nwse-resize;opacity:0;z-index:2}
-.scene:hover .grip,.scene:focus-within .grip{opacity:1}
+/* The resize handle sits at the top-left of the visible pet (placed by reportRegions) and stays
+   hidden, though still hit-testable, until the pointer is on it. */
+.grip{position:absolute;width:16px;height:16px;cursor:nwse-resize;opacity:0;transition:opacity .15s;z-index:2}
+.grip:hover{opacity:1}
 .grip svg{width:100%;height:100%;fill:none;stroke:var(--pet-ink);stroke-width:2}
 .badge{position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);background:var(--pet-ink);color:#fff;padding:3px 8px;border-radius:5px;pointer-events:none}
 [hidden]{display:none!important}
@@ -57,7 +64,7 @@
 <div class="scene" id="scene">
   <div class="stack collapsed" id="stack" role="list" aria-label="会话动态" hidden><div class="deck" id="deck"></div></div>
   <canvas id="cv" width="344" height="252" aria-label="桌面宠物，双击打开 ACECode"></canvas>
-  <div class="grip" id="grip" title="拖动调整大小，双击恢复默认大小"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M2 7L7 2M2 11L11 2M2 15L15 2"/></svg></div>
+  <div class="grip" id="grip" title="拖动调整大小，双击恢复默认大小" hidden><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M2 7L7 2M2 11L11 2M2 15L15 2"/></svg></div>
   <div class="badge" id="badge" hidden></div>
 </div>
 <script>window.ClassicPetAgents={};window.clippy={ready:(name,data)=>{window.ClassicPetAgents[name.toLowerCase()]=data;}};</script>
diff --git a/assets/desktop_pet/classic_pet.js b/assets/desktop_pet/classic_pet.js
index 1bc058e3b..fbeb6f8a5 100644
--- a/assets/desktop_pet/classic_pet.js
+++ b/assets/desktop_pet/classic_pet.js
@@ -52,14 +52,21 @@
       sleep: 'sleep', wake: 'wake',
     },
   };
+  // Docked pets peek in from the screen edge. `hidden` canvas px of the art stays past the edge so
+  // they can lean in without revealing where the drawing is cut. `ratio` is how much larger the peek
+  // art is drawn than the sprite frames: it is shown at the frame scale divided by it, so the head
+  // keeps the size it has in every other pose instead of growing at the edge. Whale Girl's art is
+  // about 1.8x (eye height and headband-to-mouth both measure 1.8x); Clippy's and Rover's are made
+  // at sprite resolution (their eyes match the frames' eyes) and, like their frames, are scaled
+  // without smoothing. Their art is narrow, so less of it hides past the edge.
+  const PEEK = {
+    whale: { ratio: 1.8, hidden: 9, smooth: true },
+    clippy: { ratio: 1, hidden: 4, smooth: false },
+    rover: { ratio: 1, hidden: 4, smooth: false },
+  };
+  const peekStyle = () => PEEK[kind] || PEEK.whale;
   // Extra hit margin (canvas px) so moving silhouettes stay clickable without per-frame region updates.
-  // Docked Whale Girl peeks in from the screen edge; PEEK_HIDDEN of the art stays past the edge
-  // so she can lean in without revealing where the drawing is cut.
-  // The peek art is drawn about 1.8 times larger than the sprite frames (eye height and headband-to-
-  // mouth both measure 1.8x), so it is shown at the frame scale divided by that ratio: her head
-  // keeps the size it has in every other pose instead of nearly doubling at the edge.
-  const PEEK_ART_RATIO = 1.8, PEEK_HIDDEN = 9;
-  const MOTION_MARGIN = { float: [0, 4], breathe: [0, 3], shake: [3, 0], wiggle: [8, 0], tilt: [16, 2], peek: [PEEK_HIDDEN + 4, 8] };
+  const MOTION_MARGIN = { float: [0, 4], breathe: [0, 3], shake: [3, 0], wiggle: [8, 0], tilt: [16, 2] };
   const timing = { fidgetMin: 7000, fidgetMax: 16000, sleepAfter: 5 * 60 * 1000, greeting: 6000 };
   // The original agents hold a pose through self-looping branches (Clippy's idle stares ~6s).
   // Once one picture has been shown this long, branches are skipped so the clip moves on.
@@ -68,8 +75,10 @@
   let snapshot = { version: 1, follow: true, connected: false, agents: [], offices: [], selected: null, activities: [] };
   let kind = '', data = null, sheet = null, profile = null, loadRevision = 0, pendingIntro = null;
   let animation = '', frameIndex = 0, flipped = false, motionKind = '', images = null, imageKey = '', imageSince = 0;
-  // Edge docking (Whale Girl only): the peek sheet, which edge, eyes open/closed, lean and bounce.
-  let peek = null, docked = '', peekEyes = 0, peekLean = 0, peekBounce = '', peekBounceAt = 0;
+  // Edge docking (pets with peek art): the peek sheet, which edge, eyes open/closed, lean and bounce.
+  // `windowEdge` is the edge the native window sits on; it becomes `docked` once the pet has peek art,
+  // so a pet switched in (or still loading) while the window is docked peeks from the same edge.
+  let peek = null, docked = '', windowEdge = '', peekEyes = 0, peekLean = 0, peekBounce = '', peekBounceAt = 0;
   let timer = 0, generation = 0, current = null;
   let base = 'idle', variant = '', queue = [], stateKey = '';
   // Session cards: keys already reacted to, cards the user dismissed, and whether the deck is spread out.
@@ -77,7 +86,8 @@
   let dragging = false, dragDir = 0, dragPauseTimer = 0, dragWatchTimer = 0, dragEndedAt = 0;
   let hovered = false, hoverOffTimer = 0, hoverReadyAt = 0, lastClickAt = 0;
   let sleeping = false, lastActivity = performance.now(), fidgetAt = 0, fidgetTimer = 0, lastFidget = '';
-  let greetingUntil = 0, greetingTimer = 0, rafId = 0, bodyRegions = [], spriteRect = null, bandCache = new Map();
+  let greetingUntil = 0, greetingTimer = 0, rafId = 0, bodyRegions = [], bodyBounds = null, bandCache = new Map();
+  let hoverPoint = null;
   let overlayKey = '', badgeTimer = 0;
 
   const pick = list => list[Math.floor(Math.random() * list.length)];
@@ -107,9 +117,10 @@
     const [w, h] = data.framesize;
     const frameScale = Math.min(184 / w, 140 / h);
     if (peeking()) {
-      const scale = frameScale / PEEK_ART_RATIO, width = peek.fw * scale, height = peek.fh * scale;
+      const { ratio, hidden } = peekStyle();
+      const scale = frameScale / ratio, width = peek.fw * scale, height = peek.fh * scale;
       return { peek: true, w: peek.fw, h: peek.fh, scale, width, height,
-        x: docked === 'right' ? cv.width - width + PEEK_HIDDEN : -PEEK_HIDDEN, y: cv.height - height - 2 };
+        x: docked === 'right' ? cv.width - width + hidden : -hidden, y: cv.height - height - 2 };
     }
     const width = w * frameScale, height = h * frameScale;
     return { w, h, scale: frameScale, width, height, x: (cv.width - width) / 2, y: cv.height - height - 8 };
@@ -124,9 +135,10 @@
     else if (kindOfMotion === 'wiggle') o.angle = Math.sin(now / 160) * 0.05;
     else if (kindOfMotion === 'peek') {
       // A shy, slow lean in and out; hovering or a waiting session makes her lean in further.
-      const sway = (1 - Math.cos(now / 1900)) * 3;
+      // The sway spans two thirds of the hidden strip, so it never stalls against that limit.
+      const sway = (1 - Math.cos(now / 1900)) * peekStyle().hidden / 3;
       peekLean += ((hovered ? 12 : base === 'waiting' ? 9 : 0) - peekLean) * 0.12;
-      o.dx = (docked === 'right' ? -1 : 1) * Math.min(PEEK_HIDDEN, sway + peekLean);
+      o.dx = (docked === 'right' ? -1 : 1) * Math.min(peekStyle().hidden, sway + peekLean);
       const since = now - peekBounceAt;
       if (peekBounce === 'happy' && since < 900) o.dy = -Math.abs(Math.sin(since / 90)) * 6 * (1 - since / 900);
       else if (peekBounce === 'shake' && since < 700) o.dx += Math.sin(since / 28) * 3 * (1 - since / 700);
@@ -142,7 +154,7 @@
     target.clearRect(0, 0, cv.width, cv.height);
     if (g.peek) {
       target.save();
-      target.imageSmoothingEnabled = true;
+      target.imageSmoothingEnabled = peekStyle().smooth;
       if (o) target.translate(o.dx, o.dy);
       // The art peeks from the right edge; mirror it for the left edge.
       if (docked === 'left') { target.translate(g.x * 2 + g.width, 0); target.scale(-1, 1); }
@@ -166,7 +178,6 @@
   function render() {
     if (!sheet || !data) return;
     const g = geometry();
-    spriteRect = g;
     paint(ctx, g, offsetAt(performance.now(), g));
     if (!rafId && continuous()) rafId = requestAnimationFrame(() => { rafId = 0; render(); });
   }
@@ -188,8 +199,11 @@
       }
       bandCache.set(key, bands);
     }
-    const [mx, my] = MOTION_MARGIN[activeMotion()] || [0, 0];
+    const motion = activeMotion();
+    const [mx, my] = motion === 'peek' ? [peekStyle().hidden + 4, 8] : MOTION_MARGIN[motion] || [0, 0];
     bodyRegions = bands.map(([l, t, r, b]) => [Math.max(0, l - mx), Math.max(0, t - my), Math.min(cv.width, r + mx), Math.min(cv.height, b + my)]);
+    bodyBounds = bands.length ? [Math.min(...bands.map(b => b[0])), Math.min(...bands.map(b => b[1])),
+      Math.max(...bands.map(b => b[2])), Math.max(...bands.map(b => b[3]))] : null;
   }
   function setFrame(frame) {
     if (!Array.isArray(frame?.images)) return;   // frames without images keep the previous picture
@@ -201,15 +215,25 @@
   function reportRegions() {
     const r = cv.getBoundingClientRect();
     const toWindow = b => [b[0] / cv.width, b[1] / cv.height, b[2] / cv.width, b[3] / cv.height];
-    // While hovered the whole sprite box stays hit-testable (as Codex does), so a jump that changes
-    // the silhouette under a resting pointer cannot flicker the hover on and off.
-    const g = spriteRect;
-    const bodies = hovered && g ? [toWindow([g.x - 4, g.y - 6, g.x + g.width + 4, g.y + g.height + 2])] : bodyRegions.map(toWindow);
-    // The fixed-size native handle uses these same CSS coordinates on both hosts.
-    bodies.push(normalized($('grip').getBoundingClientRect()));
+    const bodies = bodyRegions.map(toWindow);
+    // Keep only a small anchor under a stationary pointer when the animation jumps away.
+    // The rest of the transparent sprite frame remains click-through during hover.
+    if (hovered && hoverPoint) bodies.push(toWindow([hoverPoint.x - 3, hoverPoint.y - 3, hoverPoint.x + 3, hoverPoint.y + 3]));
+    const grip = $('grip');
+    grip.hidden = !bodyBounds;
+    // It follows the animated outline, but holds still under the pointer so it can be grabbed.
+    // It also stays below the collapsed card stack: that box (with its shadow padding) sits above
+    // the grip and would swallow the pointer, and macOS treats it as foreground, not the grip.
+    if (bodyBounds && !grip.matches(':hover')) {
+      const belowCards = stack.hidden || expanded ? 0 : stack.getBoundingClientRect().bottom;
+      const top = Math.max(0, belowCards, bodyBounds[1] * r.height / cv.height - grip.offsetHeight);
+      grip.style.left = Math.max(0, bodyBounds[0] * r.width / cv.width - grip.offsetWidth) + 'px';
+      grip.style.top = Math.min(Math.max(0, innerHeight - grip.offsetHeight), top) + 'px';
+    }
     // No card, no rectangle: the empty space above the pet stays click-through.
     const message = { type: 'overlay', controls: null,
-      rect: stack.hidden ? null : normalized(stack.getBoundingClientRect()), bubbles: bodies };
+      rect: stack.hidden ? null : normalized(stack.getBoundingClientRect()),
+      grip: grip.hidden ? null : normalized(grip.getBoundingClientRect()), bubbles: bodies };
     const key = JSON.stringify(message);
     if (key !== overlayKey && r.width > 0) { overlayKey = key; action(message); }
   }
@@ -263,7 +287,7 @@
     animation = rest.name; flipped = false; motionKind = ''; frameIndex = 0;
     setFrame(data.animations[rest.name].frames[0]);
   }
-  // ---- Edge peek (docked Whale Girl): blink now and then, happy squint on attention ----
+  // ---- Edge peek (docked pet): blink now and then, happy squint on attention ----
   function setPeekEyes(value) {
     peekEyes = value; frameIndex = value;
     updateBands(); render(); reportRegions();
@@ -295,8 +319,9 @@
     timer = setTimeout(() => { if (token === generation) playPeek(); }, kind === 'happy' ? 900 : 700);
   }
   function setDocked(side, { quiet = false } = {}) {
-    const next_ = side === 'left' || side === 'right' ? side : '';
-    if (next_ === docked || (next_ && !peek)) return;
+    windowEdge = side === 'left' || side === 'right' ? side : '';
+    const next_ = peek ? windowEdge : '';
+    if (next_ === docked) return;
     docked = next_; peekLean = 0; peekBounce = '';
     if (!sheet || quiet) return;
     next();
@@ -415,7 +440,26 @@
     stack.classList.toggle('layers-2', !expanded && cards.length > 2);
     stack.setAttribute('aria-label', cards.length > 1 && !expanded ? `${cards.length} 个会话动态，点击展开` : '会话动态');
     deck.replaceChildren(...cards.map(cardElement));
-    reportRegions();
+    fitStack(); reportRegions();
+  }
+  // The cards keep the transcript font size, but the pet shrinks with the window: below roughly
+  // 280px the collapsed stack would run past the top edge and be cut off. Shrink it just enough
+  // to fit above the pet (not below 9px text), else pin it to the top edge. The spread-out list
+  // scrolls inside the window and keeps the collapsed size.
+  function fitStack() {
+    if (expanded) return;
+    stack.style.removeProperty('--stack-fit');
+    stack.classList.remove('pinned');
+    if (stack.hidden) return;
+    const minFit = Math.min(1, 9 / parseFloat(getComputedStyle(stack).fontSize));
+    let fit = 1;
+    for (let pass = 0; pass < 3; pass++) {
+      const box = stack.getBoundingClientRect();
+      if (box.top >= -0.5 || fit <= minFit) break;
+      fit = Math.max(minFit, fit * box.bottom / box.height);
+      stack.style.setProperty('--stack-fit', fit.toFixed(3));
+    }
+    if (stack.getBoundingClientRect().top < -0.5) stack.classList.add('pinned');
   }
   function setExpanded(value) {
     clearTimeout(collapseTimer);
@@ -501,8 +545,10 @@
   function applyTranscriptFont(font) {
     const root = document.documentElement.style;
     const size = String(font?.size || '').trim(), family = String(font?.family || '').trim();
+    const before = root.cssText;
     if (/^\d+(\.\d+)?px$/.test(size)) root.setProperty('--pet-font-size', size);
     if (family && !/[;{}<>]/.test(family)) root.setProperty('--pet-font', family);
+    if (root.cssText !== before) { fitStack(); reportRegions(); }
   }
   function applySnapshot(value) {
     if (value?.version !== 1 || !Array.isArray(value.agents) || !Array.isArray(value.offices)) return;
@@ -528,14 +574,15 @@
     try { await image.decode(); } catch {
       if (revision === loadRevision) {
         deck.replaceChildren(cardElement({ key: 'load-failed', status: 'failed', title: '宠物素材加载失败', body: '请关闭后重新开启', local: true }));
-        stack.hidden = false; reportRegions();
+        stack.hidden = false; fitStack(); reportRegions();
       }
       return;
     }
     if (revision !== loadRevision) return;
     kind = value.kind; sheet = image; data = window.ClassicPetAgents[kind]; profile = normalizeProfile(PROFILES[kind]);
     peek = peekImage ? { image: peekImage, fw: peekImage.naturalWidth / 2, fh: peekImage.naturalHeight } : null;
-    docked = '';
+    docked = peek ? windowEdge : ''; peekLean = 0; peekBounce = '';
+    hovered = false; hoverPoint = null;
     bandCache = new Map(); images = null; base = 'idle'; variant = ''; queue = []; current = null;
     stateKey = ''; sleeping = false; lastFidget = '';
     // A newly shown pet greets instead of celebrating results that were already waiting.
@@ -597,16 +644,19 @@
     const r = cv.getBoundingClientRect();
     return { x: (event.clientX - r.left) * cv.width / r.width, y: (event.clientY - r.top) * cv.height / r.height };
   }
-  function overSprite(event) {
-    const g = spriteRect;
-    if (!g || !images?.length) return false;
+  function overSprite(event, updateAnchor = false) {
     const p = canvasPoint(event);
-    return p.x >= g.x - 4 && p.x <= g.x + g.width + 4 && p.y >= g.y - 6 && p.y <= g.y + g.height + 2;
+    if (bodyRegions.some(([l, t, r, b]) => p.x >= l && p.x < r && p.y >= t && p.y < b)) {
+      if (updateAnchor) hoverPoint = p;
+      return true;
+    }
+    return Boolean(hovered && hoverPoint && Math.abs(p.x - hoverPoint.x) <= 3 && Math.abs(p.y - hoverPoint.y) <= 3);
   }
   function setHovered(value) {
     clearTimeout(hoverOffTimer);
     if (hovered === value) return;
     hovered = value;
+    if (!value) hoverPoint = null;
     reportRegions();
     if (!value || dragging) return;
     const now = performance.now();
@@ -634,7 +684,9 @@
     }
     // The native move loop swallows the release; the next free move ends any stale drag pose.
     if (dragging && !(event.buttons & 1)) endDrag();
-    if (overSprite(event)) setHovered(true); else hoverOff();
+    if (overSprite(event, true)) {
+      setHovered(true); reportRegions();
+    } else hoverOff();
   });
   cv.addEventListener('pointerleave', hoverOff);
   cv.addEventListener('pointerup', event => {
@@ -690,7 +742,7 @@
   document.addEventListener('visibilitychange', () => {
     if (document.hidden) { stopPlayback(); cancelAnimationFrame(rafId); rafId = 0; } else if (sheet) next();
   });
-  window.addEventListener('resize', reportRegions);
+  window.addEventListener('resize', () => { fitStack(); reportRegions(); });
   window.addEventListener('pagehide', () => {
     stopPlayback(); loadRevision++;
     for (const id of [collapseTimer, badgeTimer, fidgetTimer, greetingTimer, dragPauseTimer, dragWatchTimer, hoverOffTimer]) clearTimeout(id);
@@ -709,7 +761,7 @@
     const selected = new URLSearchParams(location.search).get('pet');
     if (PROFILES[selected]) void setCharacter({ kind: selected,
       sprite: selected === 'whale' ? './whale/map.png' : `./classic/${selected}/map.png`,
-      peek: selected === 'whale' ? './whale/peek.png' : undefined });
+      peek: selected === 'whale' ? './whale/peek.png' : `./classic/${selected}/peek.png` });
   }
   reportRegions(); post('ready');
 })();
diff --git a/assets/desktop_pet/whale/README.md b/assets/desktop_pet/whale/README.md
index aad5caebf..2b26da51d 100644
--- a/assets/desktop_pet/whale/README.md
+++ b/assets/desktop_pet/whale/README.md
@@ -8,4 +8,4 @@
 
 ## 趴边偷看（peek.png）
 
-鲸鱼娘拖到屏幕左/右边缘吸附后改用 `peek.png`：两帧并排（左睁眼、右闭眼），每帧 178×300，透明背景，画面右缘就是她躲着的那条边（贴左边时页面水平镜像）。不来自上游项目，2026-10-16 用 Codex 的内置图像生成（codex-cli 0.162，`image_generation` 功能）绘制，以本目录 idle / welcome / joy 的首帧作为风格参考，要求同一角色设计与画风：从画面右缘探出半个头、双手扒着边、好奇又害羞地偷看。闭眼帧由同一张图做「只闭眼、其余不变」的编辑，再只把眼睛区域贴回睁眼图，眨眼时其余线条不抖动。纯绿背景抠成透明并去绿边，在她扒着的那条边线处裁掉，两帧同裁同缩放。这张原画比精灵帧大约 1.8 倍，页面按常规帧缩放 ÷ 1.8 绘制（`classic_pet.js` 的 `PEEK_ART_RATIO`），换图时要重新量这个比例。生成用的是 ZipZipPipe 设计的角色形象，沿用上游许可说明。
+鲸鱼娘拖到屏幕左/右边缘吸附后改用 `peek.png`：两帧并排（左睁眼、右闭眼），每帧 178×300，透明背景，画面右缘就是她躲着的那条边（贴左边时页面水平镜像）。不来自上游项目，2026-10-16 用 Codex 的内置图像生成（codex-cli 0.162，`image_generation` 功能）绘制，以本目录 idle / welcome / joy 的首帧作为风格参考，要求同一角色设计与画风：从画面右缘探出半个头、双手扒着边、好奇又害羞地偷看。闭眼帧由同一张图做「只闭眼、其余不变」的编辑，再只把眼睛区域贴回睁眼图，眨眼时其余线条不抖动。纯绿背景抠成透明并去绿边，在她扒着的那条边线处裁掉，两帧同裁同缩放。这张原画比精灵帧大约 1.8 倍，页面按常规帧缩放 ÷ 1.8 绘制（`classic_pet.js` 的 `PEEK.whale.ratio`），换图时要重新量这个比例。生成用的是 ZipZipPipe 设计的角色形象，沿用上游许可说明。
diff --git a/assets/seed/MANIFEST.json b/assets/seed/MANIFEST.json
index 4b0beb51d..2ac2c1793 100644
--- a/assets/seed/MANIFEST.json
+++ b/assets/seed/MANIFEST.json
@@ -1,5 +1,5 @@
 {
-  "bundle_version": "2026-10-15.1",
+  "bundle_version": "2026-10-16.1",
   "description": "Versioned default ACECode global Skill, expert, and managed hook seed bundle reconciled at startup.",
   "skills": [
     {
@@ -24,7 +24,7 @@
       "name": "expert-manager",
       "source_id": "acecode:expert-manager@2026-08-09",
       "relative_path": "expert-management/expert-manager",
-      "skill_md_sha256": "804fbfefb9cfb49a047182b82f1f6b6f42eb3ba1f42abb87e412fcaf24ef20a8"
+      "skill_md_sha256": "54250804b66e1e5b8658f7c56a3e4cd1fcd175cdfe2a583e1b2b9017ab0c0dc9"
     },
     {
       "name": "native-mcp",
diff --git a/assets/seed/seed.version b/assets/seed/seed.version
index 2e7a6e1d0..ed433c0e1 100644
--- a/assets/seed/seed.version
+++ b/assets/seed/seed.version
@@ -1 +1 @@
-2026-10-15.1
+2026-10-16.1
diff --git a/assets/seed/skills/expert-management/expert-manager/SKILL.md b/assets/seed/skills/expert-management/expert-manager/SKILL.md
index 6597412bb..119b9968e 100644
--- a/assets/seed/skills/expert-management/expert-manager/SKILL.md
+++ b/assets/seed/skills/expert-management/expert-manager/SKILL.md
@@ -34,6 +34,9 @@ description: 创建、导入、修改、校验和打包 ACECode 专家组件；
 - 如果已有资料足够，直接转化，不重复询问资料里已经明确的信息。
 - 高级能力默认保持“继承全局”。只有用户明确要求限制或启用特定 Skill、MCP
   服务器、本地工具时，才写入 `expert.json.capabilities`。
+- 采样参数默认继承模型。用户指定时写入 `expert.json.sampling`，支持
+  `temperature`、`top_p`、`top_k`、`min_p`；批量定义也接受同名对象。
+  不把采样值写成 Agent 指令或未经解析的 frontmatter。具体范围见包格式文档。
 
 ## 开始前检查
 
diff --git a/assets/seed/skills/expert-management/expert-manager/references/expert-json-spec.md b/assets/seed/skills/expert-management/expert-manager/references/expert-json-spec.md
index 2b191b4af..1ee5d50fa 100644
--- a/assets/seed/skills/expert-management/expert-manager/references/expert-json-spec.md
+++ b/assets/seed/skills/expert-management/expert-manager/references/expert-json-spec.md
@@ -17,6 +17,27 @@
 - 不写 `author`。ACECode 只使用 `displayName` 作为专家对外名称；来源和许可
   信息保留在 `NOTICE.md`、`license` 与 `homepage` 中。
 
+## 采样参数（可选）
+
+Agent 和 Team 的 `expert.json` 都可包含：
+
+```json
+"sampling": { "temperature": 0.3, "top_p": 0.95, "top_k": 20, "min_p": 0 }
+```
+
+每个字段独立可选，`null` 表示继承：temperature 为 0 到 2，top_p 大于 0 且不超过 1，
+top_k 为 1 到 2147483647 的整数，min_p 为 0 到 1。数值 0 必须保留。
+包内 `agents` 对象项也可声明 `sampling`，覆盖包级默认值。
+团队引用专家时使用各专家的有效预设，团队默认值补充未设置字段。
+子 agent 发起时传入的 `sampling` 具有最高优先级，模型设置作为最终默认值。
+
+实际运行仍受所选 provider/protocol 限制。Responses 不支持 top_k/min_p，Anthropic
+不支持 min_p 且 temperature 不超过 1。无法生效的设置会在会话启动或切换时被拒绝。
+管理 API 更新时省略 sampling 保留原预设，传 null 或空对象清除全部预设。
+单专家详情返回包含 lead 覆盖后的有效值；显式更新 sampling 时一并清除 lead 的旧覆盖。
+专家团的更新只替换团队默认值，被引用专家的预设保持独立。
+`batch_create.py` 接受同名字段，`validate_expert.py` 校验类型、范围和未知键。
+
 ## Agent 型必需字段
 
 ```json
diff --git a/assets/seed/skills/expert-management/expert-manager/scripts/batch_create.py b/assets/seed/skills/expert-management/expert-manager/scripts/batch_create.py
index 1fb1231a0..d99bf6374 100644
--- a/assets/seed/skills/expert-management/expert-manager/scripts/batch_create.py
+++ b/assets/seed/skills/expert-management/expert-manager/scripts/batch_create.py
@@ -42,6 +42,7 @@
     "homepage",
     "avatar",
     "stateAvatars",
+    "sampling",
 }
 AGENT_INPUT_KEYS = COMMON_INPUT_KEYS | {"instructions", "capabilities"}
 TEAM_INPUT_KEYS = COMMON_INPUT_KEYS | {"leadExpert", "memberExperts"}
@@ -67,7 +68,7 @@ def quick_prompts(item: dict[str, Any]) -> list[str]:
 
 
 def copy_optional_metadata(item: dict[str, Any], manifest: dict[str, Any]) -> None:
-    for key in ("license", "homepage"):
+    for key in ("license", "homepage", "sampling"):
         if key in item:
             manifest[key] = item[key]
 
diff --git a/assets/seed/skills/expert-management/expert-manager/scripts/validate_expert.py b/assets/seed/skills/expert-management/expert-manager/scripts/validate_expert.py
index af589bf4b..4f622ab1e 100644
--- a/assets/seed/skills/expert-management/expert-manager/scripts/validate_expert.py
+++ b/assets/seed/skills/expert-management/expert-manager/scripts/validate_expert.py
@@ -13,6 +13,7 @@
 
 import argparse
 import json
+import math
 import os
 import re
 from pathlib import Path
@@ -323,6 +324,32 @@ def validate_capabilities(
             seen.add(normalized)
 
 
+def validate_sampling(value: Any, result: ValidationResult, label: str = "sampling") -> None:
+    if value is None:
+        return
+    if not isinstance(value, dict):
+        result.error(f"{label} must be an object or null")
+        return
+    fields = {"temperature", "top_p", "top_k", "min_p"}
+    for key, number in value.items():
+        if key not in fields:
+            result.error(f"{label}: unknown field {key}")
+            continue
+        if number is None:
+            continue
+        if type(number) not in (int, float) or (type(number) is float and not math.isfinite(number)):
+            result.error(f"{label}.{key} must be a finite number")
+            continue
+        valid = {
+            "temperature": 0 <= number <= 2,
+            "top_p": 0 < number <= 1,
+            "top_k": type(number) is int and 1 <= number <= 2147483647,
+            "min_p": 0 <= number <= 1,
+        }[key]
+        if not valid:
+            result.error(f"{label}.{key} is outside its supported range")
+
+
 def validate_agent(
     package_root: Path, manifest: dict[str, Any], result: ValidationResult
 ) -> None:
@@ -340,6 +367,7 @@ def validate_agent(
         elif isinstance(entry, dict):
             agent_id = localized_text(entry.get("id"))
             raw_path = localized_text(entry.get("path"))
+            validate_sampling(entry.get("sampling"), result, f"agents[{index}].sampling")
         else:
             result.error(f"expert.json: agents[{index}] must be a path or object")
             continue
@@ -485,6 +513,7 @@ def validate_expert(
     validate_display_fields(manifest, result)
     validate_avatar_and_skills(package_root, manifest, result)
     validate_capabilities(manifest, expert_type, result)
+    validate_sampling(manifest.get("sampling"), result)
 
     if expert_type == "agent":
         validate_agent(package_root, manifest, result)
diff --git a/cmake/acecode_desktop.cmake b/cmake/acecode_desktop.cmake
index 6cbf8f24a..f7dfc8cbd 100644
--- a/cmake/acecode_desktop.cmake
+++ b/cmake/acecode_desktop.cmake
@@ -177,8 +177,10 @@ if(WIN32 OR APPLE)
             ${CMAKE_SOURCE_DIR}/assets/desktop_pet/classic_pet.js
             ${CMAKE_SOURCE_DIR}/assets/desktop_pet/classic/clippy/agent.js
             ${CMAKE_SOURCE_DIR}/assets/desktop_pet/classic/clippy/map.png
+            ${CMAKE_SOURCE_DIR}/assets/desktop_pet/classic/clippy/peek.png
             ${CMAKE_SOURCE_DIR}/assets/desktop_pet/classic/rover/agent.js
             ${CMAKE_SOURCE_DIR}/assets/desktop_pet/classic/rover/map.png
+            ${CMAKE_SOURCE_DIR}/assets/desktop_pet/classic/rover/peek.png
             ${CMAKE_SOURCE_DIR}/assets/desktop_pet/whale/agent.js
             ${CMAKE_SOURCE_DIR}/assets/desktop_pet/whale/map.png
             ${CMAKE_SOURCE_DIR}/assets/desktop_pet/whale/peek.png
diff --git a/docs/agent-browser-performance.md b/docs/agent-browser-performance.md
new file mode 100644
index 000000000..04f372793
--- /dev/null
+++ b/docs/agent-browser-performance.md
@@ -0,0 +1,328 @@
+# Agent Browser 性能改造方案
+
+对标项目：[browser-use/jev-ultrafast](https://github.com/browser-use/jev-ultrafast)（2026-09 抓取）。
+
+本文只谈**延迟**。正确性与隐私类问题另见文末「附录 B」，不在本方案范围内。
+
+---
+
+## 一、背景：jev 的「7 秒」是怎么来的
+
+jev-ultrafast 的卖点是一句话：一条自然语言目标，Google Flights 上从苏黎世搜到伦敦，
+**7.1 秒**，含模型调用、文本生成、浏览器操作和加载等待。
+
+拆开看，这 7 秒的构成与直觉相反：
+
+| 来源 | 占比 | 说明 |
+| --- | --- | --- |
+| 模型时间 | 绝对主导 | 每步一次模型请求，约 10 余步 |
+| 浏览器协议时间 | 零点几秒 | 整个任务 101 次 CDP 调用，持久会话上每次约毫秒级 |
+
+它自己公布的优化前后对比更说明问题：
+
+| 指标 | 优化前 | 优化后 | 变化 |
+| --- | --- | --- | --- |
+| 浏览器协议调用 | 1092 | 101 | 降低 91% |
+| 任务耗时中位数 | 9.450 秒 | 7.092 秒 | 降低 25% |
+
+**把浏览器协议调用砍掉 91%，任务只快了 25%。** 这是本方案最重要的一条背景事实：
+jev 的速度主要不来自浏览器代码，而来自它的**模型形态**和**每步只发一次请求**。
+
+它快的三个真实原因：
+
+1. **模型不是通用 LLM。** 决策模型是 TypeSafe 的 Jev，一个约束解码的分类器：输出一个
+   操作枚举（`CLICK` / `TYPE_TEXT` / `SELECT` / `SCROLL_UP` / `SCROLL_DOWN` / `WAIT` /
+   `DONE` / `BLOCKED`）加一个元素序号。只有需要输入文本时才调一次小而快的文本模型，
+   当前 demo 用 `inception/mercury-2.5` 且关闭 reasoning。
+2. **每个决策周期一次网络往返。** 操作头和目标头共享同一份观测状态，投机式扇出，
+   一次请求同时拿到「做什么」和「对谁做」。目标头里只包含与该操作兼容的元素。
+3. **步数少，且每步的状态是替换而非累积。** 模型每步只看当前元素表，历史是一份
+   紧凑的决策列表，不是一堆过期页面全文。
+
+它明确不做的：默认循环里**没有截图**；结构化状态就是全部输入。截图只给它的可视化
+inspector 用，演示视频走独立的 screencast。
+
+### jev 在浏览器侧做的事（值得借的部分）
+
+即使浏览器侧只值 25%，这 25% 的做法仍然干净，值得参考：
+
+- **一次快照一次调用。** `jev_ultrafast/snapshot.js` 一个 `Runtime.evaluate` 原子返回
+  url、title、viewport、可见文本、动作表、新鲜度标记、逐节点守卫。
+- **只发可见内容。** 元素中心点落在视口外的直接丢弃；正文用 Range 的 rect 判断是否
+  真在屏幕上，上限 6000 字符。屏幕外的正文和页脚不进模型上下文。
+- **动作空间而非元素空间。** 表里每一行都是可执行动作：`<select>` 的每个选项各一行
+  select 动作；可编辑 combobox 额外给一行「Open X」的 click；页面能滚动时才追加
+  scroll_up / scroll_down。模型只挑序号，不可能的操作根本不在候选里。上限 250 条，
+  超出回报 `omitted_actions`。
+- **等待极短且有条件。** 输入后最多两个动画帧或 50 毫秒；往 combobox 填字时改为等
+  可见的 `[role="option"]` 出现，上限 200 毫秒。而且这个等待挂在**下一次**观测上，
+  执行结果先落账。
+- **后台标签页不被节流。** `Emulation.setFocusEmulationEnabled` 让自己拥有的后台页
+  保持 rAF 和菜单渲染，同时不抢用户正在看的标签页。
+- **几何确定化。** `Emulation.setDeviceMetricsOverride` 固定 1120x780。
+- **填字一次到位。** selectAll 后 `Input.insertText` 整段写入，不逐字符敲。
+
+### jev 的边界
+
+MVP 明确不处理 shadow root、iframe、canvas、文件上传、弹出标签页、嵌套滚动和任意
+键盘组件。`DONE` 仍需独立验证。这些方面它没有可借的实现。
+
+---
+
+## 二、ACECode 的延迟预算与 jev 不同
+
+同一个任务，ACECode 慢一到两个数量级，但**瓶颈不在 `browser_tools.cpp` 里**：
+
+| 项 | jev | ACECode 现状 | 量级 |
+| --- | --- | --- | --- |
+| 每个动作的模型往返次数 | 1 | 2 | 2 倍 |
+| 每次请求携带的页面状态 | 约 3 至 4 千 token，每步替换 | 约 15 千 token，逐次累积 | 数量级 |
+| 每次点击的浏览器请求数 | 约 3，持久会话 | 7，每次新建连接 | 每动作百毫秒级 |
+| 每次点击的固定等待 | 50 毫秒 | 80 毫秒，导航另加 300 毫秒 | 每动作百毫秒级 |
+
+前两行是数量级差距，后两行是每动作一两百毫秒。**优化顺序必须按这个排。**
+
+---
+
+## 三、现状测绘
+
+以下均为代码核对结果，可逐条复查。
+
+### 3.1 一次 `browser_click` 是 7 次 IPC 请求
+
+`src/adapters/tool/agent_browser/browser_tools.cpp:653-686`：
+
+| # | 调用 | 位置 | 备注 |
+| --- | --- | --- | --- |
+| 1 | `claim_page` 或 `select_page` | `connect_client` `:192` | 每个工具都做 |
+| 2 | `Runtime.evaluate` 解析目标 | `resolve_target` `:292` | 返回 rect / role / name |
+| 3 | `Runtime.evaluate` 画 AI 指针 | `show_agent_pointer` `:669` | 纯视觉，**随后固定睡 80 毫秒** |
+| 4 | `Input.dispatchMouseEvent` mouseMoved | `:672` | |
+| 5 | `Input.dispatchMouseEvent` mousePressed | `:673` | |
+| 6 | `Input.dispatchMouseEvent` mouseReleased | `:675` | |
+| 7 | `Runtime.evaluate` 读页面摘要 | `page_summary` `:234` | 只为 url / title / ready_state 三个字段 |
+
+`browser_drag` 更重：2 次解析 + 2 次指针 + press + 8 步插值 mouseMoved + release + 摘要，
+约 16 次请求（`:928-976`）。
+
+`browser_read_page` 是 2 次（claim + 一次快照 evaluate），**快照本身已经是良好的批量设计**。
+
+### 3.2 传输层每个请求新建一条连接
+
+`AgentBrowserCdpClient::request()` 每次调用都完整走一遍：`open_proxy_pipe` /
+`open_proxy_socket`（`src/adapters/tool/agent_browser/cdp_client.cpp:551` / `:562`）、写 u32 长度 +
+JSON、读 u32 长度 + JSON、写 1 字节 ack、`close_pipe()`（`:622-627`）。
+
+即：**一次点击建立并拆除 7 条命名管道或 Unix socket**，没有任何连接复用。
+
+### 3.3 固定 sleep 清单
+
+| 位置 | 时长 | 性质 |
+| --- | --- | --- |
+| `browser_tools.cpp:520` | 250 毫秒 | `browser_open` 无条件 |
+| `browser_tools.cpp:594` | 300 毫秒 | `browser_navigate` 无条件 |
+| `browser_tools.cpp:40` `:670` | 80 毫秒 | `kPointerClickLeadTime`，click / drag 前 |
+
+没有任何基于 `Page.loadEventFired` 或生命周期事件的等待。click / type / fill / press /
+hover / scroll / drag 之后**零 settle**，`url` / `title` / `ready_state` 在最后一个输入事件
+之后立刻采样——所以**一次触发跳转的点击基本都回报旧 URL**，模型据此会误判「没跳转」。
+
+显式等待完全交给模型调 `browser_wait`，它每 100 毫秒轮询一次 evaluate（`:1110`），
+默认上限 10 秒，最大 120 秒，即最坏 1200 次 evaluate。
+
+### 3.4 快照体积
+
+`agent_browser_snapshot_script()`（`browser_tools.cpp:1311-1370`）默认值：
+
+- `max_text_chars` 默认 30000，上限 50000（`:1314`）——取的是整页 `document.body.innerText`，
+  不区分是否在视口内（`:1365`）。
+- `max_elements` 默认 300，上限 500（`:1313`）——文档顺序取前 N 个可见元素，
+  不按视口过滤（`:1333-1334`）。
+- 选择器里包含 `option`（`:1333`），所以**一个 250 项的国家下拉能吃掉整个元素预算**。
+- 截断后没有任何「被省略了多少」的信号。
+
+粗算一次 `browser_read_page` 约 15 千 token（正文约 8 千，元素表约 9 千，中文更高）。
+而这份结果作为工具结果**永久留在对话历史里**，后续每一轮都要重发。读五次页面就是
+约 75 千 token 的过期页面文本参与此后每一轮的计费与 TTFT。
+
+### 3.5 每个动作需要两次模型往返
+
+`browser_click` 返回 `{target, clicked, url, title, ready_state}`（`:678-686`），
+**不含新的页面状态**。模型点完按钮不知道页面变成什么样，只能再发一轮
+`browser_read_page`。所以稳态是「一个动作两轮模型」。
+
+一条有利的现状：`window.__aceAgentBrowserSnapshot` 只在快照脚本里重写
+（`:1341`），点击**不会**改变 `revision`，所以同一次读取拿到的 `@eN` 在多个动作之间
+一直有效。这意味着批量执行不需要引入新的引用机制。
+
+---
+
+## 四、方案
+
+四个杠杆，按收益排序。杠杆 1 与 2 解决数量级问题，3 与 4 解决常数问题。
+
+### 杠杆 1：mutation 工具回带页面状态（每动作 2 轮 → 1 轮）
+
+**动机**：见 3.5。这是最便宜的一倍。
+
+**改法**：把 `success_result_with_page`（`:245-262`）从「只读 url / title / ready_state」
+升级为「顺带返回一份新的紧凑元素表」，并与动作脚本合并为同一次 evaluate。
+为控制体积，回带的表用比 `browser_read_page` 更严的预算（例如仅视口内、正文上限
+2000 字符），并带上新的 `revision`。
+
+**预期**：模型往返减半；顺带干掉 3.1 里的第 7 次请求。
+
+**风险**：每个动作结果都变大。必须配合杠杆 3 先把快照瘦身，否则省下的往返会被
+膨胀的历史吃回去。**因此杠杆 3 应先于杠杆 1 落地。**
+
+### 杠杆 2：批量动作工具（N 轮 → 1 轮）
+
+**动机**：jev 一个任务十几步，每步一次小模型请求。ACECode 每步一次前沿模型请求，
+无法把单步变快，只能**减少步数**。
+
+**改法**：新增一个批量工具，接一串步骤，例如「click @e3 / fill @e5 "Zurich" /
+click @e7」。语义要求：
+
+- 每步执行前做自己的新鲜度与命中校验，第一步不匹配就**停下**，回报已完成到哪一步、
+  失败原因、以及失败时刻的页面状态。
+- 绝不在中途静默跳过或猜测。
+- 步数上限与总时长上限可配置。
+- 沿用 `@eN` + `revision`，不引入新的引用机制（依据见 3.5 末段）。
+
+**预期**：填一张表从七八轮往返压到一轮。这是本方案单项收益最大的一条。
+
+**风险**：批量失败的语义必须极其清楚，否则模型会对「做到一半」的页面状态产生错误
+前提。这也是必须先做遮挡命中测试（附录 B 第 1 条）的原因——批量执行会放大静默
+失败的后果。
+
+### 杠杆 3：快照瘦身（单次读取约 15 千 token → 约 3 千）
+
+**动机**：见 3.4。这一项的收益是复利的，因为它减少的是**此后每一轮**的 prompt 体积。
+
+**改法**，全部在 `agent_browser_snapshot_script()` 内：
+
+1. **按视口过滤元素**。中心点落在 viewport 外的丢弃，照抄 jev 的判据。
+2. **正文只取屏幕上可见的文本段**，用 Range 的 rect 判断，上限降到 6000 字符。
+3. **`option` 从选择器移除**，折叠进父级 select；参考 jev 的做法，把每个可选项表达
+   成父元素上的一个 select 动作。
+4. **回报被省略的数量**，对齐 jev 的 `omitted_actions`，让模型知道自己看的是截断视图。
+5. 顺带：`checkVisibility({checkOpacity:true, checkVisibilityCSS:true})` 加
+   `closest('[aria-hidden="true"],[inert]')` 替换手写的 `getComputedStyle` 三连判断
+   （`:1315-1321`），一次原生调用，更便宜也更正确。
+
+**预期**：单次读取压到三四千 token，约 5 倍。**不触碰对话历史，无 prompt cache 风险。**
+
+**关于「抹掉过期快照」**：把历史里被取代的旧快照替换成 stub 能省更多，机制上也已有
+先例（PA 兜底里的 `ThreadRepairOptions::clear_tool_outputs`）。但按 CLAUDE.md 的
+prompt cache 前缀不变量，改写历史会从改写点截断缓存，后面整条尾巴全价重算。
+**本方案不做这一项**，先靠源头瘦身拿掉大部分收益；若将来仍需要，应设计成
+低频水位触发而非每轮触发，并单独评估缓存代价。
+
+### 杠杆 4：浏览器侧固定开销（每动作约 380 毫秒 → 约 50 毫秒）
+
+四条互相独立：
+
+1. **连接复用**。`AgentBrowserCdpClient` 持有长连接，7 次连接建立变 1 次。
+   需要处理 host 重启、页面关闭与超时后的重连，失败时回落到当前的每请求建连行为。
+2. **指针不挡关键路径**。`kPointerClickLeadTime` 那 80 毫秒是纯视觉效果
+   （`:40` `:669-670`）。改成不等待返回，或者点击之后再画轨迹。指针本身是
+   `pointer-events:none` 的 shadow root 覆盖层，不会造成遮挡，这一点不变。
+3. **页面摘要合进动作脚本**。`page_summary`（`:234-243`）为三个字段单独跑一次
+   evaluate，应与杠杆 1 一起合并。
+4. **固定 sleep 换条件等待**。`browser_open` 的 250 毫秒与 `browser_navigate` 的
+   300 毫秒（`:520` `:594`）换成 jev 那种「最多两个动画帧或 50 毫秒」的有上限条件
+   等待；往 combobox 填字后改为等可见 `[role="option"]`，上限 200 毫秒。
+
+做完这四条，一次点击从 7 个请求降到 2 个，固定等待从 380 毫秒降到 50 毫秒。
+
+**附带修掉一个已知限制**：`docs/agent-browser.md:161` 记着「非显示页面的 WebView2
+处于隐藏状态，Chromium 会节流定时器」。`Emulation.setFocusEmulationEnabled` 正是
+jev 用来解决同一问题的手段，让后台页保持渲染而不抢用户正在看的标签页。
+建议在这一杠杆里一并接上，同时用 `Emulation.setDeviceMetricsOverride` 固定几何。
+
+---
+
+## 五、更远的选项：`browser_task` 子代理
+
+如果要真正对齐 jev 的架构，而不只是在现有形态里榨常数：
+
+新增一个 `browser_task(goal)` 工具，内部跑 jev 那套「索引动作空间 + 每步一次请求」
+的小循环，配一个独立配置的快模型，只把最终结果回给主模型。主模型全程只花一轮。
+
+ACECode 已有两处同形状的先例可以复用设计：`spawn_subagent` 的子会话机制，以及
+`vision_analyze` 那种「一次性子调用 + 独立模型连接」的模式（`image_generation` 与
+`vision_analyze` 都已经这么做）。
+
+这是换形态，成本和风险都显著高于前四个杠杆，**建议在杠杆 1 至 4 落地并量到收益之后
+再单独立项**。
+
+---
+
+## 六、明确不做
+
+- **不动截图路径。** 截图本来就不在默认循环里，只由 `browser_screenshot` 产生，
+  这一点已经与 jev 一致。
+- **不改填字方式。** 已经在用 `Input.insertText` 整段写入，不是逐字符。
+- **不重构快照的批量性。** 快照已经是一次 evaluate 原子返回，设计正确。
+- **不抄 jev 的安全立场。** jev 声明「模型输出永不变成选择器、坐标、shell 命令或
+  可执行 JS」。ACECode 有意暴露 `selector` 目标与 `browser_evaluate`，按 CLAUDE.md
+  的定位这是**永久开发宽松浏览器**，不应照抄收紧。
+- **不抄 shadow DOM / iframe 支持。** jev 的 MVP 同样不支持，没有可借的实现。
+- **不做历史快照抹除**（理由见杠杆 3 末段）。
+
+上面三条「已经做对」恰好是这类项目最常见的性能坑，先确认无需返工。
+
+---
+
+## 七、实施顺序与验证
+
+建议顺序（杠杆 3 必须先于杠杆 1，理由见杠杆 1 的风险项）：
+
+| 阶段 | 内容 | 预期收益 | 独立性 |
+| --- | --- | --- | --- |
+| 1 | 杠杆 3 快照瘦身 | 单次读取约 5 倍 | 完全独立 |
+| 2 | 杠杆 4 浏览器侧常数 | 每动作约 330 毫秒 | 完全独立 |
+| 3 | 杠杆 1 回带页面状态 | 模型往返减半 | 依赖阶段 1 |
+| 4 | 杠杆 2 批量动作 | 单项最大 | 依赖阶段 3 与附录 B 第 1 条 |
+
+**量化口径**：改造前后各跑同一组任务，记录三个数字，缺一不可。
+
+1. 单任务的模型往返次数。
+2. 单任务的 IPC 请求总数。
+3. 单任务墙钟耗时，并分离出模型时间与浏览器时间。
+
+只看墙钟会把模型侧的抖动误判成改造效果。jev 自己也强调它那组数据是「单任务、单
+浏览器配置、三次重复」，不是通用可靠性基准；我们的口径同样要写清样本条件。
+
+改动集中在 `src/adapters/tool/agent_browser/browser_tools.cpp` 与 `cdp_client.cpp`，
+按 AGENTS.md 的命令集跑 `acecode_unit_tests`；杠杆 4 的连接复用需要 Windows 与 macOS
+两端实测，因为传输实现不同（命名管道与 Unix socket）。
+
+---
+
+## 附录 A：jev 中可直接移植的片段
+
+| 用途 | jev 位置 | 移植目标 |
+| --- | --- | --- |
+| 可见性判据 | `snapshot.js` 的 `visible` | 替换 `browser_tools.cpp:1315-1321` |
+| 视口过滤与动作表构造 | `snapshot.js` 主循环 | `agent_browser_snapshot_script()` |
+| 可见文本提取 | `snapshot.js` 的 TreeWalker + Range | 同上 |
+| 执行前命中测试 | `browser.py` 的 target 脚本 | `element_mutation_script` 与 click 路径 |
+| 有上限的条件 settle | `browser.py::observe` 的 rAF 脚本 | 替换 `:520` `:594` 的固定 sleep |
+
+## 附录 B：与性能无关但建议顺手修的两条
+
+这两条不在本方案范围内，但杠杆 2 会放大第 1 条的后果，建议同期处理。
+
+1. **点击前没有遮挡命中测试。** 目标在第 2 次请求解析出坐标，随后经过 80 毫秒指针
+   等待和至少 4 次 IPC 往返才真正派发，全程不重新验证几何，也没有
+   `document.elementFromPoint` 命中测试（可见性判据见 `:269`）。cookie 横幅或 modal
+   盖住目标时点击被吞掉，工具仍回报 `clicked:true`。jev 在执行前重新解析并做
+   `e.contains(document.elementFromPoint(x,y))`，不过就要求重新观察。
+
+2. **密码会进模型上下文与会话存档。** 快照选择器包含 `input` 且不排除
+   `type="password"`（`:1333`），每个元素都带 `value: String(el.value).slice(0, 500)`
+   （`:1350`）；`textOf` 在没有 aria-label 时也会把 value 当作 name（`:1322-1325`）。
+   用户在 Agent Browser 页面登录后，任何一次 `browser_read_page` 都会把明文密码写进
+   transcript 与会话 JSONL。jev 用一行 `safe = e => !['password','file','hidden'].includes(e.type)`
+   挡掉。建议独立修复，优先级高于本方案全部性能项。
diff --git a/docs/computer-use.md b/docs/computer-use.md
index 214864865..fa531411f 100644
--- a/docs/computer-use.md
+++ b/docs/computer-use.md
@@ -8,6 +8,19 @@
 
 本次参考本地 Codex 的 Windows 工具能力与接入方式，自主实现 C++ 原生后端。Codex 仓库中的 MCP 桥接代码不包含其专有 `@oai/sky` 运行时，因此这里不依赖该插件或 JavaScript REPL。
 
+### 与 Codex macOS 实现的关系
+
+2026-09-24 核对了本机 Codex 应用包内 `cua_node/lib/node_modules/@oai/cua/dist/project/cua/sky_js/src/targets/mac/` 的 `client.js`、`get_app_state.js`、`window_result.js` 和 `native-pipe.js`。这些文件是 JavaScript 客户端，使用 `CodexComputerUseIPC-5` 调用独立的 `Codex Computer Use.app` 原生服务；它们不包含原生指针绘制代码。本机 CLI 源码和检查到的应用资源中均未找到该服务的原生实现。
+
+| 核对项 | Codex 客户端中可确认的行为 | ACECode 当前实现 |
+|---|---|---|
+| 观察对象 | 按应用身份请求 skyshot，由原生服务返回截图和文字 | 按窗口请求截图、结构化 AX 控件树和一次性观察标识 |
+| 动作入口 | `ComputerUseIPCAppPerformActionRequest`，包含应用身份与动作 | 现有 `computer_*` 工具，经自有 broker/helper 执行 |
+| 文字操作 | 独立 `type`、`paste`、`selectText`、`setValue` | Unicode 键盘输入、按键组合和 AX 赋值；尚无专用粘贴和按文字选择接口 |
+| 原生指针 | 客户端没有提供渲染、动画或生命周期实现 | ACECode 自行实现 AppKit 悬浮窗和截图合成，视觉反馈以现有 Windows 后端为参照 |
+
+因此当前 macOS 后端属于自主实现，不能称为 Codex 原生代码的移植或完整行为复刻。后续对齐应逐项记录可观察的输入、输出和实际桌面效果；源码不能证明的细节需要对照运行结果验证。
+
 ## 功能
 
 | 工具 | 行为 |
@@ -49,6 +62,7 @@ Windows 组合键支持 Codex 文档中的 keysym 名称和常用别名，例如
 - 设置中的权限区显示“辅助功能”和“屏幕录制”的独立状态。“去授权”会请求对应系统权限并打开系统设置；必须由用户在系统显示的应用条目下授权，再点击“刷新权限”。读取配置、刷新状态和打开工具开关都不会主动弹授权框。不同启动方式可能由系统归属到不同应用；以 macOS 显示的名称为准，权限检查始终在实际 helper 进程内进行。
 - `enabled` 表示用户开启意图，`availability.ready` 表示两项权限均就绪。开关不会伪装成系统授权。没有屏幕录制权限时可返回明确警告及可用的 AX 控件信息，不能生成可用于坐标动作的截图标识；没有辅助功能权限时拒绝观察和输入。
 - 截图只捕获指定窗口，关闭系统光标和窗口阴影；合成 ACE/plain 指针。图片坐标换算到屏幕点坐标，保留 Retina、非整数缩放和负屏幕原点。没有可见操控指针时 `cursor.visible` 为 `false`，不伪造系统光标。
+- 鼠标和 AX 控件动作显示目标指针；按键和文字输入在可见、已验证的焦点控件处显示指针。点击反馈保留 250 ms，不延长真实鼠标按下时间。指针不抢焦点、不拦截输入，释放、取消或回合结束后清除。列举、启动和观察应用本身不会移动系统鼠标或生成点击反馈。
 - 窗口绑定同时核对进程启动身份、CG 窗口几何与 AX 窗口；不能唯一匹配时拒绝输入。弹层必须从窗口的 AX 层级或已验证的前台窗口菜单层级发现，最多返回三个；不以“同一进程”推断无关浮动窗口归属。
 - 输入前检查前台应用、焦点窗口、观察有效期、控件几何、实际窗口遮挡及 AX 命中。键盘还检查具体焦点控件，避免输入到同一应用的另一个窗口。观察标识有效期为 90 秒且只能用于一次输入；失败后也需重新观察。
 - `computer_press_key` 支持 `Cmd+A`、`Option+Left`、`Ctrl+Shift+Tab`、F1–F20、方向键和 Numpad 键等。字符快捷键按当前键盘布局解析，修饰键需显式指定；文字使用 Unicode 输入。滚动量使用像素，`scrollX` 正值向右、`scrollY` 正值向下；Windows 的 120 单位滚轮语义保持不变。
@@ -65,6 +79,8 @@ macOS 构建生成 `acecode-computer-use`，独立 CLI 包中与 `acecode` 相
 
 macOS 原生验证目标为 `computer_use_native_mac_smoke`，运行其 `.app/Contents/MacOS/computer_use_native_mac_smoke --run-owned-window`，经真实 broker/helper 操作专用测试窗口；`--observe-owned-window` 只验证观察。缺少权限返回退出码 77，表示未验证。几何和键名解析有独立单测；`tests/computer_use/macos_helper_test.py <helper>` 验证协议上限、互斥租约和父进程退出，不需要输入权限。
 
+macOS 指针检查还独立枚举实际 helper 的 WindowServer 悬浮窗，用 ScreenCaptureKit 单独捕获该窗口，验证颜色、热点位置、焦点保持、点击穿透和释放后的消失；它不以工具返回截图中的合成指针作为桌面可见性的证明。锁屏时返回 77，真实可见性保持未验证。设置 `ACECODE_MAC_FIXTURE_ARTIFACTS` 可保存测试窗口图片和单独捕获的 `native-overlay.png`，不截取其他应用内容。
+
 原生集成验证使用专门的可丢弃窗口：构建 `computer_use_native_smoke`，传入 `--observe-owned-window` 检查窗口发现、应用启动、遮挡截图、缩放、密码字段、弹层归属和控件命中；传入 `--run-owned-window` 继续检查鼠标键盘、控件操作和真实 OLE 拖放。后者需要测试窗口能获得前台焦点，系统搜索菜单等界面可能阻止激活，此时明确失败，不向错误窗口发送输入。可用 `--wait-for-foreground` 等待用户点击测试窗口标题栏后执行，超时自动结束。独立的 `computer_use_broker_smoke` 使用私有假执行器验证超时、取消、并发租约和大响应，不接触桌面。
 
 `--run-owned-window-via-helper` 通过生产 broker、真实独立执行器和私有管道运行同一套完整检查，不回退到进程内调用。它验证中文与补充平面字符输入、辅助控件动作、菜单/下拉框选择、画布对象最终位置、OLE 目标 payload，以及可用显示器和缩放截图的实际坐标点击。测试窗口结束时销毁，不把事件已入队当作动作已完成。主题指针验证覆盖本次可用的一台显示器及 3000 像素窗口缩放；负原点等布局另有坐标单测覆盖。测试同时核对系统光标、UIA/点击后的可见桌面指针、PNG 指针热点及缩放一致性，并检查 ACE / plain 在默认蓝色和指定主题色下的实际 PNG 像素，截图保存到系统临时目录。
diff --git a/docs/daemon-api.md b/docs/daemon-api.md
index 318911bc4..3cfba4900 100644
--- a/docs/daemon-api.md
+++ b/docs/daemon-api.md
@@ -410,7 +410,7 @@ Development `--static-dir` resources continue to be read from disk on each reque
 | DELETE | `/api/memory/:scope/:name?workspace=<hash>` | delete one entry and record a tombstone |
 | POST | `/api/memory/reset` | clear one scope (entries, index, inbox, archive) |
 | GET | `/api/config/tool-rewrites` | read tool rewrite settings plus the built-in tool catalog |
-| PUT | `/api/config/tool-rewrites` | replace tool rewrite settings, persist `tool-rewrites.json`, apply live |
+| PUT | `/api/config/tool-rewrites` | replace tool rewrite settings, persist `tool_rewrites.json`, apply live |
 | GET | `/api/config/tool-preamble` | read the concrete progress text switch (work mode) |
 | PUT | `/api/config/tool-preamble` | set the concrete progress text switch in `config.json`, push to active sessions |
 | GET | `/api/config/sandbox` | read sandbox switches, filesystem lists, defaults and platform probe |
@@ -2827,6 +2827,22 @@ Creating an ID shadowed by a workspace package returns
 returns `409 EXPERT_ALREADY_EXISTS`. Updating or deleting a workspace-sourced
 package also returns `409 WORKSPACE_EXPERT_READ_ONLY`.
 
+Expert definitions and create/update payloads also support `sampling`:
+`{"temperature":0.3,"top_p":0.95,"top_k":20,"min_p":0}`. Each key is optional.
+Updates that omit `sampling` preserve the stored preset; `null` or `{}` clears it.
+For a single expert, the response includes its lead's effective preset; explicit
+updates replace that complete preset, removing any package-authored lead override.
+Team updates change team defaults and leave referenced experts' presets intact.
+Unknown sampling keys, invalid types and out-of-range values are rejected. Generic
+ranges match saved models; actual provider/protocol support is checked when the
+expert is selected or a session is created. A team's preset supplies defaults;
+each referenced expert's preset overrides its fields. The `agents[].sampling`
+response describes the effective expert preset for that member. Session-local
+sampling supplied by `spawn_subagent` or `agent_spawn` has highest priority and
+is persisted independently of saved model settings. Expert switching publishes
+the new sampling settings at the same control boundary as the role; an
+incompatible switch keeps the existing role and provider.
+
 Each of `capabilities.skills`, `capabilities.mcp_servers`, and
 `capabilities.tools` is independently optional:
 
@@ -4156,7 +4172,7 @@ either name. This is an explicit opt-in for audit scenarios; the process
 default is no rewriting.
 
 The data is **not** part of `config.json`. It lives in
-`<data_dir>/tool-rewrites.json` next to `config.json`, shared by the daemon,
+`<data_dir>/tool_rewrites.json` next to `config.json`, shared by the daemon,
 the TUI and headless mode, and is loaded once at startup before tool
 registration:
 
@@ -4427,7 +4443,7 @@ Manifest checks and package transfers do not use a fixed total request timeout.
 Transport, HTTP, and file-write failures are still reported normally.
 
 Checks and upgrades append flushed JSON diagnostic records to the ACECode data
-directory's `logs/upgrade-YYYY-MM-DD-PID.log` (UTC date). Each attempt has an
+directory's `logs/upgrade_YYYY_MM_DD_PID.log` (UTC date). Each attempt has an
 `operation_id`; GUI precheck, worker, and installer records share that id, and
 GUI records also include `job_id`. Records include phase, elapsed milliseconds,
 versions, paths, HTTP/transport status, download byte counts, checksum values,
@@ -4907,7 +4923,7 @@ runtime is not long-path aware: a copied file whose final path reaches 260
 characters may be unreadable at runtime, and completion logs a warning with the
 count and one sample path.
 
-Success atomically publishes the copied directory, writes `data-dir.redirect.json`
+Success atomically publishes the copied directory, writes `data_dir.redirect.json`
 in the platform default data directory, and sets `restart_required:true`. The
 current process continues reading the old root; new turns and authenticated
 mutations are rejected with `409 DATA_DIR_MIGRATION_ACTIVE` until restart.
@@ -5453,7 +5469,7 @@ Resize uses `POST /api/pty/:id/resize`, not the WebSocket.
 ## 14. Scheduled tasks
 
 Scheduled tasks (Chinese UI: “定时任务”, internal identifier: LOOP) is a daemon-owned scheduler. It persists to
-`<acecode_dir>/scheduled-loops.sqlite3` and continues running without an open
+`<acecode_dir>/scheduled_loops.sqlite3` and continues running without an open
 browser. Clients configure friendly period/interval/once fields; the compiled
 schedule expression is internal and is never returned by the API.
 
@@ -5958,3 +5974,5 @@ Backs the `ios_simulator` / `ios_simulator_build` tools, Settings > Tools > iOS
 `helper.sandboxed` is true while the helper runs inside its Seatbelt profile; `sandbox_note` explains an unconfined helper (`ACECODE_IOS_SIM_SANDBOX=0`, no `sandbox-exec`, or the profile could not be applied).
 
 Tool results of `ios_simulator` carry `metadata.ios_simulator = {action, udid, name, runtime, point_width, point_height, rotation}`; the web UI opens the panel on `attach` and closes it on `detach`.
+
+Runtime-generated names use underscore separators. Existing hyphen-named data remains accessible; see [运行数据命名](runtime_file_naming.md).
diff --git a/docs/desktop-agent-office.md b/docs/desktop-agent-office.md
index 59cc4935f..df9848325 100644
--- a/docs/desktop-agent-office.md
+++ b/docs/desktop-agent-office.md
@@ -9,14 +9,14 @@ Windows 与 macOS Desktop 可开启透明桌面宠物，默认关闭。设置 
 行为引擎在 `assets/desktop_pet/classic_pet.js`，对照 Codex 桌面版 Mini 宠物的实现（`avatar-overlay-native-page` 与精灵播放器：状态 idle / running / waiting / failed / review / waving，悬停 jumping，拖动 running-left / running-right）。每只宠物在 `PROFILES` 里把这套词汇映射到自己的原始动作，改动作只改这张表。
 
 - **没有顶部工具条**：陪伴宠物不显示最近五个会话、跟随、置顶和关闭按钮；右键菜单提供「切换宠物」二级菜单（四种宠物，当前那只打勾，与设置页走同一条保存路径）、「回到右下角」「保持置顶」、缩放和「隐藏桌面宠物」。四种宠物（含虚拟办公室）的右键菜单相同。
-- **会话卡片（复刻 Codex Mini）**：每个正在运行、等你处理、失败或完成后还没看过的主会话一张卡片，跨工作区，按最近发消息时间排序：加粗标题 + 一行内容，字体、字号、行高与 ACECode 对话正文完全一致（主页面每次推送快照都带上当前的 `--font-sans` 和 `--ace-font-size-13`，跟随设置里的小 / 中 / 大字号，默认 14px、行高 1.6）（运行中是最新输出或正在做的事，完成是回复开头，失败 / 等待各有提示），完成带绿色对勾，失败红色、等待橙色，运行中有转圈和 ■ 停止按钮。多张时收拢成一张、后面露出两层卡边；点一下展开成列表，点卡片打开那个会话（主窗口到前台并切过去，已完成的卡片随即消失，因为打开即标为已读）；悬停卡片左上角 × 移除（完成 / 失败的同时标为已读，运行中的只暂时隐藏到状态变化）；鼠标离开展开的列表 1.5 秒后收回。**没有会话动态时一张卡片都不显示**，窗口那片区域也不拦截点击；只在宠物出现时显示约 6 秒的招呼卡片，断线时显示「连接已中断」。数据来自 `/api/desktop-office` 的 `activities`（见 daemon-api），完成未读与侧栏未读点同源。
+- **会话卡片（复刻 Codex Mini）**：每个正在运行、等你处理、失败或完成后还没看过的主会话一张卡片，跨工作区，按最近发消息时间排序：加粗标题 + 一行内容，字体、字号、行高与 ACECode 对话正文完全一致（主页面每次推送快照都带上当前的 `--font-sans` 和 `--ace-font-size-13`，跟随设置里的小 / 中 / 大字号，默认 14px、行高 1.6；宠物缩小到窗口放不下时卡片按需等比缩小，最小 9px，仍放不下就贴住窗口顶边，整张卡片始终留在窗口里——曾经保持原字号，窗口宽度低于约 280 时卡片顶端被切掉；标题和内容过长时在停止按钮前省略）（运行中是最新输出或正在做的事，完成是回复开头，失败 / 等待各有提示），完成带绿色对勾，失败红色、等待橙色，运行中有转圈和 ■ 停止按钮。多张时收拢成一张、后面露出两层卡边；点一下展开成列表，点卡片打开那个会话（主窗口到前台并切过去，已完成的卡片随即消失，因为打开即标为已读）；悬停卡片左上角 × 移除（完成 / 失败的同时标为已读，运行中的只暂时隐藏到状态变化）；鼠标离开展开的列表 1.5 秒后收回。**没有会话动态时一张卡片都不显示**，窗口那片区域也不拦截点击；只在宠物出现时显示约 6 秒的招呼卡片，断线时显示「连接已中断」。数据来自 `/api/desktop-office` 的 `activities`（见 daemon-api），完成未读与侧栏未读点同源。
 - **出场**：先打招呼（回形针 Greeting、rover 跑进来再打招呼、鲸鱼娘挥手），同时显示招呼卡片「你好，我是…」「双击我就能打开 ACECode」，点一下可提前收起。
 - **静止时永不静止**：循环播放闲置动作，每 7–16 秒随机插入一个预置动作（回形针玩原子、绳子、东张西望等，rover 运动、做饭、看书等，鲸鱼娘玩耍、吃东西、挥手、开心），连续两次不重复。鲸鱼娘和 rover 带轻微呼吸起伏；原版动作里自循环超过 1.2 秒的停顿会被跳过（回形针原版闲置会盯着一处好几秒）。空闲 5 分钟后入睡（仍有睡眠动画，rover 没有睡眠动作），任何交互或状态变化都会唤醒。
 - **心情跟随卡片**：有会话等你处理时提醒一次再循环等待动作；否则有会话在跑就做最新那个会话对应的工作动作（思考 / 撰写 / 调用工具 / 压缩 / 重试，同类阶段切换时等当前动作自然收尾）；新出现完成卡片时庆祝几遍、新出现失败卡片时做失败动作，然后回到闲置。宠物刚出现时已有的完成卡片不会再庆祝一次。
 - **悬停**：鼠标移到宠物身上跳一下（Codex jumping，3 秒内不重复），悬停期间整个宠物框可点，避免跳动改变轮廓导致悬停闪烁。
 - **单击**：做一个回应动作（回形针挥手、rover 被点、鲸鱼娘挥手）；双击的第二下不会重复回应。
 - **双击**：陪伴宠物双击把 ACECode 主窗口叫到前台（Codex Mini 也是直接打开主窗口），具体会话从卡片打开。虚拟办公室双击选中的人物打开其会话，双击空地打开当前会话，没有会话时也把主窗口叫到前台。Windows 由宠物窗口短暂挂接前台线程输入队列后激活主窗口（点击落在 WebView2 浏览器进程的子窗口里，本进程不一定有前台权限），macOS 走与通知点击相同的 `mac_bring_window_foreground`。
-- **趴边偷看（只有鲸鱼娘）**：拖到屏幕左 / 右边缘附近松手（窗口中心离边缘不超过窗口宽度的 1/4，约等于身体碰到屏幕边），窗口贴到那条边，鲸鱼娘换成从屏幕边探出半个头、双手扒着边偷看的样子（贴左边时镜像）：缓慢地探进探出，每 2–5 秒眨一次眼、偶尔连眨两下；悬停时探得更靠里并开心地眯眼，有会话等你处理时也会多探出来一点，新完成的会话让她开心眯眼、失败时抖一下；双击照常打开 ACECode，再拖起来就恢复全身。缩放和恢复默认大小时保持贴边，「回到右下角」取消吸附。画面是用 Codex 按鲸鱼娘原有帧的画风画的两帧（睁眼 / 闭眼），来源与处理见 `assets/desktop_pet/whale/README.md`。偷看原画比精灵帧大约 1.8 倍（眼睛高度、发箍到嘴的距离都量过），按常规帧缩放 ÷ 1.8 绘制，头和站着时一样大；曾经固定画成 170 像素高，头大了将近一倍。吸附判定与贴边位置是 `desktop_pet_layout` 里的纯函数（`desktop_pet_dock_side` / `dock_desktop_pet`），原生在拖动结束时判定并发 `{type:'pet-dock', side:'left'|'right'|''}`。
+- **趴边偷看（三只陪伴宠物都有）**：拖到屏幕左 / 右边缘附近松手（窗口中心离边缘不超过窗口宽度的 1/4，约等于身体碰到屏幕边），窗口贴到那条边，宠物换成从屏幕边探出半个身子偷看的样子（贴左边时镜像）：鲸鱼娘双手扒着边，回形针把上半截钢丝和两只大眼睛探进来，rover 探出脑袋、两只前爪扒着边。缓慢地探进探出，每 2–5 秒眨一次眼、偶尔连眨两下；悬停时探得更靠里并开心地眯眼，有会话等你处理时也会多探出来一点，新完成的会话让它开心眯眼、失败时抖一下；双击照常打开 ACECode，再拖起来就恢复全身。缩放和恢复默认大小时保持贴边，「回到右下角」取消吸附；贴着边在右键菜单里换宠物，新宠物接着从同一条边偷看（页面记住窗口所在的边，素材还在解码时收到的贴边消息也不会丢）。画面都是用 Codex 按各自原有帧的画风画的两帧（睁眼 / 闭眼），来源与处理见 `assets/desktop_pet/whale/README.md` 与 `assets/desktop_pet/classic/README.md`。头的大小与其它姿势一致：鲸鱼娘的偷看原画比精灵帧大约 1.8 倍（眼睛高度、发箍到嘴的距离都量过），按常规帧缩放 ÷ 1.8 平滑绘制，曾经固定画成 170 像素高、头大了将近一倍；回形针与 rover 的偷看图直接做成精灵分辨率（眼睛大小与原帧一致），和原帧一样不平滑放大，像素颗粒一致。每只宠物藏在屏幕外的宽度（鲸鱼娘 9、像素宠物 4 个画布像素）与是否平滑在 `classic_pet.js` 的 `PEEK` 表，探进探出的幅度按藏边宽度缩放，不会顶到上限停住。吸附判定与贴边位置是 `desktop_pet_layout` 里的纯函数（`desktop_pet_has_edge_peek` / `desktop_pet_dock_side` / `dock_desktop_pet`），原生在拖动结束时判定并发 `{type:'pet-dock', side:'left'|'right'|''}`。
 - **拖动**：原生拖动循环按窗口横向位移向页面发 `{type:'pet-drag', phase:'start'|'move'|'end', direction}`（`DesktopPetDragTracker` 累计 4 像素才报方向）。鲸鱼娘整个拖动过程都是被一只手拎起来的姿势（drag 帧）并以手为支点轻轻摆动；回形针朝拖动方向看；rover 先吃惊再朝拖动方向看，停住 0.45 秒转回正面。松开后继续原来的状态。松手时没有吸附，窗口又有一部分在屏幕外，就整窗收回工作区（`keep_desktop_pet_in_work_area`，所有宠物都适用）。吸附要窗口伸出屏幕约 1/4 宽，只是蹭到边上松手，正好会停在半出屏的位置，头顶的会话卡片会被屏幕边截掉。
 
 虚拟办公室继续显示主/子 Agent 的完整协作场景。单会话有一个主角色 Maestro，多 agent 任务按真实子会话入座；无需启动额外模型，也没有演示任务循环。美术与拖动缩放来自原有 Claude 桌宠，旧的 `design-prototypes/agent-office` 事务所原型已移除。
@@ -37,7 +37,7 @@ Windows 与 macOS Desktop 可开启透明桌面宠物，默认关闭。设置 
 - 子 agent 出现时门先打开，人从门槛淡入走进来，先到派活的人桌前领「任务」信封再回工位，坐下后跳一跳、冒星星、说「报到！」；完成后走到派活的人桌前递「回报」信封（派活的人显示「收到…的结果」），说「再见」后快步出门、在门槛淡出；失败或停止的成员直接道别出门。网状协作中 agent 间消息以带「消息 / 新任务 / 回报」标签的信封在工位间飞过。系统开启「减少动态效果」时不走路，交接信封、「报到！」和原地「再见」仍然显示。
 - 等待授权、等待回答、重试、压缩、失败和取消有各自状态。超过七个子角色时点击 `+N` 查看成员并打开对应会话；列表随状态更新，Escape 收起。选中房间人物后双击可打开其会话；双击空地打开当前会话，没有会话时也会把 ACECode 主窗口叫到前台。
 - 文件堆随当前上下文占用增长，压缩后依据实际新统计变薄。工具符号与聊天工具行共用 SVG 来源。
-- 拖动房间空地移动窗口；滚轮、右下角把手和右键菜单可缩放。窗口不抢主界面焦点，透明角落可穿透点击；尺寸按原实现保存。
+- 拖动房间空地移动窗口；滚轮、房间左上角的缩放三角形和右键菜单可缩放（陪伴宠物的三角形贴在宠物可见轮廓的左上角，随动作和贴边移动，经 overlay 的 `grip` 上报给原生命中）。三角形平时隐藏，鼠标移到它上面才显示，隐藏时照样能拖。窗口不抢主界面焦点，透明角落可穿透点击；尺寸按原实现保存。
 
 ## 构建与数据流
 
@@ -65,4 +65,4 @@ Windows/macOS 共用 `desktop_office_service.hpp` 管理偏好、桥和可重建
 
 ## 四种宠物的验证
 
-`node web/scripts/test-classic-desktop-pets.mjs` 覆盖三种新增宠物的离线解码、出场招呼、鲸鱼娘全部 15 套动作、工作 / 等待 / 失败 / 成功状态、闲置动画最长静止时长、随机预置动作、悬停跳动、单击回应、双击打开会话或仅激活主窗口、拖动左右方向、入睡与唤醒、开启减少动态效果时照样动、会话卡片（无会话不占位、收拢 / 展开 / 打开 / 停止 / 移除）、没有工具条、右键菜单和多尺寸布局；`ACE_OFFICE_HOST=mac` 用 macOS 桥垫片跑同一套。`test-desktop-office.mjs` 额外覆盖办公室空地双击。`node web/scripts/test-virtual-office-preferences.mjs` 覆盖四种选择与原有开关、邀请、订阅释放流程。Windows 上的 macOS 桥测试不等于 Mac 原生窗口实机验收。
+`node web/scripts/test-classic-desktop-pets.mjs` 覆盖三种新增宠物的离线解码、出场招呼、鲸鱼娘全部 15 套动作、三只宠物的趴边偷看（左右两边、眨眼、悬停、拿起、贴边换宠物）、缩小后卡片完整显示与缩放三角形只在悬停时出现、工作 / 等待 / 失败 / 成功状态、闲置动画最长静止时长、随机预置动作、悬停跳动、单击回应、双击打开会话或仅激活主窗口、拖动左右方向、入睡与唤醒、开启减少动态效果时照样动、会话卡片（无会话不占位、收拢 / 展开 / 打开 / 停止 / 移除）、没有工具条、右键菜单和多尺寸布局；`ACE_OFFICE_HOST=mac` 用 macOS 桥垫片跑同一套。`test-desktop-office.mjs` 额外覆盖办公室空地双击。`node web/scripts/test-virtual-office-preferences.mjs` 覆盖四种选择与原有开关、邀请、订阅释放流程。Windows 上的 macOS 桥测试不等于 Mac 原生窗口实机验收。
diff --git a/docs/runtime_file_naming.md b/docs/runtime_file_naming.md
new file mode 100644
index 000000000..72f7a32ad
--- /dev/null
+++ b/docs/runtime_file_naming.md
@@ -0,0 +1,30 @@
+# 运行数据命名
+
+ACECode 自动生成的运行数据名称使用下划线 `_` 分隔。此规则包括会话 ID、日期日志、升级诊断、反馈包、导出建议名、工具输出、粘贴附件、截图及临时备份。
+
+| 类型 | 新生成名称示例 | 旧数据兼容 |
+| --- | --- | --- |
+| 会话 | `20261016_153000_abcd.jsonl`、同 ID 的 `.meta.json` | 原 ID 和文件原名继续读取、恢复、追加；不改写引用 |
+| 运行日志 | `desktop_2026_10_16.log`、`tui_input_trace_2026_10_16.log` | 反馈收集同时识别连字符日志与下划线日志，按修改时间选择 |
+| 升级日志 | `upgrade_2026_10_16_123.log` | 最近升级日志收集支持两种名称 |
+| 反馈包 | `acecode_feedback_<session>_<timestamp>_<platform>.zip` | 内部会话 ID 元数据仍保留原值 |
+| 工具与截图 | `bash_<id>.txt`、`mcp_image_0.png`、`simulator_<device>_<timestamp>.jpg` | 历史消息里存储的路径直接按记录读取 |
+| 粘贴文本 | `pasted_text_20261016_153000_2.txt` | 旧附件名称、附件 ID 和来源元数据继续识别 |
+| 导出 | `acecode_audit_<timestamp>.csv`、`mermaid_flowchart.svg` | 用户最终选择的保存路径不作重写 |
+| 配置备份 | `config_backups/last_good/config.json` | 已有 `config-backups/last-good/` 继续使用，不创建空替代存储 |
+| 固定运行文件 | `desktop_managed.json`、`agent_browser.json`、`tool_rewrites.json`、`data_dir.redirect.json` | 已有旧路径继续读写 |
+| 定时数据 | `scheduled_loops.sqlite3` | 已有 `scheduled-loops.sqlite3` 继续使用原数据库 |
+| 开发运行目录 | `.acecode/dev_run/<worktree>_<commit>/` | 旧目录仍可复用；清理仍要求确认 PID 已死亡 |
+
+## 兼容边界
+
+- 不批量重命名旧数据。持久化路径仅在没有旧资源时创建下划线名称；新旧固定资源同时存在时优先旧资源，避免升级意外打开一份空数据。
+- 会话的新旧 ID 作为不同身份原样处理，不把连字符替换后的字符串当作旧 ID 的别名。旧 PID 后缀实验文件仍不进入正常列表。
+- ISO 时间文本、标准 UUID、API 路由、已发布包名、Git 分支名及主题包等既定协议格式保持其约定。SQLite 自身的 `-wal`、`-shm` 后缀由 SQLite 管理。
+- 跨版本进程共用的单实例锁和系统命名管道保留原有协调名称，避免旧新版进程各自取得不同的锁。已有种子资源或用户文件的复制保留原名。
+- 本次只调整自动生成的运行数据。用户明确输入的文件路径、导入文件名、会话显示标题，以及 AI 自主创建的工程文件不作强制改写。
+- 新版支持读取旧数据；旧版是否支持新版新增数据由旧版实现决定。
+
+## 实现入口
+
+`src/base/utils/generated_file_names.hpp` 提供新名称转换及旧路径选择。会话生成由 `SessionStorage::generate_session_id()` 负责；日志写入与反馈发现分别在 Logger / 输入追踪、feedback 模块内维护。FTXUI 输入追踪名称由 overlay port 固化，并提升 port version，确保重建依赖时使用一致命名。
diff --git a/docs/subagents.md b/docs/subagents.md
index 8fb1e6dc9..ab150ad02 100644
--- a/docs/subagents.md
+++ b/docs/subagents.md
@@ -5,6 +5,23 @@
 Multi-Agent V2,openspec `add-mesh-swarm-mode`)。
 对应提交:`dd10b15`(工具内核,daemon)→ `2c20b5b`(Web 后台任务面板 + parent 持久化)→ `35b986f`(TUI 支持)。
 
+## 采样参数
+
+`spawn_subagent` 和网状蜂群的 `agent_spawn` 都接受可选 `sampling`：
+
+```json
+{"sampling":{"temperature":0.3,"top_p":0.95,"top_k":20,"min_p":0}}
+```
+
+四个字段分别覆盖，优先级为：本次发起参数 > 所选专家（成员）预设 > 模型设置。
+未传、`null` 或 `{}` 表示不增加覆盖；字段为 `null` 也表示继承。数值 `0` 不等于空值。
+普通子任务不额外继承父会话的显式采样覆盖，`fork_turns` 只控制历史继承。
+显式覆盖保存到子会话 metadata，恢复、模型重载和后续模型切换时继续使用。
+
+专家编辑器的“采样参数”可保存这些预设。团队设置提供默认值，被引用专家的预设优先；
+子任务仍可逐字段覆盖。旧专家包无需迁移。不受支持的 provider/protocol、错误类型和越界值
+会在启动前报错；例如 Responses 协议不接受 `top_k`、`min_p`。
+
 ## 1. 设计概览
 
 参照 Claude Code 的 Task 工具语义,落在 ACECode 自己的多会话基建上:
diff --git a/docs/user-manual.md b/docs/user-manual.md
index f2729ddbe..8aaa5f390 100644
--- a/docs/user-manual.md
+++ b/docs/user-manual.md
@@ -749,7 +749,7 @@ acecode 启动时按 transport 连接每个配置的 MCP 服务器：
 [MCP] Connected 2 server(s), registered 8 external tool(s).
 ```
 
-若某个服务器连接失败，可在 `<数据目录>/logs/tui-YYYY-MM-DD.log` 中查看详细错误信息（默认数据目录为 `~/.acecode`）。
+若某个服务器连接失败，可在 `<数据目录>/logs/tui_YYYY_MM_DD.log` 中查看详细错误信息（默认数据目录为 `~/.acecode`）。
 
 ### 管理 MCP 连接
 
@@ -886,13 +886,13 @@ OpenAI 兼容网关或 Anthropic 模型如果推理时间很长、连接容易
 ### Q: 日志文件在哪里？
 
 普通 TUI 运行时会按本地日期滚动写入
-`<数据目录>/logs/tui-YYYY-MM-DD.log`，记录详细的调试信息。默认数据目录为
+`<数据目录>/logs/tui_YYYY_MM_DD.log`，记录详细的调试信息。默认数据目录为
 `~/.acecode`；若已配置数据目录重定向，则使用重定向后的目录。已有工作区中的
 `acecode.log` 会被保留，但新的 TUI 不再创建或追加该文件。启用 TUI 输入追踪的
 调试构建会将高频鼠标和选区记录另写到
-`<数据目录>/logs/tui-input-trace-YYYY-MM-DD.log`，同样不会写入工作区。
+`<数据目录>/logs/tui_input_trace_YYYY_MM_DD.log`，同样不会写入工作区。
 
-Daemon 模式按日期滚动写到 `<数据目录>/logs/daemon-YYYY-MM-DD.log`（详见第 16 章）。
+Daemon 模式按日期滚动写到 `<数据目录>/logs/daemon_YYYY_MM_DD.log`（详见第 16 章）。
 
 ---
 
diff --git a/openspec/changes/add-agent-sampling-overrides/.openspec.yaml b/openspec/changes/add-agent-sampling-overrides/.openspec.yaml
new file mode 100644
index 000000000..0cb476561
--- /dev/null
+++ b/openspec/changes/add-agent-sampling-overrides/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-16
diff --git a/openspec/changes/add-agent-sampling-overrides/design.md b/openspec/changes/add-agent-sampling-overrides/design.md
new file mode 100644
index 000000000..3427fef8a
--- /dev/null
+++ b/openspec/changes/add-agent-sampling-overrides/design.md
@@ -0,0 +1,29 @@
+## Context
+
+现有 ModelSamplingOptions 和 provider 请求构造已支持四种采样字段。两种子 agent 工具均通过 SessionRegistry 创建会话；专家团引用单专家，旧格式也支持包内 Agent。SessionModelBinding 在模型构造后重新解析配置，单改首次构造会丢失覆盖值。当前专家解绑只清元数据，已加载角色状态按现有生命周期保留。
+
+## Goals / Non-Goals
+
+**Goals:** 复用采样值类型、范围校验、协议校验和 provider factory。覆盖值只能修改会话局部 profile 副本，并随 session metadata 保存。
+
+**Non-Goals:** 不新增模型参数种类、推理强度配置、全局默认值或第二套专家执行引擎；不改既有解绑契约。
+
+## Decisions
+
+1. 在 saved_models 辅助层提供字段合并与严格覆盖解析。旧 saved_models 的未知键兼容规则不变，新的工具/专家入口拒绝拼错字段。null 字段代表未覆盖。
+2. ExpertDefinition 与包内 ExpertAgent 保存 sampling；所选 Agent 的值覆盖包级默认。引用成员投影其自身有效预设。专家 CRUD 使用 presence 标记，省略保留、null/{} 清除；单专家详情展示有效预设，显式编辑会一并替换其 lead 的包内覆盖，防止隐藏值抵消表单修改。团队编辑仅修改团队默认。编辑器始终明确提交当前值。
+3. SessionOptions/SessionMeta/SessionManager 保存 `sampling` 显式覆盖，SessionEntry 保留合并后的会话覆盖快照，所有模型 resolver 均应用快照后验证支持。先解析专家再创建 provider，避免发起时覆盖被 revalidation 丢弃。恢复时使用持久化覆盖和当前专家预设。
+4. 专家切换在原控制边界、model_control_mu 下构造并发布对应 provider；元数据写入失败恢复旧 provider。采样字段不直接修改共享 provider，进行中的请求继续持有原快照。
+5. 两个 spawn 工具始终暴露 sampling，蜂群已有 model/reasoning 开关只控制既有字段。省略 sampling 使用所选专家/模型默认，不额外复制父会话的显式覆盖；历史 fork 与采样覆盖独立。
+6. 专家编辑器沿用现有基本信息区样式，以可选数字输入表示继承。协议校验在执行时按实际选用模型进行；编辑器与保存 API 验证通用范围。
+7. 遵守 R12 文件行数上限：专家定义选择方法移入 `expert_definition.cpp`，会话模型元数据方法移入 `session_manager_model.cpp`，共享模型快照和覆盖解析移入 `session_model_resolution.cpp`。保留原接口与锁序，不提高体积基线。
+
+## Risks / Trade-offs
+
+- 专家预设可能无法用于某些模型协议 → 在创建与切换前明确拒绝，不静默丢弃。
+- 遗留无可解析模型、仅借用 provider 的嵌入路径无法安全重建 provider → 未配置覆盖保持现状，显式配置则失败说明原因。
+- 采样修改与模型热重载并发 → 复用 model_control_mu 与不可变 resolver 捕获，保留已有锁序和快照生命周期。
+
+## Migration Plan
+
+缺少 sampling 的旧专家包、会话与调用无需迁移。回滚程序会忽略新增元数据和专家字段。验证包括专家 CRUD、参数合并/拒绝、两种派生入口、恢复与重载、Web 全量测试/构建及 Windows 定向原生测试。
diff --git a/openspec/changes/add-agent-sampling-overrides/proposal.md b/openspec/changes/add-agent-sampling-overrides/proposal.md
new file mode 100644
index 000000000..0b446d267
--- /dev/null
+++ b/openspec/changes/add-agent-sampling-overrides/proposal.md
@@ -0,0 +1,23 @@
+## Why
+
+采样参数目前只能保存在模型配置中，普通子 agent、蜂群子 agent 与专家预设无法按任务选择不同的采样方式。专家复用子会话执行机制，需要共享同一套参数校验、优先级与生命周期处理。
+
+## What Changes
+
+- 为 `spawn_subagent` 和 `agent_spawn` 增加可选 `sampling` 对象，支持现有 `temperature`、`top_p`、`top_k`、`min_p`。
+- 专家包、管理 API 与专家编辑器支持保存、回填、清除采样预设；专家团复用成员的预设。
+- 按字段合并模型默认值、所选专家预设、本次发起覆盖值，参数仅作用于目标会话。
+- 会话持久化显式覆盖值；创建、恢复、模型切换、热重载与专家切换使用相同规则，并校验实际 provider/protocol 支持。
+
+## Capabilities
+
+### New Capabilities
+- `agent-sampling-overrides`: 子 agent 发起与专家预设共享的采样配置及生命周期。
+
+### Modified Capabilities
+
+无。现有会话模型选择的隔离与失败回滚要求继续适用。
+
+## Impact
+
+涉及配置采样辅助函数、ExpertRegistry、SessionOptions/SessionManager/SessionStorage、SessionRegistry、两种派生工具、专家编辑器和 expert-manager 包格式文档。复用现有 provider 请求构造，不增加依赖，不修改全局已保存模型。
diff --git a/openspec/changes/add-agent-sampling-overrides/specs/agent-sampling-overrides/spec.md b/openspec/changes/add-agent-sampling-overrides/specs/agent-sampling-overrides/spec.md
new file mode 100644
index 000000000..85e96e433
--- /dev/null
+++ b/openspec/changes/add-agent-sampling-overrides/specs/agent-sampling-overrides/spec.md
@@ -0,0 +1,46 @@
+## Purpose
+
+允许用户按子任务与专家角色配置采样参数，同时复用既有模型配置与执行引擎。保证参数覆盖规则、会话恢复、错误处理及不同发起入口的一致性，使实际模型请求可靠地体现用户设置。
+
+## ADDED Requirements
+
+### Requirement: 子 agent 发起支持采样覆盖
+系统 SHALL 在 `spawn_subagent` 与 `agent_spawn` 接受可选 `sampling` 对象，支持 temperature、top_p、top_k、min_p。缺失、null 或空对象表示无额外覆盖；数值零 MUST 按参数范围保留。
+
+#### Scenario: 按字段覆盖且隔离父会话
+- **WHEN** 模型设置 temperature=1、top_p=0.9，发起子 agent 指定 temperature=0
+- **THEN** 子 agent 的请求使用 temperature=0、top_p=0.9
+- **THEN** 父会话、兄弟会话与已保存模型不发生变化
+
+### Requirement: 专家预设支持采样配置
+系统 SHALL 在专家包与管理 API 读写 `sampling`，并在专家编辑器提供四项可选输入和取值校验。旧客户端省略 sampling MUST 保留原预设，显式 null 或空对象 MUST 清除预设。
+
+#### Scenario: 保存回填与清除
+- **WHEN** 用户保存专家采样参数并重新打开编辑器
+- **THEN** 输入显示保存的参数；全部清空后保存则恢复继承
+
+#### Scenario: 专家团使用成员预设
+- **WHEN** 专家团主理人派遣具有采样预设的成员
+- **THEN** 成员使用自己的专家预设；团队默认值仅补充该成员未设置的字段
+
+### Requirement: 统一优先级与生命周期
+系统 SHALL 按字段使用本次发起覆盖值、所选专家预设、模型默认值的优先级，并持久化会话显式覆盖。创建、恢复、模型重载与切换 SHALL 保持该规则。专家切换 SHALL 在现有控制边界一起更新角色与采样配置，失败时保持原绑定。解绑继续遵守既有仅清元数据、不立即清除已加载角色状态的约定。
+
+#### Scenario: 恢复会话与热重载
+- **WHEN** 带有显式采样覆盖的子会话恢复，或其已保存模型配置重新加载
+- **THEN** 显式覆盖继续生效，未覆盖字段使用当前专家预设与模型值
+
+#### Scenario: 本次发起值优先于专家
+- **WHEN** 专家 temperature=0.4、top_k=20，发起子任务指定 temperature=0.8
+- **THEN** 子会话使用 temperature=0.8、top_k=20
+
+### Requirement: 拒绝无法生效的采样配置
+系统 MUST 复用模型采样范围与 provider/protocol 支持校验，对错误类型、越界值、未知采样字段及不受支持的参数返回明确错误；MUST 在子任务开始前拒绝无效配置，模型或专家切换失败不得改变原有效状态。
+
+#### Scenario: 协议不支持参数
+- **WHEN** 使用 Responses 协议的子会话请求 top_k
+- **THEN** 发起失败并说明不兼容原因，不向模型发送任务
+
+#### Scenario: 参数类型错误
+- **WHEN** sampling 的 top_k 是小数或 temperature 是字符串
+- **THEN** 发起或专家保存失败并说明字段错误
diff --git a/openspec/changes/add-agent-sampling-overrides/tasks.md b/openspec/changes/add-agent-sampling-overrides/tasks.md
new file mode 100644
index 000000000..90305f62d
--- /dev/null
+++ b/openspec/changes/add-agent-sampling-overrides/tasks.md
@@ -0,0 +1,23 @@
+## 1. 数据与专家预设
+
+- [x] 1.1 复用四项采样类型，增加字段合并与严格覆盖解析，并覆盖零值、类型及范围拒绝测试。
+- [x] 1.2 接入专家加载、引用成员投影、CRUD 与 DTO，验证保存/回填、旧客户端保留及显式清除。
+
+## 2. 子会话执行
+
+- [x] 2.1 接入会话持久化及统一模型解析，验证优先级、隔离、恢复、热重载和专家/模型切换。
+- [x] 2.2 接入 spawn_subagent 与 agent_spawn schema/解析/执行，验证合法覆盖到达 provider、错误在任务开始前返回。
+
+## 3. 界面与交付验证
+
+- [x] 3.1 增加专家采样表单及字段校验，验证真实表单保存/回填/清除、零值和窄屏布局。
+- [x] 3.2 更新子 agent、daemon API 与专家包说明，完成 Windows 定向原生测试、Web 全量测试与构建、OpenSpec strict 和差异检查。
+
+## 验证记录
+
+- Windows / MSVC / MinSizeRel 原生增量构建通过；最终相关回归组 181/181 通过，包括 9 项新增测试。结果：`build/agent_sampling_final_tests.xml`。
+- 扩展回归曾发现一项既有失败：`SessionRegistry.CreateNoWorkspaceKeepsWorkspaceHashEmpty` 仍断言目录名 `no-workspace`，当前工作区在本任务之前已有的 `compatible_generated_path` 改动返回 `no_workspace`。保留该命名改动与原测试，本任务最终回归仅排除此项；原始失败记录为 `build/agent_sampling_regression.xml`。
+- `pnpm test`、`pnpm build` 通过；专家管理脚本新增 2 项采样测试与既有 6 项头像测试通过。
+- 真实浏览器组件验证通过：四参数保存、零值、回填、清除继承、非法 Top K 阻止保存、亮色桌面及暗色窄屏无溢出。执行入口：`web/scripts/test-expert-sampling.mjs`，API 使用测试夹具。
+- OpenSpec strict、分层检查、所有权检查、界面机械检查和 `git diff --check` 通过。新增文件以 intent-to-add 纳入差异审查，未提交或推送。
+- 未重启或替换用户正在使用的桌面程序；浏览器与源码测试不代表已安装 Desktop 已加载新代码。
diff --git a/openspec/changes/add-computer-use-tools/.openspec.yaml b/openspec/changes/add-computer-use-tools/.openspec.yaml
new file mode 100644
index 000000000..f05b045c8
--- /dev/null
+++ b/openspec/changes/add-computer-use-tools/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-27
diff --git a/openspec/changes/add-computer-use-tools/design.md b/openspec/changes/add-computer-use-tools/design.md
new file mode 100644
index 000000000..a37ef7eb7
--- /dev/null
+++ b/openspec/changes/add-computer-use-tools/design.md
@@ -0,0 +1,219 @@
+## Context
+
+ACECode's tool boundary already carries everything an OS-level operator needs.
+`ToolResult::attachments` accepts a `{name, mime_type, path}` descriptor;
+`AgentLoop::materialize_result_attachments` turns it into a session attachment,
+`output_attachments_to_content_parts` turns that into content parts, and the
+provider layer emits an `image_url` part for vision-capable models. This is the
+exact path `browser_screenshot` uses today, so a desktop capture needs no new
+transport.
+
+What is missing is entirely below that boundary. No source file in the
+repository calls `SendInput`, `XTestFakeButtonEvent`, `CGEventPost`, `BitBlt`,
+or any equivalent. `agent_browser` synthesizes input through the CDP `Input`
+domain, which cannot leave the page.
+
+UI-TARS-desktop (Apache-2.0) is the reference for the missing layer. Its
+`BaseOperator` is two methods, `screenshot()` and `execute(action)`, and its
+`nut-js` operator is roughly 325 lines that are mostly a key-name map. The parts
+worth taking are the action vocabulary, the physical-to-logical downsample
+before the image reaches the model, and the resize-factor arithmetic in
+`action-parser`. The parts worth refusing are the `Thought:/Action:` DSL, the
+regex action parser, and the separate `GUIAgent` loop, all of which exist to
+serve a model family trained on that specific text format.
+
+Two ACECode invariants constrain the design more than the platform work does.
+Permission decisions are per tool call, but a GUI task is tens of calls. And the
+prompt-cache prefix invariant recorded in `CLAUDE.md` means any retroactive edit
+to already-sent conversation content invalidates the cache from that point to
+the end of the turn.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Expose screen capture and synthetic pointer/keyboard control as ordinary
+  built-in tools that the existing `AgentLoop` drives.
+- Keep the model's coordinate space unambiguous and independent of DPI scaling,
+  monitor layout, and capture downsampling.
+- Make the capability opt-in, revocable mid-session, and observable while it is
+  active.
+- Bound image cost per turn without rewriting conversation history.
+- Keep the backend contract narrow enough that macOS and X11 implementations are
+  additive.
+
+**Non-Goals:**
+
+- Porting the UI-TARS `Thought:/Action:` DSL, its action parser, or its
+  `GUIAgent` loop.
+- Requiring or bundling a specific vision model. Model choice stays with
+  `saved_models` and the existing `vision` capability tag.
+- macOS and Linux backends. This change lands the contract and the Windows
+  backend; the other platforms are separate follow-ups.
+- Wayland. Screen capture and input injection there require
+  `xdg-desktop-portal` plus `libei` and do not fit this contract.
+- Remote or sandboxed desktops, including the UI-TARS AIO HTTP operator.
+- Element-level semantics such as an accessibility tree. This layer is
+  deliberately pixel-only; `agent_browser` remains the semantic path for web
+  content.
+
+## Decisions
+
+### Expose plain JSON tools rather than a nested agent
+
+Each action is a normal tool with a JSON schema, so tool calls appear in the
+transcript, flow through `PermissionManager`, honor `ctx.abort_flag`, render
+through the existing TUI and web tool rows, and count toward the session's own
+token accounting. A single `gui_task(instruction)` tool that runs an inner loop
+was rejected: it would hide every intermediate step from the permission gate and
+the UI, and would spend tokens against a model the session does not track.
+
+The action set is taken from UI-TARS's vocabulary because it is small and
+proven, split so that each verb maps to one tool rather than one DSL string:
+`computer_screenshot`, `computer_click` (with `button` and `count`),
+`computer_move`, `computer_drag`, `computer_scroll`, `computer_key` (chords and
+explicit hold/release), and `computer_type`. `wait`, `finished`, and `call_user`
+are not ported; ACECode already terminates on a text-only reply, has
+`task_complete`, and has `AskUserQuestion`.
+
+Only `computer_screenshot` is registered with `is_read_only = true`. Every
+action tool is write-class so it cannot be auto-approved.
+
+### Split a narrow backend interface from platform code
+
+`ComputerBackend` declares `capture()`, `pointer_move`, `pointer_button`,
+`pointer_scroll`, `key_event`, and `type_text`, plus a `ScreenGeometry` query.
+Platform bodies live in `computer_backend_win.cpp`, and later
+`computer_backend_mac.mm` and `computer_backend_x11.cpp`, following the
+`_win` / `_mac` / `_posix` split already used by `notifications`,
+`folder_picker`, `single_instance`, and `proxy_resolver`.
+
+The Windows backend uses `SendInput` for pointer and keyboard events and a
+`BitBlt` desktop capture. DXGI Desktop Duplication is faster but requires
+device-lost handling and a redistributable code path; the capture rate here is
+one frame per model turn, so `BitBlt` is chosen for simplicity and is an
+internal detail the interface does not expose.
+
+When no backend exists for the target platform, `register_computer_use_tools`
+registers nothing, exactly as `register_agent_browser_tools` does outside
+`_WIN32 || __APPLE__`. Tools that are absent are absent from the tool list
+rather than present-and-failing, so the model never plans around a capability it
+cannot use.
+
+### Make the captured image the single coordinate space
+
+Three spaces exist: logical desktop coordinates that `SendInput` consumes,
+physical pixels that the framebuffer holds, and the pixel grid of the image the
+model actually sees after downsampling. Bugs in this area are silent — clicks
+land near, but not on, the target — so the contract is fixed explicitly.
+
+Every action tool takes `x` and `y` in **captured-image pixels of the most
+recent `computer_screenshot` in this session**, with the origin at the image's
+top-left. A pure `computer_coords` translation unit converts that to logical
+desktop coordinates using the capture's recorded scale and virtual-desktop
+origin. The capture records its geometry so a later action can be rejected when
+the screen configuration changed after the screenshot, instead of clicking a
+stale location.
+
+Capture downsamples physical pixels to logical pixels before encoding, following
+the `nut-js` operator's `pixelDensity` handling, so a HiDPI display does not
+double every coordinate. The resize-factor arithmetic in UI-TARS's
+`smartResizeForV15` is ported into the same unit: models in the Qwen-VL family
+are trained on images resized to a multiple of a fixed factor, and feeding a
+native-resolution frame degrades grounding without any error surfacing. This
+arithmetic is pure and unit-testable, and it is the piece most worth taking from
+the reference implementation.
+
+Normalized 0–1000 coordinates, which UI-TARS models emit natively, are not
+accepted. They exist to serve one model family's output format; a general tool
+contract in absolute image pixels is checkable and does not silently rescale.
+
+### Bound capture cost without rewriting history
+
+A capture is clamped to a configured maximum edge length before encoding, and a
+per-turn capture count limit rejects further screenshots with an explanatory
+result rather than a hard failure.
+
+Screenshots are deliberately **not** pruned retroactively. A sliding image
+window of the kind UI-TARS uses in `processVlmParams` is correct for a
+stateless per-request assembly, but in ACECode the same technique would mutate
+already-sent conversation content and invalidate the prompt cache from the
+mutation point through the end of every subsequent request in the turn. That
+cost grows with exactly the long tool-heavy turns this feature produces. Cost is
+therefore controlled at capture time — fewer, smaller images — and long sessions
+fall back to the existing compaction path, which is already a cache-boundary
+event.
+
+### Grant control once per session, not once per click
+
+The first action tool call in a session raises one permission decision that
+describes the capability rather than the individual click. Once granted, action
+tools in that session proceed without further prompts. The grant is stored in
+session-scoped runtime state, is never persisted, and is dropped on session end,
+on user abort, and on `/computer off`.
+
+Per-call confirmation was rejected as unusable: a short GUI task is tens of
+calls, and a prompt the user answers reflexively is not a safety control. A
+persisted grant was rejected because the blast radius — full synthetic input to
+every application the user is signed into — is larger than any other tool in the
+codebase and should not survive a restart silently.
+
+`computer_screenshot` is read-only and does not require the grant, so the model
+can look before asking to act.
+
+While a grant is active the surfaces that already show session state show that
+the session can control the machine, and the existing abort path drops the grant
+so the visible stop control is also the kill switch.
+
+### Keep the capability disabled by default
+
+`ComputerUseConfig` carries `enabled` (default `false`), plus the capture bound
+and per-turn capture limit. Registration is skipped when disabled, matching
+`config.web_search.enabled` and `config.lsp.enabled`. Unlike those, the default
+is off: an unaware user upgrading ACECode should not gain a tool that can drive
+their desktop.
+
+`/computer` reports backend availability, screen geometry, grant state, and the
+configured bounds, and revokes an active grant. It follows `/lsp` and
+`/websearch` in sharing one dispatch function across the TUI command table, the
+daemon builtin allowlist, and the web slash-command list.
+
+### Record third-party attribution
+
+The action vocabulary, the physical-to-logical capture handling, and the
+resize-factor arithmetic derive from UI-TARS-desktop, which is Apache-2.0. The
+ported arithmetic carries an attribution comment naming the upstream file, and
+the repository NOTICE records the dependency. No upstream source is vendored
+wholesale and no npm package is added; the runtime remains a self-contained C++
+binary.
+
+## Risks / Trade-offs
+
+- [Grounding quality is a model property, not a tool property] → Pixel-accurate
+  clicking is what UI-TARS's specialized models are trained for, and a general
+  vision model will misclick more often. The tools are therefore additive and
+  opt-in rather than promoted as a default workflow, and model selection stays
+  with the existing `vision` capability tag so a user who configures a
+  GUI-grounding model gets the better behavior without a code change.
+- [Full-screen captures are expensive in tokens] → Bounded capture size and a
+  per-turn limit keep a single turn's image cost predictable, at the cost of
+  detail on large displays. Region capture would help further and is left for a
+  follow-up once real usage shows which regions matter.
+- [A session-scoped grant is coarser than per-call confirmation] → It covers a
+  sequence the user cannot practically review click by click. The mitigations
+  are that the grant is never persisted, is visible while active, is dropped by
+  the existing abort control, and covers only action tools.
+- [Coordinates can go stale between capture and action] → Captures record their
+  geometry and actions are rejected when the screen configuration changed, so a
+  monitor change produces an explicit error instead of a click at a wrong
+  location. Content that moves without a geometry change is not detectable here
+  and remains the model's responsibility to re-verify by capturing again.
+- [Windows-only in this change] → Users on other platforms see no tools at all
+  rather than a broken capability. The backend interface is the only thing the
+  tools depend on, so a macOS or X11 body is additive; macOS additionally needs
+  Accessibility and Screen Recording TCC grants from a signed bundle, which is
+  the main reason it is scoped separately.
+- [Automating a signed-in desktop can trip application anti-automation rules] →
+  Synthetic input is indistinguishable from a script to the target application.
+  The capability being opt-in and non-persistent keeps this a deliberate user
+  choice rather than a default behavior.
diff --git a/openspec/changes/add-computer-use-tools/proposal.md b/openspec/changes/add-computer-use-tools/proposal.md
new file mode 100644
index 000000000..040cf05ab
--- /dev/null
+++ b/openspec/changes/add-computer-use-tools/proposal.md
@@ -0,0 +1,70 @@
+## Why
+
+ACECode can already drive a web page. `src/tool/agent_browser/` registers
+fifteen CDP-backed tools that navigate, read a semantic accessibility snapshot,
+click by element reference, and capture a PNG that reaches the model through
+`ToolResult::attachments`. Everything outside a Chromium page is unreachable:
+the repository contains no screen capture and no synthetic input path on any
+platform, so an agent cannot operate a native installer, a desktop IDE, a
+settings dialog, or any application that is not a browser.
+
+The GUI-agent stacks that do solve this — `bytedance/UI-TARS-desktop` being the
+most complete open one — converge on a very small operator contract: capture the
+screen, execute one pointer or keyboard action, repeat. Their value is not the
+surrounding machinery. UI-TARS wraps that contract in its own agent loop, its
+own `Thought:/Action:` text DSL, its own parser, and a model family trained to
+emit that DSL. ACECode already owns an agent loop, a tool protocol, permission
+gating, abort propagation, and an image-to-context pipeline, so adopting the
+wrapper would mean running a second opaque agent inside a tool call.
+
+This change takes the operator contract and the coordinate handling that make
+those stacks work, and exposes them as ordinary ACECode tools driven by the
+existing `AgentLoop` and any vision-capable configured model.
+
+## What Changes
+
+- Add a `ComputerBackend` abstraction under `src/tool/computer_use/` that
+  captures the screen and executes single pointer/keyboard actions, with a
+  Windows implementation.
+- Register a built-in tool group — `computer_screenshot`, `computer_click`,
+  `computer_move`, `computer_drag`, `computer_scroll`, `computer_key`, and
+  `computer_type` — using ordinary JSON arguments and the existing
+  `ToolResult::attachments` path for captures.
+- Gate the whole group behind a new `config.computer_use` section that is
+  disabled by default, and skip registration entirely on platforms without a
+  backend, mirroring how `agent_browser` and `lsp` are gated.
+- Add a pure coordinate layer that converts between captured-image pixels,
+  physical screen pixels, and logical desktop coordinates so DPI scaling and
+  multi-monitor origins do not silently misplace clicks.
+- Add a session-scoped control grant: the first action tool in a session raises
+  one permission decision that covers the sequence, rather than one decision per
+  click, and the grant is revoked on session end, abort, or `/computer off`.
+- Add a capture budget that bounds screenshot pixel dimensions and per-turn
+  capture count without retroactively rewriting earlier conversation content.
+- Add a `/computer` command that reports backend availability, grant state, and
+  screen geometry, and revokes an active grant.
+
+## Capabilities
+
+### New Capabilities
+
+- `computer-use-tools`: Defines OS-level screen capture and synthetic pointer
+  and keyboard control as gated built-in tools, including the coordinate
+  contract, the session-scoped control grant, and the capture budget.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+- New `src/tool/computer_use/` sources and the built-in registration chain in
+  `src/tool/builtin_tool_registry.hpp`.
+- `AppConfig` gains a `computer_use` section; `config.json` schema notes and
+  documentation follow.
+- Command registration for `/computer` in both the TUI builtin command table and
+  the daemon builtin allowlist.
+- Windows link surface gains `User32`/`Gdi32` usage for input and capture.
+- Focused unit tests for the pure coordinate, budget, and grant-state logic, and
+  a gated manual smoke path for the native backend.
+- `README.md`, `README_CN.md`, and the repository capability notes.
diff --git a/openspec/changes/add-computer-use-tools/specs/computer-use-tools/spec.md b/openspec/changes/add-computer-use-tools/specs/computer-use-tools/spec.md
new file mode 100644
index 000000000..ad70599f8
--- /dev/null
+++ b/openspec/changes/add-computer-use-tools/specs/computer-use-tools/spec.md
@@ -0,0 +1,221 @@
+## ADDED Requirements
+
+### Requirement: Computer use capability gate
+
+ACECode SHALL register the computer use tool group only when
+`config.computer_use.enabled` is true and a screen backend exists for the
+running platform. The setting SHALL default to false.
+
+#### Scenario: Capability disabled by default
+
+- **WHEN** a configuration without a `computer_use` section is loaded
+- **THEN** no computer use tool is registered
+- **AND** the model's tool list contains no screen capture or synthetic input
+  capability
+
+#### Scenario: Capability enabled on a supported platform
+
+- **WHEN** `config.computer_use.enabled` is true and the platform has a backend
+- **THEN** `computer_screenshot`, `computer_click`, `computer_move`,
+  `computer_drag`, `computer_scroll`, `computer_key`, and `computer_type` are
+  registered
+
+#### Scenario: Unsupported platform
+
+- **WHEN** `config.computer_use.enabled` is true and the platform has no backend
+- **THEN** no computer use tool is registered
+- **AND** startup succeeds without an error
+
+### Requirement: Screen capture as a model-visible attachment
+
+ACECode SHALL provide `computer_screenshot`, which captures the current screen
+and returns it as a PNG attachment through the tool result attachment path so
+vision-capable models receive it as image content. The tool SHALL be read-only.
+
+#### Scenario: Capture reaches the model as an image
+
+- **WHEN** the model calls `computer_screenshot` in a session using a
+  vision-capable model
+- **THEN** the result carries a PNG attachment
+- **AND** the attachment is materialized into the session and sent to the
+  provider as image content
+
+#### Scenario: Capture reports its coordinate geometry
+
+- **WHEN** a capture succeeds
+- **THEN** the result reports the captured image's pixel width and height and
+  the screen geometry the capture was taken against
+
+#### Scenario: Capture requires no control grant
+
+- **WHEN** no control grant is active in the session
+- **THEN** `computer_screenshot` still executes because it is read-only
+
+### Requirement: Captured-image pixel coordinate contract
+
+ACECode SHALL interpret the `x` and `y` arguments of every computer use action
+tool as pixel coordinates in the most recent capture of the current session,
+with the origin at the captured image's top-left corner, and SHALL translate
+them to logical desktop coordinates before dispatching input.
+
+#### Scenario: Coordinates translate across display scaling
+
+- **WHEN** a capture is downsampled from physical to logical pixels on a scaled
+  display and the model targets a point in that image
+- **THEN** the dispatched pointer event lands at the corresponding logical
+  desktop position rather than at the raw image coordinate
+
+#### Scenario: Multi-monitor origin is applied
+
+- **WHEN** the captured virtual desktop begins at a non-zero origin
+- **THEN** the capture origin is applied during translation so a point in the
+  image maps to the same point on the physical desktop
+
+#### Scenario: Action before any capture
+
+- **WHEN** an action tool with coordinates is called before any capture in the
+  session
+- **THEN** the call fails with a result directing the model to capture first
+- **AND** no input event is dispatched
+
+#### Scenario: Screen geometry changed since capture
+
+- **WHEN** the screen configuration changed after the most recent capture
+- **THEN** a coordinate-bearing action fails with an explicit staleness error
+  directing the model to capture again
+- **AND** no input event is dispatched
+
+#### Scenario: Coordinates outside the captured image
+
+- **WHEN** an action targets a coordinate outside the captured image bounds
+- **THEN** the call fails
+- **AND** no input event is dispatched
+
+### Requirement: Session-scoped control grant
+
+ACECode SHALL require a session-scoped control grant before executing any
+computer use action tool. The first such call in a session SHALL raise one
+permission decision covering the capability. The grant SHALL NOT be persisted
+and SHALL be dropped on session end, on user abort, and on explicit revocation.
+
+#### Scenario: First action requests the grant
+
+- **WHEN** the model calls an action tool in a session with no active grant
+- **THEN** ACECode raises a permission decision describing desktop control
+- **AND** the action executes only after approval
+
+#### Scenario: Subsequent actions reuse the grant
+
+- **WHEN** a grant is active in the session
+- **THEN** further action tools execute without an additional permission prompt
+
+#### Scenario: Denied grant blocks the action
+
+- **WHEN** the user denies the control grant
+- **THEN** the action fails with a result explaining that desktop control was
+  denied
+- **AND** no input event is dispatched
+- **AND** no grant is recorded
+
+#### Scenario: Abort drops the grant
+
+- **WHEN** the user aborts the running turn while a grant is active
+- **THEN** the grant is dropped
+- **AND** the next action tool call raises a new permission decision
+
+#### Scenario: Grant does not survive the session
+
+- **WHEN** a session with an active grant ends and a new session starts
+- **THEN** the new session has no grant
+- **AND** its first action tool call raises a permission decision
+
+### Requirement: Synthetic pointer and keyboard actions
+
+ACECode SHALL provide pointer and keyboard action tools that dispatch synthetic
+input through the platform backend: `computer_click` with button and repeat
+count, `computer_move`, `computer_drag` between two points, `computer_scroll`
+with a direction and amount, `computer_key` for named keys and chords including
+explicit hold and release, and `computer_type` for literal text.
+
+#### Scenario: Click dispatches at a translated position
+
+- **WHEN** `computer_click` is called with in-bounds coordinates and an active
+  grant
+- **THEN** a pointer button event is dispatched at the translated logical
+  position
+- **AND** the result reports the action and the position used
+
+#### Scenario: Key chord dispatches modifiers around the main key
+
+- **WHEN** `computer_key` is called with a modifier chord
+- **THEN** modifiers are pressed before and released after the main key
+
+#### Scenario: Held keys are released
+
+- **WHEN** `computer_key` holds a key without a matching release and the turn
+  ends or is aborted
+- **THEN** the backend releases keys it is holding so no modifier is left stuck
+
+#### Scenario: Abort stops a running action
+
+- **WHEN** the session abort flag is set while an action tool is executing
+- **THEN** the tool returns promptly without dispatching further input
+
+#### Scenario: Unknown key name
+
+- **WHEN** `computer_key` is called with a key name the backend does not know
+- **THEN** the call fails with a result naming the unknown key
+- **AND** no input event is dispatched
+
+### Requirement: Capture budget without history rewriting
+
+ACECode SHALL bound captured image dimensions to the configured maximum edge
+length and SHALL bound the number of captures per turn. ACECode SHALL NOT remove
+or downgrade image content already present in earlier conversation messages.
+
+#### Scenario: Oversized capture is downscaled
+
+- **WHEN** the screen exceeds the configured maximum edge length
+- **THEN** the capture is downscaled before encoding
+- **AND** the reported image dimensions match the delivered image so coordinate
+  translation stays correct
+
+#### Scenario: Per-turn capture limit reached
+
+- **WHEN** the model requests more captures in one turn than the configured
+  limit
+- **THEN** the call returns an explanatory result instead of a new image
+- **AND** the turn continues
+
+#### Scenario: Earlier captures are left intact
+
+- **WHEN** several captures accumulate across a session
+- **THEN** earlier image content in the conversation is left unmodified so the
+  request prefix stays byte-stable across iterations within a turn
+
+### Requirement: Computer use status command
+
+ACECode SHALL provide a `/computer` command in the TUI, the daemon builtin
+command set, and the web slash-command list that reports backend availability,
+screen geometry, grant state, and configured bounds, and that revokes an active
+grant on request.
+
+#### Scenario: Report status
+
+- **WHEN** the user runs `/computer`
+- **THEN** ACECode reports whether the capability is enabled, whether a backend
+  is available, the current screen geometry, whether a grant is active, and the
+  configured capture bounds
+
+#### Scenario: Revoke an active grant
+
+- **WHEN** a grant is active and the user runs `/computer off`
+- **THEN** the grant is dropped
+- **AND** the next action tool call raises a new permission decision
+
+#### Scenario: Status without a backend
+
+- **WHEN** the platform has no backend and the user runs `/computer`
+- **THEN** the command reports that the capability is unavailable on this
+  platform
+- **AND** exits successfully
diff --git a/openspec/changes/add-computer-use-tools/tasks.md b/openspec/changes/add-computer-use-tools/tasks.md
new file mode 100644
index 000000000..d757d8bd3
--- /dev/null
+++ b/openspec/changes/add-computer-use-tools/tasks.md
@@ -0,0 +1,46 @@
+## 1. Configuration and Gating
+
+- [ ] 1.1 Add `ComputerUseConfig` (`enabled` default false, max capture edge, per-turn capture limit) to `AppConfig` with sparse serialization.
+- [ ] 1.2 Add `register_computer_use_tools` to the built-in registration chain, skipped when disabled and compiled out where no backend exists.
+- [ ] 1.3 Add config schema notes for the `computer_use` section.
+
+## 2. Backend Contract and Coordinates
+
+- [ ] 2.1 Declare `ComputerBackend` (`capture`, `pointer_move`, `pointer_button`, `pointer_scroll`, `key_event`, `type_text`, geometry query) and `ScreenGeometry`.
+- [ ] 2.2 Add the pure `computer_coords` unit: captured-image pixels to logical desktop coordinates, capture downscale factors, virtual-desktop origin, and bounds checks.
+- [ ] 2.3 Port the resize-factor arithmetic from UI-TARS `action-parser` with an attribution comment naming the upstream file.
+- [ ] 2.4 Add the pure capture-budget unit for maximum edge clamping and per-turn capture counting.
+- [ ] 2.5 Add unit tests for coordinate translation, scaled and multi-monitor geometry, staleness detection, out-of-bounds rejection, and budget clamping.
+
+## 3. Windows Backend
+
+- [ ] 3.1 Implement desktop capture and PNG encoding in `computer_backend_win.cpp`, downsampling physical to logical pixels.
+- [ ] 3.2 Implement pointer move, button, scroll, and drag through `SendInput`.
+- [ ] 3.3 Implement the key-name map, chords, explicit hold/release, and literal text entry, releasing held keys on teardown or abort.
+- [ ] 3.4 Add the Windows link dependencies and confirm the capability is absent from non-Windows builds.
+
+## 4. Tool Surface
+
+- [ ] 4.1 Add `computer_screenshot` as read-only, returning a PNG through `ToolResult::attachments` and reporting image dimensions and capture geometry.
+- [ ] 4.2 Add `computer_click`, `computer_move`, `computer_drag`, `computer_scroll`, `computer_key`, and `computer_type` with JSON schemas, abort polling, and structured results.
+- [ ] 4.3 Reject coordinate-bearing actions with no prior capture, with stale geometry, or with out-of-bounds coordinates before dispatching input.
+- [ ] 4.4 Add tool summaries and compact call previews so TUI and web tool rows render usefully.
+
+## 5. Control Grant and Safety
+
+- [ ] 5.1 Add session-scoped grant state with a single capability-level permission decision on the first action tool call.
+- [ ] 5.2 Drop the grant on session end, on user abort, and on explicit revocation; never persist it.
+- [ ] 5.3 Surface an active grant in the session status surfaces so an operating session is visible.
+- [ ] 5.4 Add unit tests for grant acquisition, reuse, denial, abort-drop, and non-persistence.
+
+## 6. Command Surface
+
+- [ ] 6.1 Add a shared `/computer` dispatch reporting availability, geometry, grant state, and bounds, with an `off` subcommand.
+- [ ] 6.2 Register `/computer` in the TUI command table, the daemon builtin allowlist, and the web slash-command list.
+
+## 7. Verification and Documentation
+
+- [ ] 7.1 Add a gated manual smoke path for the native backend, following the notification smoke-test precedent.
+- [ ] 7.2 Document the capability, its default-off posture, the coordinate contract, and the grant model in `README.md`, `README_CN.md`, and the repository capability notes.
+- [ ] 7.3 Record the UI-TARS-desktop Apache-2.0 attribution in NOTICE.
+- [ ] 7.4 Build the relevant targets, run focused tests, manually verify capture and a click sequence on Windows, and strictly validate the OpenSpec change.
diff --git a/openspec/changes/add-macos-computer-use/design.md b/openspec/changes/add-macos-computer-use/design.md
index 27b1eb566..23c0dd523 100644
--- a/openspec/changes/add-macos-computer-use/design.md
+++ b/openspec/changes/add-macos-computer-use/design.md
@@ -24,6 +24,14 @@ The existing Windows implementation has a process-wide broker, a native worker,
 9. A nonactivating mouse-transparent native pointer follows configured ACE/plain style and theme color. Exclude the overlay from target enumeration/hit tests and composite it at most once into returned images. Rendering uses the AppKit main thread.
 10. Build the worker separately from the macOS 11 host targets and only start it on compatible OS versions. Include it alongside the desktop daemon and standalone executable; sign nested code before the outer bundle. Add package presence/architecture checks and document permission ownership for desktop and TUI launches.
 
+## Pointer visibility follow-up
+
+The original fixture sampled a cursor drawn into the returned screenshot by `pointer_composite`. That verifies image composition, not that the native overlay is visible. Acceptance must also discover the helper's on-screen WindowServer window, capture that window independently, and compare its pixels and screen position with the configured pointer and action target. The fixture must verify that the target keeps focus, receives input through the overlay, and that release removes the overlay. A locked desktop cannot satisfy on-screen acceptance.
+
+Keyboard input should provide feedback at the verified focused control, as the existing Windows backend does. Click feedback should remain visibly pressed for the Windows backend's existing 250 ms feedback interval without holding down the real mouse button. Main-thread rendering must flush the overlay, and release/cancellation must still remove it immediately. Listing, launching and observing apps do not imply a pointer action; they must not fabricate a click or move the system mouse.
+
+The local Codex CLI checkout does not contain the native Mac service implementation. The installed Codex application's `@oai/cua` Mac client calls `CodexComputerUseIPC-5`, with app-scoped skyshots and actions delegated to a separately delivered native service. This is reference evidence for an API contract, not evidence of native cursor rendering or its timing. The ACECode implementation keeps its existing window/observation contract and public macOS APIs; compatibility fixes must not be described as porting Codex's private service.
+
 ## Risks / Trade-offs
 
 - TCC attribution can depend on launch path and signing: verify both installed app and terminal paths, record actual grant behavior; never claim a read-only probe proves successful capture/input.
diff --git a/openspec/changes/add-macos-computer-use/specs/macos-computer-use/spec.md b/openspec/changes/add-macos-computer-use/specs/macos-computer-use/spec.md
index 9ce018660..b9a68ed92 100644
--- a/openspec/changes/add-macos-computer-use/specs/macos-computer-use/spec.md
+++ b/openspec/changes/add-macos-computer-use/specs/macos-computer-use/spec.md
@@ -43,6 +43,14 @@ The system SHALL preserve ACE/plain themed pointer appearance, render a nonactiv
 - **WHEN** the user changes pointer style or theme color
 - **THEN** the next render uses the new appearance without enabling control or unnecessarily destroying the current observation
 
+#### Scenario: Visible native action feedback
+- **WHEN** a verified input action targets the fixture's window
+- **THEN** the actual native overlay renders at the action target, keyboard actions show feedback at the focused control, and click feedback remains perceptible without delaying mouse-button release or intercepting input
+
+#### Scenario: Independent overlay acceptance
+- **WHEN** the native pointer fixture runs on an unlocked desktop
+- **THEN** it verifies the actual overlay's WindowServer presence, independently captured pixels, position and removal on release, in addition to checking screenshot composition
+
 ### Requirement: Packaged and verified execution
 The system SHALL include the helper in macOS desktop and standalone distributions, sign nested executables appropriately, and resolve the delivered helper without PATH lookup. Validation SHALL cover deterministic transport and coordinate behavior, actual native fixture interactions and package contents. Unexecuted permission-dependent tests SHALL remain explicitly unverified.
 
diff --git a/openspec/changes/add-macos-computer-use/tasks.md b/openspec/changes/add-macos-computer-use/tasks.md
index ed8b5c80c..fbc40b016 100644
--- a/openspec/changes/add-macos-computer-use/tasks.md
+++ b/openspec/changes/add-macos-computer-use/tasks.md
@@ -20,3 +20,11 @@
 - [x] 4.3 Run frontend tests/build, affected package checks, C++ build and relevant regression tests; review final diff and record remaining verification limits honestly.
 
 Native interaction acceptance passed on the authorized Intel Mac on 2026-09-21. See `verification.md` for executed checks and permission/hardware limits.
+
+## 5. Pointer visibility follow-up
+- [x] 5.1 Record the inspected Codex client contract and distinguish it from the independently implemented ACECode native backend; correct the earlier pointer acceptance claim.
+- [x] 5.2 Add independent checks of the helper's actual WindowServer overlay and rendered pixels, including position, input transparency and cleanup, instead of relying only on screenshot composition.
+- [ ] 5.3 Restore visible action feedback for keyboard input and a perceptible click state, using the existing ACECode Windows behavior as the compatibility reference.
+- [ ] 5.4 Build and run the affected regression checks and unlocked native fixture; record any remaining on-screen verification limits explicitly.
+
+2026-09-24: Code for 5.3 is present and all affected builds, 70 focused tests and helper lifecycle checks pass. The real desktop is locked; the native fixture returns 77. Keep 5.3/5.4 pending until the independent overlay checks can execute on the unlocked desktop. See `verification.md`.
diff --git a/openspec/changes/add-macos-computer-use/verification.md b/openspec/changes/add-macos-computer-use/verification.md
index 47b71a0f7..a3c54aaae 100644
--- a/openspec/changes/add-macos-computer-use/verification.md
+++ b/openspec/changes/add-macos-computer-use/verification.md
@@ -25,7 +25,9 @@ On 2026-09-21, the user unlocked the desktop and granted Accessibility. The actu
 build/macos-x64-agent-browser-test/tests/computer_use_native_mac_smoke.app/Contents/MacOS/computer_use_native_mac_smoke --run-owned-window
 ```
 
-The fixture operates only on its own disposable windows. The passing native run exercised real screenshot pixels against AX coordinates; protected-field filtering; element and coordinate clicks; Unicode typing; Command, Option, Control and Shift chords; AX value/invoke/toggle; horizontal and vertical scroll; drag and mouse-button release; one-use observations; stale geometry and changed-focus rejection including another window of the same process; sheet and context-menu capture/input; ACE/plain pointer pixels and cleanup; and exact app discovery/launch.
+The fixture operates only on its own disposable windows. The passing native run exercised real screenshot pixels against AX coordinates; protected-field filtering; element and coordinate clicks; Unicode typing; Command, Option, Control and Shift chords; AX value/invoke/toggle; horizontal and vertical scroll; drag and mouse-button release; one-use observations; stale geometry and changed-focus rejection including another window of the same process; sheet and context-menu capture/input; ACE/plain pointer pixels and cleanup in the composed screenshots; and exact app discovery/launch.
+
+**Correction, 2026-09-24:** The pointer assertions above sampled `pointer_composite` output. They did not independently capture the native overlay or verify its visibility to a person on the desktop. They must not be treated as acceptance of the real on-screen pointer. The pointer visibility follow-up in `tasks.md` reopens that coverage.
 
 This run exposed and fixed a real occlusion bug: the system Dock can own a screen-sized transparent backing window. The helper now ignores that specific system-owned backing rectangle while retaining the system-wide AX hit test. The native fixture also verifies that an actual opaque input panel still blocks the click. Fixture improvements include refreshing the bundled helper when its binary changes, checking bitmap samples in their actual color profile, providing the standard Edit menu for Cmd+A, reobserving explicitly reported AX/WindowServer transitions, and waiting for the menu action callback rather than assuming its animation finishes in 150 ms. Input actions are never retried by the fixture.
 
@@ -46,3 +48,19 @@ Local evidence from this run:
 ## Coverage limits
 
 Real mixed-display interactions, additional keyboard layouts, Apple Silicon execution and Developer ID-signed installed-app/TUI permission attribution remain unverified. Single-display Retina interactions passed; negative origins and differing image scales have deterministic tests. Release signing now includes the standalone helper and existing nested-code signing covers its bundled copy; no release signing, notarization or publishing was performed here. Existing Windows native code was preserved, but Windows runtime tests were not executed on this host.
+
+## Pointer visibility follow-up — 2026-09-24
+
+Source inspection confirmed two action-feedback gaps: `press_key`/`type_text` never showed the Mac overlay, and clicks reset their pressed state immediately after posting mouse up, potentially before AppKit rendered a frame. The changes add focused-control feedback, request an immediate overlay redraw and preserve the visual pressed state for the existing Windows backend's 250 ms interval. Actual mouse-up, release and cancellation are not delayed. These are ACECode compatibility fixes, not a claim to reproduce Codex's private cursor implementation. The inspected Codex Mac client contract and remaining differences are recorded in `docs/computer-use.md`.
+
+The native fixture now independently identifies its child helper's on-screen WindowServer window, captures only that overlay with ScreenCaptureKit and checks its pixels, hotspot, foreground preservation and removal. It also clicks through an already-visible overlay and starts keyboard checks with the previous overlay released. Its capture does not use `pointer_composite` or images returned by the Computer Use tool. Optional artifacts include `native-overlay.png` alongside the disposable fixture's images.
+
+Executed checks:
+
+- Rebuilt `acecode-computer-use`, `computer_use_native_mac_smoke`, `acecode_unit_tests` and `acecode-desktop` successfully.
+- All 70 focused tests (`ComputerUse*:*ComputerUse*:*ToolImage*`) passed; the actual-helper lifecycle CTest passed.
+- OpenSpec strict validation and `git diff --check` passed.
+- Build-root, fixture-bundle and desktop-bundle helpers match SHA-256 `ed1626979b51624c66ee73a3f2ac68551f96a9ea4cc25574cde803b23b070f38`.
+- The native fixture returned **77** because the desktop was locked. This is **not** a pass. The newly added independent overlay checks, perceived click feedback and keyboard feedback still require an unlocked run; follow-up tasks 5.3/5.4 remain unchecked pending that acceptance.
+
+Local logs: `/tmp/acecode-macos-pointer-build-20260924.log`, `/tmp/acecode-macos-pointer-fixture-final-20260924.log`, `/tmp/acecode-macos-pointer-unit-20260924.log`, `/tmp/acecode-macos-pointer-lifecycle-20260924.log` and `/tmp/acecode-macos-pointer-native-20260924.log`.
diff --git a/openspec/changes/tighten-companion-pet-hit-area/.openspec.yaml b/openspec/changes/tighten-companion-pet-hit-area/.openspec.yaml
new file mode 100644
index 000000000..0cb476561
--- /dev/null
+++ b/openspec/changes/tighten-companion-pet-hit-area/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-16
diff --git a/openspec/changes/tighten-companion-pet-hit-area/design.md b/openspec/changes/tighten-companion-pet-hit-area/design.md
new file mode 100644
index 000000000..d038bc5e0
--- /dev/null
+++ b/openspec/changes/tighten-companion-pet-hit-area/design.md
@@ -0,0 +1,23 @@
+## Context
+
+透明窗口保持 344 × 252 的基准尺寸，为上方宽会话卡片留出空间。精灵逐帧 alpha 横条已用于原生命中区域，但悬停时被整个精灵画布外框取代；页面内部悬停也使用该外框。
+
+## Goals / Non-Goals
+
+目标：本体激活区贴近实际轮廓；把手位于宠物左上角；气泡大小及点击区域保持。范围不含办公室布局、宠物尺寸、会话卡片样式与行为。
+
+## Decisions
+
+1. 始终上报 alpha 轮廓横条，保留既有小幅动作边距。悬停稳定性仅用鼠标进入位置附近的小矩形维持，避免动画跳动触发反复进出。
+2. 页面内悬停判断复用本体轮廓，不使用精灵外框。换角色、离开和拖动结束后避免遗留悬停区域。
+3. 缩放把手保持 16 CSS 像素，位置来自可见轮廓左上角；窗口缩放时重算 CSS 坐标。贴边时夹到窗口内。
+4. overlay 消息添加可选 `grip` 矩形。共享解析器验证并纳入窗口区域，macOS 保存并用于原生缩放光标；办公室继续使用既有固定坐标。
+5. `rect` 仍独立上报会话卡片外框，保持宽度与绘制阴影留白；不缩窄整个窗口。
+
+## Risks / Trade-offs
+
+轮廓按有限数量横条近似，保留动画所需的小边距；快速变换姿态时把手位置随可见范围更新。macOS 本机运行需在 macOS 后补，Windows 构建与共享页面可在当前机器检查。
+
+## Migration Plan
+
+无需数据迁移。旧的办公室页面不发送 `grip`，原生宿主保留办公室固定把手命中。
diff --git a/openspec/changes/tighten-companion-pet-hit-area/proposal.md b/openspec/changes/tighten-companion-pet-hit-area/proposal.md
new file mode 100644
index 000000000..eb3534600
--- /dev/null
+++ b/openspec/changes/tighten-companion-pet-hit-area/proposal.md
@@ -0,0 +1,21 @@
+## Why
+
+陪伴宠物悬停后使用整张精灵画布作为激活区域，透明部分占用桌面；缩放把手固定在整个窗口的左侧，与宠物本体相距过远。
+
+## What Changes
+
+- 大眼回形针、Rover 和鲸鱼娘按可见精灵轮廓接收鼠标，悬停不扩大为整张画布。
+- 缩放三角紧贴宠物可见轮廓的左上角，缩放和贴边状态同步更新。
+- 保持上方会话气泡的原有宽度、独立命中范围与会话操作。
+- macOS 原生缩放光标跟随页面上报的把手区域，办公室保留原有布局。
+
+## Capabilities
+
+### New Capabilities
+- `companion-pet-hit-area`: 陪伴宠物轮廓命中与独立会话气泡区域。
+
+### Modified Capabilities
+
+## Impact
+
+影响共享陪伴宠物页面与 macOS 原生把手命中；Windows 沿用现有页面浮层区域协议。无持久化数据或会话格式变更。
diff --git a/openspec/changes/tighten-companion-pet-hit-area/specs/companion-pet-hit-area/spec.md b/openspec/changes/tighten-companion-pet-hit-area/specs/companion-pet-hit-area/spec.md
new file mode 100644
index 000000000..7f7d68f9c
--- /dev/null
+++ b/openspec/changes/tighten-companion-pet-hit-area/specs/companion-pet-hit-area/spec.md
@@ -0,0 +1,25 @@
+## ADDED Requirements
+
+### Requirement: Companion body activation follows visible art
+
+The companion pet SHALL use visible sprite silhouette bands for native and page pointer hit detection, including while hovered. A small hover anchor MAY keep a stationary pointer active across animation frames without activating the full sprite frame.
+
+#### Scenario: Hovering does not activate transparent side margins
+- **WHEN** a pointer enters the visible companion pet
+- **THEN** the pet responds to hover while transparent side margins outside its silhouette and small motion allowance remain click-through
+
+### Requirement: Resize grip follows the pet corner
+
+The resize grip SHALL retain a 16 CSS pixel target at the visible pet's upper left corner and update when the viewport, character or docked pose changes. Native cursor hit detection SHALL use the reported grip for companion pets.
+
+#### Scenario: Character and size change
+- **WHEN** the user changes companion character or window size
+- **THEN** the grip is repositioned next to the visible pet instead of staying at the wide window's left edge
+
+### Requirement: Session bubbles retain independent width
+
+Session bubbles SHALL retain their existing width, shadow padding and independent native hit region when the companion body region is tightened.
+
+#### Scenario: Wide session card above narrow pet
+- **WHEN** a session card is displayed above a companion pet
+- **THEN** both ends of the card remain visible and interactive while transparent space beside the body remains click-through
diff --git a/openspec/changes/tighten-companion-pet-hit-area/tasks.md b/openspec/changes/tighten-companion-pet-hit-area/tasks.md
new file mode 100644
index 000000000..97a99e4cd
--- /dev/null
+++ b/openspec/changes/tighten-companion-pet-hit-area/tasks.md
@@ -0,0 +1,19 @@
+## 1. 实现
+
+- [x] 1.1 复用 alpha 横条收紧悬停与本体命中，保留局部悬停稳定性。
+- [x] 1.2 依据可见轮廓更新左上角缩放把手，并同步原生命中。
+- [x] 1.3 保留会话气泡的布局与独立浮层范围。
+
+## 2. 交付检查
+
+- [x] 2.1 检查三个角色、窗口缩放与鲸鱼娘贴边时的页面几何和渲染。
+- [x] 2.2 完成 Windows Desktop 编译、静态差异检查和 OpenSpec 严格验证，记录平台限制。
+
+### 检查记录（2026-10-16）
+
+- Chromium/Edge 页面渲染检查覆盖 Clippy、Rover、鲸鱼娘在 172、430、860px 窗口宽度下的本体与把手，以及鲸鱼娘左右贴边；11 个状态无页面脚本错误。
+- 430px 窗口中卡片可见宽度修改前后均为 395.625px；把手保持 16px，并跟随 alpha 轮廓左上角。上方 stack 的样式与外框上报保持。
+- 悬停时仍上报约 16–18 条轮廓横条与局部锚点，不再替换为整张精灵框。锚点只在可见轮廓内更新，避免鼠标通过小步移动把激活区拖入透明区域。
+- layer、文档路径、所有权静态检查通过；设计扫描仅提示原有卡片的字体、圆角与颜色不在办公室局部规范中，本次没有修改这些样式。
+- macOS 原生命中与缩放光标已同步源码；当前机器为 Windows，未执行 macOS 运行验证。
+- Windows `cmake --build build --config MinSizeRel --target acecode acecode-desktop -- /m:4 /v:minimal` 成功；通过项目共享 Desktop 启动函数打开新实例（PID 108440），原 Debug 实例保留。编译前重新配置 CMake，确认伴随宠物资源已重新嵌入。
diff --git a/openspec/changes/use-underscore-runtime-names/.openspec.yaml b/openspec/changes/use-underscore-runtime-names/.openspec.yaml
new file mode 100644
index 000000000..0cb476561
--- /dev/null
+++ b/openspec/changes/use-underscore-runtime-names/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-16
diff --git a/openspec/changes/use-underscore-runtime-names/design.md b/openspec/changes/use-underscore-runtime-names/design.md
new file mode 100644
index 000000000..c83500b38
--- /dev/null
+++ b/openspec/changes/use-underscore-runtime-names/design.md
@@ -0,0 +1,27 @@
+## Context
+
+会话 ID 当前由 SessionStorage 生成 `YYYYMMDD-HHMMSS-xxxx`，部分诊断使用固定正则；日志由 Logger 和输入跟踪独立生成，反馈收集按连字符前缀匹配。多个持久化配置、IPC 文件和数据目录也带连字符。
+
+## Goals / Non-Goals
+
+目标是统一自动生成名称，并保证旧名称可用。保留用户输入路径、现有会话 ID、协议 UUID 和第三方要求的文件名；不通过全局替换路径或重写数据完成迁移。
+
+## Decisions
+
+1. 在 base/utils 提供共享名称转换和持久化路径兼容工具。转换仅用于系统负责生成的新名称，兼容路径优先使用实际存在的旧资源，避免创建并行空数据库或丢失配置。
+2. 新会话 ID 使用下划线；读取时保持 ID 原样，不把旧 ID 转换成另一个身份。旧 PID 后缀实验数据仍按原约定排除，新格式同样不能误列为独立会话。
+3. 日志新写使用下划线；反馈发现识别两种前缀并按真实修改时间选择，不依靠文件名字典序推断最新记录。
+4. 新反馈包、导出建议名、工具结果和临时文件在生成边界规范化；历史元数据存储的文件路径直接按记录读取。
+5. 固定名称的持久化资源首次创建使用新名，已有旧资源继续使用旧路径。协议 / 单实例协调资源的修改必须覆盖生产者、消费者及开发启动器，避免同时出现两个资源所有者。
+
+## Risks / Trade-offs
+
+旧程序未必识别新会话 ID；本次保证新版读取旧数据，不承诺旧程序理解未来全部新增数据。新旧路径并存时不得删除其中一个；必须给出确定的优先级并验证历史读取。SQLite 自身生成的 `-wal`、`-shm` 属于第三方协议，不改写。
+
+## Validation Strategy
+
+覆盖新名称无连字符、新旧会话混合列表与恢复、旧 PID 后缀排除、跨日和多进程日志追加、反馈新旧日志发现、旧配置与备份读取，以及实际构建。按改动范围运行定向原生与脚本测试、静态分层闸门和严格 OpenSpec 验证。
+
+## 生成入口清单
+
+完整名称对照及兼容例外记录在 `docs/runtime_file_naming.md`。实现覆盖会话/诊断、Logger/FTXUI、反馈、配置恢复、工具输出/截图、Web 粘贴与导出、升级临时文件、记忆观察/归档、数据库/运行记录、浏览器配置和开发启动器。共享进程锁、标准协议资源与用户命名保持原约定。
diff --git a/openspec/changes/use-underscore-runtime-names/proposal.md b/openspec/changes/use-underscore-runtime-names/proposal.md
new file mode 100644
index 000000000..2219a9f26
--- /dev/null
+++ b/openspec/changes/use-underscore-runtime-names/proposal.md
@@ -0,0 +1,24 @@
+## Why
+
+ACECode 自动生成的会话、日志、附件和导出文件混用连字符与下划线。统一新名称使用 `_`，同时确保已有会话和日志仍可读取、恢复和收集。
+
+## What Changes
+
+- 新会话 ID 使用 `YYYYMMDD_HHMMSS_xxxx`；列表、恢复、诊断同时识别新旧格式。
+- 自动生成的运行数据、日志、反馈、导出、临时文件和备份名称统一使用下划线分隔。
+- 固定持久化路径采用旧路径兼容解析；已有资源继续使用实际路径，不批量重命名。
+- 用户确认只调整自动生成的运行数据。标准协议标识、外部工具约定的文件名和用户明确提供的路径保留其语义；发布包与 AI 自主创建的工程文件不在本次范围。
+
+## Capabilities
+
+### New Capabilities
+
+- `runtime-file-naming`: 新生成运行数据的下划线命名及旧名称兼容。
+
+### Modified Capabilities
+
+- `session-storage`: 新会话 ID 的格式和新旧数据同时发现、恢复。
+
+## Impact
+
+涉及 base 路径与日志工具、session 存储与导出、工具输出、反馈收集、升级诊断和对应开发启动器、测试及文档。无数据批量迁移，不改变 HTTP 路由、第三方 UUID 标准或既有会话标识。
diff --git a/openspec/changes/use-underscore-runtime-names/specs/runtime-file-naming/spec.md b/openspec/changes/use-underscore-runtime-names/specs/runtime-file-naming/spec.md
new file mode 100644
index 000000000..bb9a5034f
--- /dev/null
+++ b/openspec/changes/use-underscore-runtime-names/specs/runtime-file-naming/spec.md
@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### Requirement: Generated runtime names use underscores
+
+ACECode SHALL use `_` instead of `-` as a separator in names it generates for runtime files, logs, attachments, exports, backups and temporary artifacts. User-supplied paths and externally mandated file names MUST retain their meaning.
+
+#### Scenario: Generate a dated runtime artifact
+- **WHEN** ACECode generates a log, feedback package or tool output file
+- **THEN** the newly generated file name contains underscore separators and no hyphen separators
+
+### Requirement: Existing runtime data remains accessible
+
+ACECode MUST continue discovering and reading existing files with hyphen names. Persisted session IDs and explicit artifact references MUST remain unchanged. The system MUST NOT silently create an empty replacement store when a legacy data store already exists.
+
+#### Scenario: Upgrade an existing data directory
+- **WHEN** the data directory contains a legacy persistent resource and no new-name replacement
+- **THEN** ACECode reads and updates the existing resource without losing its content
+
+#### Scenario: Feedback collects mixed log names
+- **WHEN** old hyphen logs and new underscore logs coexist
+- **THEN** log discovery includes the applicable logs and selects recent files using modification times
+
+#### Scenario: Clean up a relocated data directory
+- **WHEN** the default directory contains either or both generations of the data-directory redirect file
+- **THEN** cleanup preserves both redirect names, keeps the active redirect readable and does not count redirect files as remaining user data
+- **AND** subsequent data migrations exclude both redirect names from copied data
+
+#### Scenario: Rebuild with a daemon from a previous commit
+- **WHEN** an earlier daemon still owns a runtime directory using either naming generation
+- **THEN** the development launcher detects it across both runtime roots and blocks the rebuild without stopping the process
diff --git a/openspec/changes/use-underscore-runtime-names/specs/session-storage/spec.md b/openspec/changes/use-underscore-runtime-names/specs/session-storage/spec.md
new file mode 100644
index 000000000..d1fbdefc1
--- /dev/null
+++ b/openspec/changes/use-underscore-runtime-names/specs/session-storage/spec.md
@@ -0,0 +1,21 @@
+## ADDED Requirements
+
+### Requirement: New session IDs use underscore separators
+
+SessionStorage SHALL generate session IDs in the form `YYYYMMDD_HHMMSS_xxxx`, retaining the existing UTC timestamp and four random hexadecimal digits.
+
+#### Scenario: Create a session
+- **WHEN** a new session ID is automatically generated
+- **THEN** its ID and canonical JSONL / metadata file names use underscores instead of hyphens
+
+### Requirement: Mixed session naming remains compatible
+
+Session discovery, recovery and diagnostics MUST support legacy hyphen IDs and new underscore IDs without rewriting either identity. Legacy PID-suffixed experimental files MUST remain excluded from canonical session listings.
+
+#### Scenario: Resume legacy history
+- **WHEN** a legacy hyphen-named session is resumed
+- **THEN** the original session ID and file paths are used and its messages remain readable
+
+#### Scenario: Discover both generations
+- **WHEN** a workspace contains legacy and underscore sessions
+- **THEN** both canonical sessions appear in metadata listings and diagnostics
diff --git a/openspec/changes/use-underscore-runtime-names/tasks.md b/openspec/changes/use-underscore-runtime-names/tasks.md
new file mode 100644
index 000000000..f165be534
--- /dev/null
+++ b/openspec/changes/use-underscore-runtime-names/tasks.md
@@ -0,0 +1,27 @@
+## 1. 生成与兼容基础
+
+- [x] 1.1 建立共享下划线命名和旧路径兼容工具，记录生成入口清单。
+- [x] 1.2 新会话 ID 使用下划线，更新扫描、诊断、恢复验证并覆盖新旧混合数据。
+
+## 2. 运行数据名称
+
+- [x] 2.1 更新日志、输入跟踪、升级诊断与反馈发现，兼容旧日志。
+- [x] 2.2 更新反馈包、导出建议名、工具输出、临时文件和备份的生成边界。
+- [x] 2.3 更新带连字符的固定运行数据路径，保持旧数据和进程协调兼容。
+
+## 3. 验证与文档
+
+- [x] 3.1 更新对应回归测试和运行数据名称文档。
+- [x] 3.2 完成定向构建、兼容性测试、静态闸门和严格 OpenSpec 验证（主题导出用例的环境失败另列）。
+
+### 检查记录（2026-10-16）
+
+- Web 测试与生产构建通过；开发运行目录脚本 57 项、Desktop 启动脚本 13 项、独立进程追加日志 4 项通过。
+- 原生定向检查 384 项：第二轮 383 项通过；`ThemeExportTest.ConcurrentCompletedJobReclamationKeepsRegisteredWorkerHandles` 在安装测试主题时遇到 Windows 临时目录重命名拒绝访问（该用例首轮通过），不记为稳定通过。会话、新旧日志、旧路径复用等命名兼容用例通过。
+- layer、文档路径、所有权静态闸门与严格 OpenSpec 验证通过。
+- FTXUI overlay 在 vcpkg 私有构建目录复制源码后修改输入追踪文件名，原子模块保持干净；port-version 为 9。
+- 最终 MinSizeRel CLI 与 Desktop 编译成功，并启动包含改动的新 Desktop 实例；macOS 源码调整未在本机编译或运行。
+- 发布集成复核：修正开发启动器重建前的占用检查，同时扫描 `dev-run` / `dev_run` 和连字符 / 下划线会话目录；覆盖两代目录同时存在且旧目录为空的四种组合，保持仅检查 daemon 身份、不自动停止进程。开发脚本回归通过。无工作区路径断言已同步为 `no_workspace`。
+- 发布集成补验发现数据目录迁移的排除、清理与剩余数据统计仍只识别旧重定向文件名；已统一识别两代名称并保留两代并存时的旧文件优先级，新增回归及相关原生复测 119/119 通过。两个真实子进程的会话文件用例已按新下划线命名更新，并继续禁止两代 PID 后缀。
+
+- 最终 Windows 集成全量运行 6,436 项；发现的 10 个失败（命名断言、Windows 路径夹具和重定向清理）已修复并通过 119 项定向复测。合并全量与复测结果：6,426 项通过、11 项平台/外部条件跳过、1 项原有禁用；记录为 `build/release-integration-20261016/native-validation.json`。
diff --git a/ports/ftxui/portfile.cmake b/ports/ftxui/portfile.cmake
index e6d051ff3..a180e8086 100644
--- a/ports/ftxui/portfile.cmake
+++ b/ports/ftxui/portfile.cmake
@@ -9,12 +9,33 @@
 #   62e7471b (含 synchronized output + opt-in mouse hover motion)
 #   —— 输入追踪日志路径由 ACECODE_FTXUI_INPUT_TRACE_DIR 运行时指定。
 #   —— 原子追加输入追踪记录,避免多个 TUI 进程互相覆盖。
+#   —— 输入追踪日志使用 tui_input_trace_YYYY_MM_DD.log。
 #   —— hover-motion 补丁(link-hover-tooltip 依赖无按键 Mouse::Moved 上报,
 #   DEC mode 1003),提供 ftxui::App::EnableMouseHoverMotion()。
 vcpkg_check_linkage(ONLY_STATIC_LIBRARY)
 
 get_filename_component(SOURCE_PATH "${CMAKE_CURRENT_LIST_DIR}/../../external/ftxui" ABSOLUTE)
 
+# Patch a private build copy so configuring dependencies never modifies the submodule.
+file(REAL_PATH "${CURRENT_BUILDTREES_DIR}" ACECODE_FTXUI_BUILD_ROOT)
+set(ACECODE_FTXUI_BUILD_SOURCE "${ACECODE_FTXUI_BUILD_ROOT}/acecode_runtime_source")
+file(REAL_PATH "${ACECODE_FTXUI_BUILD_SOURCE}" ACECODE_FTXUI_RESOLVED_SOURCE)
+get_filename_component(ACECODE_FTXUI_SOURCE_PARENT "${ACECODE_FTXUI_RESOLVED_SOURCE}" DIRECTORY)
+if(NOT ACECODE_FTXUI_SOURCE_PARENT STREQUAL ACECODE_FTXUI_BUILD_ROOT)
+    message(FATAL_ERROR "FTXUI private source must be directly inside its build tree")
+endif()
+file(REMOVE_RECURSE "${ACECODE_FTXUI_BUILD_SOURCE}")
+file(COPY "${SOURCE_PATH}/" DESTINATION "${ACECODE_FTXUI_BUILD_SOURCE}" PATTERN ".git" EXCLUDE)
+set(SOURCE_PATH "${ACECODE_FTXUI_BUILD_SOURCE}")
+
+# Keep ACECode's runtime naming policy in this overlay, including cache rebuilds
+# from the unchanged upstream gitlink.
+set(ACECODE_TRACE_HEADER "${SOURCE_PATH}/src/ftxui/component/acecode_input_trace.hpp")
+file(READ "${ACECODE_TRACE_HEADER}" ACECODE_TRACE_SOURCE)
+string(REPLACE "tui-input-trace-" "tui_input_trace_" ACECODE_TRACE_SOURCE "${ACECODE_TRACE_SOURCE}")
+string(REPLACE "%Y-%m-%d" "%Y_%m_%d" ACECODE_TRACE_SOURCE "${ACECODE_TRACE_SOURCE}")
+file(WRITE "${ACECODE_TRACE_HEADER}" "${ACECODE_TRACE_SOURCE}")
+
 vcpkg_cmake_configure(
     SOURCE_PATH "${SOURCE_PATH}"
     OPTIONS
@@ -27,6 +48,9 @@ vcpkg_cmake_configure(
 
 vcpkg_cmake_install()
 
+# The independent-process log fixture exercises the exact production writer.
+file(INSTALL "${ACECODE_TRACE_HEADER}" DESTINATION "${CURRENT_PACKAGES_DIR}/include/ftxui/component")
+
 vcpkg_cmake_config_fixup(CONFIG_PATH lib/cmake/${PORT})
 
 vcpkg_fixup_pkgconfig()
diff --git a/ports/ftxui/vcpkg.json b/ports/ftxui/vcpkg.json
index 7e8e30def..aa3edc244 100644
--- a/ports/ftxui/vcpkg.json
+++ b/ports/ftxui/vcpkg.json
@@ -1,7 +1,7 @@
 {
   "name": "ftxui",
   "version-semver": "7.0.3",
-  "port-version": 8,
+  "port-version": 9,
   "description": "C++ Functional Terminal User Interface (shaohaozhi286 fork; adds ACECode TUI selection, input trace, Kitty keyboard lifecycle, and synchronized output (DEC mode 2026) patches — see external/ftxui/ACECODE_PATCHES.md)",
   "homepage": "https://github.com/shaohaozhi286/FTXUI",
   "license": "MIT",
diff --git a/scripts/channel_lab/server.py b/scripts/channel_lab/server.py
index 51c5696d2..9f11b7ce3 100644
--- a/scripts/channel_lab/server.py
+++ b/scripts/channel_lab/server.py
@@ -360,6 +360,8 @@ def make_server(lab, port=0):
 def source_config():
     data_dir = Path(os.environ['USERPROFILE']) / '.acecode'
     redirect = data_dir / 'data-dir.redirect.json'
+    if not redirect.exists():
+        redirect = data_dir / 'data_dir.redirect.json'
     if redirect.exists():
         data_dir = Path(json.loads(redirect.read_text(encoding='utf-8-sig'))['data_dir'])
     return data_dir / 'config.json'
diff --git a/scripts/dev_desktop.py b/scripts/dev_desktop.py
index 24181e93f..b55b39bd3 100644
--- a/scripts/dev_desktop.py
+++ b/scripts/dev_desktop.py
@@ -231,7 +231,7 @@ def pick_desktop_build(builds: list[Path], preferred: str | None = None) -> Path
 # ─── 启动 Desktop ───────────────────────────────────────────────────────────
 
 def desktop_instance_identity(project_root: Path) -> str:
-    """Stable `<worktree>-<commit12>` identity, shared with the Web runtime naming."""
+    """Stable `<worktree>_<commit12>` identity, shared with the Web runtime naming."""
     from dev_environment import current_commit, sanitize_identity
 
     commit = current_commit(project_root)
diff --git a/scripts/dev_environment.py b/scripts/dev_environment.py
index 3cb9443a2..c09ff669f 100644
--- a/scripts/dev_environment.py
+++ b/scripts/dev_environment.py
@@ -29,12 +29,12 @@
 PRUNE_TARGET = "prune"
 TARGETS = (*LAUNCH_TARGETS, PRUNE_TARGET)
 CACHE_MARKER = ".acecode-sccache.json"
-WORKER_LOG_NAME = "daemon-worker.log"
+WORKER_LOG_NAME = "daemon_worker.log"
 WORKER_LOG_MAX_BYTES = 1024 * 1024
 PORT_RANGE_START = 28080
 PORT_RANGE_COUNT = 201
 PORT_RANGE_END = PORT_RANGE_START + PORT_RANGE_COUNT - 1
-DAEMON_STARTUP_LOG_NAME = "daemon-startup.log"
+DAEMON_STARTUP_LOG_NAME = "daemon_startup.log"
 
 
 @dataclass(frozen=True)
@@ -477,8 +477,8 @@ def refresh_web_assets(root: Path, force: bool = False) -> bool:
 
 
 def sanitize_identity(name: str, identity: str) -> str:
-    """Build the shared filesystem-safe `<name>-<commit12>` runtime identity."""
-    return re.sub(r"[^A-Za-z0-9_.-]", "-", f"{name}-{identity[:12]}")
+    """Build the shared filesystem-safe `<name>_<commit12>` runtime identity."""
+    return re.sub(r"[^A-Za-z0-9_.]", "_", f"{name}_{identity[:12]}")
 
 
 def safe_identity(root: Path) -> str:
@@ -486,16 +486,20 @@ def safe_identity(root: Path) -> str:
 
 
 def runtime_root(root: Path) -> Path:
-    return root / ".acecode" / "dev-run"
+    legacy = root / ".acecode" / "dev-run"
+    return legacy if legacy.is_dir() else root / ".acecode" / "dev_run"
 
 
 def worktree_runtime_dir(root: Path) -> Path:
-    return runtime_root(root) / safe_identity(root)
+    base = runtime_root(root)
+    legacy_id = re.sub(r"[^A-Za-z0-9_.-]", "-", f"{root.name}-{(current_commit(root) or root.name)[:12]}")
+    legacy = base / legacy_id
+    return legacy if legacy.is_dir() else base / safe_identity(root)
 
 
 def worktree_prefix(root: Path) -> str:
     """Prefix every runtime directory owned by this worktree shares."""
-    return re.sub(r"[^A-Za-z0-9_.-]", "-", root.name) + "-"
+    return re.sub(r"[^A-Za-z0-9_.]", "_", root.name) + "_"
 
 
 def selected_web_runtime_dir(root: Path, extra: list[str]) -> Path:
@@ -651,13 +655,18 @@ def vite_options(extra: list[str]) -> list[str]:
 def web_runtime_is_available(root: Path, candidate: BuildCandidate | None, extra: list[str]) -> bool:
     run_dir = selected_web_runtime_dir(root, extra)
     explicit = any(arg == "--run-dir" or arg.startswith("--run-dir=") for arg in extra)
-    if not explicit and run_dir.parent.is_dir():
+    if not explicit:
         # A new commit changes the default run-dir name but an older worker
         # can still hold this build's executable open. Inspect only this
         # worktree's own launcher directories, without stopping any process.
-        prefix = worktree_prefix(root)
-        for previous in sorted(run_dir.parent.iterdir()):
-            if previous.name.startswith(prefix) and (previous / "daemon.pid").exists():
+        prefixes = (worktree_prefix(root), re.sub(r"[^A-Za-z0-9_.-]", "-", root.name) + "-")
+        bases = (run_dir.parent, root / ".acecode" / "dev_run", root / ".acecode" / "dev-run")
+        for base in dict.fromkeys(bases):
+            if not base.is_dir():
+                continue
+            previous = next((path for path in sorted(base.iterdir())
+                             if path.name.startswith(prefixes) and (path / "daemon.pid").exists()), None)
+            if previous is not None:
                 run_dir = previous
                 break
     if not (run_dir / "daemon.pid").exists():
@@ -744,8 +753,13 @@ def daemon_worker_log_path(runtime_dir: Path) -> Path:
 
 
 def worker_failure_detail(runtime_dir: Path, reason: str) -> str:
-    return (f"{reason}; see {daemon_worker_log_path(runtime_dir)} and "
-            f"{runtime_dir / DAEMON_STARTUP_LOG_NAME}")
+    worker = daemon_worker_log_path(runtime_dir)
+    startup = runtime_dir / DAEMON_STARTUP_LOG_NAME
+    if not worker.exists() and (runtime_dir / "daemon-worker.log").exists():
+        worker = runtime_dir / "daemon-worker.log"
+    if not startup.exists() and (runtime_dir / "daemon-startup.log").exists():
+        startup = runtime_dir / "daemon-startup.log"
+    return f"{reason}; see {worker} and {startup}"
 
 
 def open_worker_log(runtime_dir: Path, command: list[str]):
@@ -906,9 +920,10 @@ def launch_vite(root: Path, daemon_port_number: int, runtime_dir: Path, extra: l
 def prune_candidates(root: Path) -> list[Path]:
     """Runtime directories worth inspecting: the worktree root plus the legacy tree."""
     candidates: list[Path] = []
-    base = runtime_root(root)
-    if base.is_dir() and base.resolve().is_relative_to(root.resolve()):
-        candidates.extend(sorted(path for path in base.iterdir()))
+    for name in ("dev_run", "dev-run"):
+        base = root / ".acecode" / name
+        if base.is_dir() and base.resolve().is_relative_to(root.resolve()):
+            candidates.extend(sorted(path for path in base.iterdir()))
     legacy = root / ".acecode-dev-run"
     if legacy.is_dir() and legacy.resolve().is_relative_to(root.resolve()):
         candidates.append(legacy)
@@ -976,7 +991,7 @@ def prune_worktree_runtime_dirs(root: Path, current: Path) -> int:
     base = runtime_root(root)
     if not base.is_dir() or not base.resolve().is_relative_to(root.resolve()):
         return 0
-    prefix = worktree_prefix(root)
+    prefix = (worktree_prefix(root), re.sub(r"[^A-Za-z0-9_.-]", "-", root.name) + "-")
     stale = [
         previous for previous in sorted(base.iterdir())
         if previous.is_dir() and previous.name != current.name and previous.name.startswith(prefix)
diff --git a/scripts/embed_desktop_pet.py b/scripts/embed_desktop_pet.py
index 6395d3b5b..4f708329d 100644
--- a/scripts/embed_desktop_pet.py
+++ b/scripts/embed_desktop_pet.py
@@ -23,8 +23,8 @@ def inline(match):
     for kind in ("clippy", "rover", "whale"):
         folder = root / "whale" if kind == "whale" else root / "classic" / kind
         resources[kind + "_pet_sprite"] = (folder / "map.png").read_bytes()
-    # Whale Girl peeking from a screen edge while docked (two frames: eyes open / blink).
-    resources["whale_pet_peek"] = (root / "whale" / "peek.png").read_bytes()
+        # The pet peeking from a screen edge while docked (two frames: eyes open / blink).
+        resources[kind + "_pet_peek"] = (folder / "peek.png").read_bytes()
     output.parent.mkdir(parents=True, exist_ok=True)
     with output.open("w", encoding="utf-8", newline="\n") as out:
         out.write("// Generated by scripts/embed_desktop_pet.py\n#include <cstddef>\nnamespace acecode {\n")
@@ -35,7 +35,7 @@ def inline(match):
             out.write(f"}};\nconst unsigned char* {name}_data() {{ return {name}_bytes; }}\n")
             out.write(f"std::size_t {name}_size() {{ return {len(data)}; }}\n")
         out.write("}\n")
-    print(f"Embedded companion pet page ({len(encoded)} bytes), 3 sprite sheets and the whale peek sheet")
+    print(f"Embedded companion pet page ({len(encoded)} bytes), 3 sprite sheets and 3 edge-peek sheets")
 
 
 if __name__ == "__main__":
diff --git a/src/adapters/computer_use/macos_capture.mm b/src/adapters/computer_use/macos_capture.mm
index 7e9ab803a..b839356ec 100644
--- a/src/adapters/computer_use/macos_capture.mm
+++ b/src/adapters/computer_use/macos_capture.mm
@@ -1,4 +1,5 @@
 #include "macos_native.hpp"
+#include "utils/generated_file_names.hpp"
 #import <ImageIO/ImageIO.h>
 
 namespace acecode::computer_use::macos {
@@ -64,7 +65,7 @@ json capture(Surface& surface, const std::string& observation_id, std::size_t in
     descriptor = geometry(surface);
     descriptor.update({{"id", surface.screenshot_id}, {"window", surface.window.id}, {"observation_id", observation_id},
         {"capture_method", "screencapturekit"}, {"relation", surface.relation}, {"cursor", cursor}, {"zIndex", index}});
-    return {{"name", "computer-use-" + surface.screenshot_id + ".png"}, {"mime_type", "image/png"},
+    return {{"name", generated_file_name("computer_use_" + surface.screenshot_id + ".png")}, {"mime_type", "image/png"},
         {"data_url", "data:image/png;base64," + text([data base64EncodedStringWithOptions:0])},
         {"metadata", {{"computer_use", {{"observation_id", observation_id}, {"screenshot_id", surface.screenshot_id},
             {"window", surface.window.id}, {"geometry", geometry(surface)}, {"cursor", cursor}}}}}};
diff --git a/src/adapters/computer_use/macos_input.mm b/src/adapters/computer_use/macos_input.mm
index 8af28e7ab..d5647fb3a 100644
--- a/src/adapters/computer_use/macos_input.mm
+++ b/src/adapters/computer_use/macos_input.mm
@@ -106,6 +106,25 @@ void mouse(CGEventType type, CGPoint point, CGMouseButton button, bool down, int
     if (event) CGEventSetIntegerValueField(event.get(), kCGMouseEventClickState, count);
     post(event.get(), UINT16_MAX, button, down);
 }
+void keyboard_feedback(const Observation& observation) {
+    const CGRect bounds = ax_bounds(observation.focus.get());
+    for (const auto& surface : observation.surfaces) {
+        if (!ax_descendant(observation.focus.get(), surface.window.root.get())) continue;
+        const CGRect visible = CGRectIntersection(bounds, surface.window.rect);
+        if (CGRectIsNull(visible) || CGRectIsEmpty(visible)) continue;
+        const CGPoint point{CGRectGetMidX(visible), CGRectGetMidY(visible)};
+        try {
+            validate_hit(point, surface);
+            pointer_show(point);
+            return;
+        } catch (const Error&) {
+            // Visual feedback must not change keyboard targeting or advertise
+            // a stale/covered control as the action's visible location.
+            break;
+        }
+    }
+    pointer_hide();
+}
 }
 
 KeyChord parse_key_chord(const std::string& value) {
@@ -211,9 +230,10 @@ void input_action(const std::string& action, const json& request, Observation& o
                 ax_check(AXUIElementPerformAction(element.ax.get(), native), "Perform control action");
             }
         }
-        pointer_show(CGPointMake(CGRectGetMidX(element.rect), CGRectGetMidY(element.rect)));
+        pointer_show(CGPointMake(CGRectGetMidX(element.rect), CGRectGetMidY(element.rect)), action == "perform_secondary_action");
     } else if (action == "press_key") {
         const auto chord = parse_key_chord(request.value("key", std::string{}));
+        keyboard_feedback(observation);
         for (auto key : chord.modifiers) {
             Ref<CGEventRef> event(CGEventCreateKeyboardEvent(nullptr, key, true));
             if (event) CGEventSetFlags(event.get(), chord.flags);
@@ -229,6 +249,7 @@ void input_action(const std::string& action, const json& request, Observation& o
             throw Error("invalid_argument", "text must be valid UTF-8 of at most 16 KiB.");
         NSString* value = ns(request["text"].get<std::string>());
         if (!value) throw Error("invalid_text", "Text must contain valid UTF-8.");
+        if (value.length) keyboard_feedback(observation);
         for (NSUInteger offset = 0; offset < value.length;) {
             focus_check(observation, true);
             NSUInteger count = std::min<NSUInteger>(32, value.length - offset);
diff --git a/src/adapters/computer_use/macos_pointer.mm b/src/adapters/computer_use/macos_pointer.mm
index 6829062e4..f5ae46f2e 100644
--- a/src/adapters/computer_use/macos_pointer.mm
+++ b/src/adapters/computer_use/macos_pointer.mm
@@ -13,6 +13,7 @@ - (BOOL)canBecomeMainWindow { return NO; }
 struct Pointer {
     __strong ACEComputerPointerPanel* panel = nil;
     __strong NSImageView* view = nil;
+    __strong NSTimer* press_timer = nil;
     bool visible = false, pressed = false;
     CGPoint point{};
     std::string style = "ace", color = "#2563eb";
@@ -54,11 +55,33 @@ void draw(CGContextRef context, const std::string& style, const std::string& col
         return YES;
     }];
 }
+void render(Pointer& pointer) {
+    pointer.view.image = image(pointer);
+    [pointer.panel displayIfNeeded];
+}
+void clear_press(Pointer& pointer) {
+    [pointer.press_timer invalidate];
+    pointer.press_timer = nil;
+    pointer.pressed = false;
+}
+void press_feedback(Pointer& pointer) {
+    clear_press(pointer);
+    pointer.pressed = true;
+    // Match ACECode's Windows feedback duration, not the physical button hold.
+    // Input down/up may occur within one AppKit display cycle.
+    pointer.press_timer = [NSTimer timerWithTimeInterval:0.25 repeats:NO block:^(NSTimer* timer) {
+        auto& current = state();
+        if (current.press_timer != timer) return;
+        clear_press(current);
+        if (current.visible) render(current);
+    }];
+    [NSRunLoop.mainRunLoop addTimer:pointer.press_timer forMode:NSRunLoopCommonModes];
+}
 }
 void pointer_configure(const std::string& style, const std::string& color) {
     if (!pointer_appearance::valid_style(style) || !pointer_appearance::normalize_color(color)) return;
     main_sync(^{ auto& pointer = state(); pointer.style = style; pointer.color = color;
-        if (pointer.view) pointer.view.image = image(pointer); });
+        if (pointer.view) render(pointer); });
 }
 void pointer_show(CGPoint point, bool pressed) {
     main_sync(^{
@@ -75,15 +98,20 @@ void pointer_show(CGPoint point, bool pressed) {
             pointer.view = [[NSImageView alloc] initWithFrame:NSMakeRect(0, 0, 64, 56)];
             pointer.panel.contentView = pointer.view;
         }
-        pointer.point = point; pointer.pressed = pressed; pointer.visible = true;
-        pointer.view.image = image(pointer);
+        if (pressed) press_feedback(pointer);
+        else if (!CGPointEqualToPoint(pointer.point, point)) clear_press(pointer);
+        pointer.point = point; pointer.visible = true;
         // AppKit has a bottom-left origin; Quartz/AX have a top-left origin.
         const CGFloat top = NSScreen.screens.firstObject.frame.size.height;
         [pointer.panel setFrameOrigin:NSMakePoint(point.x - 10, top - point.y - 46)];
         [pointer.panel orderFrontRegardless];
+        render(pointer);
     });
 }
-void pointer_hide() { main_sync(^{ state().visible = false; [state().panel orderOut:nil]; }); }
+void pointer_hide() {
+    main_sync(^{ auto& pointer = state(); pointer.visible = false;
+        clear_press(pointer); [pointer.panel orderOut:nil]; });
+}
 bool pointer_owns(CGWindowID id) {
     __block bool result = false;
     main_sync(^{ result = state().panel && static_cast<CGWindowID>(state().panel.windowNumber) == id; });
diff --git a/src/adapters/computer_use/native_windows.cpp b/src/adapters/computer_use/native_windows.cpp
index 08ac0bfb1..0c8b4befe 100644
--- a/src/adapters/computer_use/native_windows.cpp
+++ b/src/adapters/computer_use/native_windows.cpp
@@ -9,7 +9,7 @@
 #include "pointer_capture.hpp"
 #include "config/vocab/pointer_appearance.hpp"
 #include "utils/base64.hpp"
-
+#include "utils/generated_file_names.hpp"
 #include <algorithm>
 #include <chrono>
 #include <cmath>
@@ -1085,7 +1085,7 @@ struct NativeBackend::Impl {
                     descriptor["capture_method"] = pixels.method;
                     if (!fallback_reason.empty()) descriptor["fallback_reason"] = fallback_reason;
                     output["screenshots"].push_back(descriptor);
-                    attachments.push_back({{"name", "computer-use-" + id + "-" + std::to_string(index) + ".png"}, {"mime_type", "image/png"},
+                    attachments.push_back({{"name", generated_file_name("computer_use_" + id + "_" + std::to_string(index) + ".png")}, {"mime_type", "image/png"},
                         {"data_url", std::move(data_url)}, {"metadata", {{"computer_use", {{"observation_id", id}, {"screenshot_id", surface.screenshot_id},
                             {"window", reinterpret_cast<std::uintptr_t>(surface.relation.window)}, {"geometry", geometry(index)}, {"cursor", cursor}}}}}});
                 } catch (const NativeError& error) {
diff --git a/src/adapters/feedback/feedback_upload.cpp b/src/adapters/feedback/feedback_upload.cpp
index 24443b5b7..9e8553e8d 100644
--- a/src/adapters/feedback/feedback_upload.cpp
+++ b/src/adapters/feedback/feedback_upload.cpp
@@ -97,7 +97,7 @@ std::string filename_timestamp_from_created_at(const std::string& created_at) {
         }
     }
     if (digits.size() >= 14) {
-        return digits.substr(0, 8) + "-" + digits.substr(8, 6);
+        return digits.substr(0, 8) + "_" + digits.substr(8, 6);
     }
 
     auto now = std::chrono::system_clock::now();
@@ -109,7 +109,7 @@ std::string filename_timestamp_from_created_at(const std::string& created_at) {
     gmtime_r(&t, &tm);
 #endif
     std::ostringstream oss;
-    oss << std::put_time(&tm, "%Y%m%d-%H%M%S");
+    oss << std::put_time(&tm, "%Y%m%d_%H%M%S");
     return oss.str();
 }
 
@@ -148,7 +148,7 @@ std::string default_output_dir() {
     fs::path dir = fs::temp_directory_path(ec);
     if (ec) dir = fs::current_path(ec);
     if (dir.empty()) dir = ".";
-    return path_to_utf8(dir / "acecode-feedback");
+    return path_to_utf8(dir / "acecode_feedback");
 }
 
 std::string trim_ascii_whitespace(std::string value) {
@@ -189,15 +189,17 @@ std::string current_login_name() {
 void append_filename_component(std::string& out, const std::string& value) {
     const std::string trimmed = trim_ascii_whitespace(value);
     if (trimmed.empty()) return;
-    out.push_back('-');
+    out.push_back('_');
     out += sanitize_feedback_filename_component(trimmed);
 }
 
 bool is_rotated_log_filename(const fs::path& path, const std::string& base_name) {
     const std::string name = path.filename().string();
-    const std::string prefix = base_name + "-";
-    return name.rfind(prefix, 0) == 0 &&
-           name.size() > prefix.size() + std::string(".log").size() &&
+    const std::string old_prefix = base_name + "-";
+    std::string new_prefix = base_name + "_";
+    std::replace(new_prefix.begin(), new_prefix.end(), '-', '_');
+    return (name.rfind(old_prefix, 0) == 0 || name.rfind(new_prefix, 0) == 0) &&
+           name.size() > old_prefix.size() + std::string(".log").size() &&
            name.substr(name.size() - 4) == ".log";
 }
 
@@ -226,17 +228,17 @@ std::string sanitize_feedback_filename_component(const std::string& value) {
     const char* hex = "0123456789abcdef";
     for (char ch : value) {
         const unsigned char c = static_cast<unsigned char>(ch);
-        if (std::isalnum(c) != 0 || ch == '-' || ch == '_' || ch == '.') {
+        if (std::isalnum(c) != 0 || ch == '_' || ch == '.') {
             out.push_back(ch);
         } else if (c >= 0x80) {
             out.push_back('x');
             out.push_back(hex[(c >> 4) & 0x0F]);
             out.push_back(hex[c & 0x0F]);
         } else {
-            out.push_back('-');
+            out.push_back('_');
         }
     }
-    while (!out.empty() && (out.front() == '.' || out.front() == '-')) {
+    while (!out.empty() && (out.front() == '.' || out.front() == '_')) {
         out.erase(out.begin());
     }
     if (out.empty()) out = "session";
@@ -249,8 +251,8 @@ std::string make_feedback_package_filename(const std::string& session_id,
                                            const std::string& platform,
                                            const std::string& computer_name,
                                            const std::string& login_name) {
-    std::string filename = "acecode-feedback-" +
-        sanitize_feedback_filename_component(session_id) + "-" +
+    std::string filename = "acecode_feedback_" +
+        sanitize_feedback_filename_component(session_id) + "_" +
         filename_timestamp_from_created_at(created_at);
     append_filename_component(filename, platform);
     append_filename_component(filename, computer_name);
diff --git a/src/adapters/feedback/feedback_upload.hpp b/src/adapters/feedback/feedback_upload.hpp
index e66b04db6..d5accc2af 100644
--- a/src/adapters/feedback/feedback_upload.hpp
+++ b/src/adapters/feedback/feedback_upload.hpp
@@ -117,7 +117,7 @@ std::string make_feedback_package_filename(const std::string& session_id,
                                            const std::string& platform = {},
                                            const std::string& computer_name = {},
                                            const std::string& login_name = {});
-// 找 logs_dir 下 "<base_name>-<date>.log" 里最近修改的一个(Logger 的滚动命名)。
+// 找 logs_dir 下新 "<base_name>_<date>.log" / 旧连字符名称里最近修改的日志。
 std::optional<std::filesystem::path> latest_rotated_log_path(
     const std::filesystem::path& logs_dir, const std::string& base_name);
 std::optional<std::filesystem::path> latest_desktop_log_path(
@@ -134,7 +134,7 @@ std::vector<FeedbackLogSource> collect_runtime_log_sources(
 std::vector<FeedbackLogSource> collect_tui_runtime_log_sources(
     const std::filesystem::path& logs_dir);
 
-// 找 logs_dir 下最近 window 内写过的全部 "upgrade-<date>-<pid>.log",按修改时间
+// 找 logs_dir 下最近 window 内写过的全部新旧命名升级日志,按修改时间
 // 从旧到新排成一个合并包(条目名固定 logs/upgrade.log.tail.txt)。窗口内一个都
 // 没有返回 nullopt:更早的升级记录不做兜底,反馈里没有升级条目就意味着这三天
 // 没跑过升级。
diff --git a/src/adapters/themes/theme_store.cpp b/src/adapters/themes/theme_store.cpp
index 5e8d2eebf..4ae05a7bf 100644
--- a/src/adapters/themes/theme_store.cpp
+++ b/src/adapters/themes/theme_store.cpp
@@ -1,12 +1,12 @@
 #include "theme_store.hpp"
 #include "utils/base64.hpp"
 #include "theme_package.hpp"
-
 #include "utils/semver.hpp"
 #include "image/image_processor.hpp"
 #include "utils/atomic_file.hpp"
 #include "utils/sha256.hpp"
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 #include "utils/uuid.hpp"
 
 #include <algorithm>
@@ -127,7 +127,7 @@ std::string export_filename(const json& definition) {
     }
     while (!name.empty() && (name.back() == ' ' || name.back() == '.')) name.pop_back();
     if (name.empty()) name = definition.at("id").get<std::string>();
-    return "ACECode-" + name + ".zip";
+    return generated_file_name("ACECode_" + name + ".zip");
 }
 
 void replace_file(const fs::path& source, const fs::path& destination) {
@@ -400,7 +400,7 @@ ThemeStore::ThemeStore(fs::path root, UpdateBaseProvider update_base, ThemeTrans
         return upgrade::download_to_file(url, path, 120000, progress, cancel);
     };
     try {
-        auto cached = read_json(root_ / "catalog-v2.json");
+        auto cached = read_json(compatible_generated_path(root_, "catalog-v2.json"));
         if (cached.value("source_base_url", "") == base_ && valid_theme_catalog(cached.at("catalog"))) {
             catalog_ = std::move(cached["catalog"]);
         }
@@ -442,7 +442,7 @@ json ThemeStore::catalog(bool refresh) {
             if (!valid_theme_catalog(parsed))
                 throw ThemeError(503, "THEME_CATALOG_UNAVAILABLE", "Invalid theme catalog response");
             catalog_ = std::move(parsed);
-            write_file(root_ / "catalog-v2.json", json{{"source_base_url", base_}, {"catalog", catalog_}}.dump());
+            write_file(compatible_generated_path(root_, "catalog-v2.json"), json{{"source_base_url", base_}, {"catalog", catalog_}}.dump());
         } catch (const std::exception& error) { offline = true; failure_message = error.what(); }
         catch (...) { offline = true; }
     }
@@ -504,7 +504,7 @@ json ThemeStore::claim_startup_theme() {
     std::error_code ec;
     fs::create_directories(root_, ec);
     if (ec) throw ThemeError(500, "THEME_SAVE_FAILED", "Could not save startup theme attempt");
-    const bool claimed = fs::create_directory(root_ / ".national-day-2026-attempted", ec);
+    const bool claimed = fs::create_directory(compatible_generated_path(root_, ".national-day-2026-attempted"), ec);
     if (ec) throw ThemeError(500, "THEME_SAVE_FAILED", "Could not save startup theme attempt");
     return {{"id", kNationalDayThemeId}, {"claimed", claimed}};
 }
@@ -649,7 +649,7 @@ std::string ThemeStore::image(const std::string& id, const std::string& kind) {
     if (kind != "thumbnail") throw ThemeError(404, "THEME_NOT_INSTALLED", "Theme is not installed");
     const auto e = descriptor(id);
     std::lock_guard<std::mutex> preview_lock(preview_mu_);
-    const auto file = root_ / "previews" / (id + "-" + e.at("version").get<std::string>() + ".png");
+    const auto file = compatible_generated_path(root_ / "previews", id + "-" + e.at("version").get<std::string>() + ".png");
     if (!matches_file(file, e.at("thumbnail"))) {
         fs::create_directories(file.parent_path());
         auto tmp = file; tmp += ".download";
@@ -810,7 +810,7 @@ void ThemeStore::run_export(const std::shared_ptr<ThemeExportJob>& job) {
         if (!job->destination.empty()) {
             update({{"state", "saving"}, {"progress", nullptr}});
             temporary_destination = job->destination;
-            temporary_destination += ".acecode-" + job_id + ".tmp";
+            temporary_destination += ".acecode_" + generated_file_name(job_id) + ".tmp";
             if (fs::exists(temporary_destination)) throw ThemeError(409, "THEME_SAVE_FAILED", "Theme save temporary file already exists");
             std::ofstream output(temporary_destination, std::ios::binary | std::ios::trunc);
             if (!output) throw ThemeError(500, "THEME_SAVE_FAILED", "Could not create theme package", path_to_utf8(job->destination));
@@ -893,7 +893,7 @@ json ThemeStore::remove_local(const std::string& id, const std::function<void()>
             } catch (...) { /* An unidentifiable legacy archive is not safe to claim. */ }
         }
     }
-    const auto quarantine = checked_path(root_, ".deleted-" + generate_uuid_v7());
+    const auto quarantine = checked_path(root_, ".deleted_" + generated_file_name(generate_uuid_v7()));
     std::vector<std::pair<fs::path, fs::path>> moved;
     try {
         fs::create_directory(quarantine);
diff --git a/src/adapters/tool/agent_browser/browser_tools.cpp b/src/adapters/tool/agent_browser/browser_tools.cpp
index 2b9efcc62..fe46a7491 100644
--- a/src/adapters/tool/agent_browser/browser_tools.cpp
+++ b/src/adapters/tool/agent_browser/browser_tools.cpp
@@ -1117,11 +1117,11 @@ ToolImpl wait_tool() {
 }
 
 std::string safe_file_name(std::string value) {
-    if (value.empty()) value = "browser-screenshot.png";
+    if (value.empty()) value = "browser_screenshot.png";
     value = std::filesystem::path(value).filename().string();
     for (char& ch : value) {
         if (!std::isalnum(static_cast<unsigned char>(ch)) &&
-            ch != '-' && ch != '_' && ch != '.') ch = '-';
+            ch != '-' && ch != '_' && ch != '.') ch = '_';
     }
     if (value.size() < 4 || value.substr(value.size() - 4) != ".png") value += ".png";
     return value;
@@ -1173,7 +1173,7 @@ ToolImpl screenshot_tool() {
                     "Browser returned invalid PNG screenshot data");
             }
             const std::filesystem::path root = context.scratch_dir.empty()
-                ? std::filesystem::temp_directory_path() / "acecode-agent-browser"
+                ? std::filesystem::temp_directory_path() / "acecode_agent_browser"
                 : acecode::path_from_utf8(context.scratch_dir);
             std::error_code filesystem_error;
             std::filesystem::create_directories(root, filesystem_error);
diff --git a/src/adapters/tool/bash_output_capture.cpp b/src/adapters/tool/bash_output_capture.cpp
index c41f56c08..975eb1354 100644
--- a/src/adapters/tool/bash_output_capture.cpp
+++ b/src/adapters/tool/bash_output_capture.cpp
@@ -2,6 +2,7 @@
 
 #include "session/tool_result_storage.hpp"
 #include "utils/encoding.hpp"
+#include "utils/generated_file_names.hpp"
 #include "utils/stream_processing.hpp"
 #include "utils/utf8_path.hpp"
 #include "utils/uuid.hpp"
@@ -46,7 +47,7 @@ bool BashOutputCapture::start_file() {
             fail("Failed to locate temporary shell output storage: " + ec.message());
             return false;
         }
-        directory /= "acecode-tool-results";
+        directory /= "acecode_tool_results";
     } else {
         directory = path_from_utf8(tool_results_dir_);
     }
@@ -55,7 +56,7 @@ bool BashOutputCapture::start_file() {
         fail("Failed to create shell output storage: " + ec.message());
         return false;
     }
-    const auto path = directory / ("bash-" + generate_uuid() + ".txt");
+    const auto path = directory / generated_file_name("bash_" + generate_uuid() + ".txt");
     filepath_ = path_to_utf8(path);
     file_.open(path, std::ios::binary | std::ios::out);
     if (!file_) {
diff --git a/src/adapters/tool/ios_simulator/tool_actions.cpp b/src/adapters/tool/ios_simulator/tool_actions.cpp
index d4fc0a621..673aa9930 100644
--- a/src/adapters/tool/ios_simulator/tool_actions.cpp
+++ b/src/adapters/tool/ios_simulator/tool_actions.cpp
@@ -192,7 +192,7 @@ ToolResult action_screenshot(const Target& target, const ToolContext& ctx) {
                     std::to_string(height) + " points (" + orientation_name(rotation) +
                     "). 1 image pixel = 1 point; use these coordinates for tap/swipe.";
     result.attachments = json::array({{
-        {"name", "simulator-" + target.device.udid.substr(0, 8) + "-" + std::to_string(stamp) + ".jpg"},
+        {"name", "simulator_" + target.device.udid.substr(0, 8) + "_" + std::to_string(stamp) + ".jpg"},
         {"mime_type", "image/jpeg"},
         {"data_url", "data:image/jpeg;base64," + base64_encode(response.binary)},
     }});
diff --git a/src/adapters/tool/mcp_manager.cpp b/src/adapters/tool/mcp_manager.cpp
index ff0bb9af5..8d8facaa1 100644
--- a/src/adapters/tool/mcp_manager.cpp
+++ b/src/adapters/tool/mcp_manager.cpp
@@ -943,7 +943,7 @@ ToolResult McpManager::invoke(const std::weak_ptr<State>& weak_state,
                         const std::string mime = item.value("mimeType", item.value("mime_type", std::string{"image/png"}));
                         std::string name = item.value("name", std::string{});
                         if (name.empty()) {
-                            name = "mcp-image-" + std::to_string(image_index) + extension_for_mcp_mime(mime);
+                            name = "mcp_image_" + std::to_string(image_index) + extension_for_mcp_mime(mime);
                         }
                         attachments.push_back(nlohmann::json{
                             {"name", name},
diff --git a/src/adapters/tool/tool_rewrites.cpp b/src/adapters/tool/tool_rewrites.cpp
index 0cd672c1b..d6ce34ca1 100644
--- a/src/adapters/tool/tool_rewrites.cpp
+++ b/src/adapters/tool/tool_rewrites.cpp
@@ -3,6 +3,7 @@
 #include "utils/atomic_file.hpp"
 #include "utils/logger.hpp"
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 
 #include <nlohmann/json.hpp>
 
@@ -31,7 +32,7 @@ std::string trim_ascii(const std::string& value) {
 } // namespace
 
 std::string settings_path(const std::string& data_dir) {
-    return path_to_utf8(path_from_utf8(data_dir) / kSettingsFileName);
+    return path_to_utf8(compatible_generated_path(path_from_utf8(data_dir), kSettingsFileName));
 }
 
 ToolRewriteSettings default_settings() {
diff --git a/src/adapters/upgrade/apply.cpp b/src/adapters/upgrade/apply.cpp
index 4cb69b9e0..92969c4e2 100644
--- a/src/adapters/upgrade/apply.cpp
+++ b/src/adapters/upgrade/apply.cpp
@@ -38,7 +38,7 @@ namespace fs = std::filesystem;
 namespace acecode::upgrade {
 namespace {
 
-constexpr const char* kUpdateRunnerDirName = ".acecode-update-runner";
+constexpr const char* kUpdateRunnerDirName = ".acecode_update_runner";
 
 // 这里的错误文本会经 run_upgrade_command 成为 GUI 升级任务的 job.error。MSVC 的
 // ec.message() 与 path::string() 走 ANSI 代码页(中文 Windows 为 GBK):OS 文本
@@ -326,9 +326,9 @@ fs::path current_executable_path(const std::string& argv0) {
 fs::path make_runner_path(unsigned long pid, const fs::path& install_dir) {
     fs::path runner_dir = install_dir / kUpdateRunnerDirName;
 #ifdef _WIN32
-    return runner_dir / ("acecode-update-runner-" + std::to_string(pid) + ".exe");
+    return runner_dir / ("acecode_update_runner_" + std::to_string(pid) + ".exe");
 #else
-    return runner_dir / ("acecode-update-runner-" + std::to_string(pid));
+    return runner_dir / ("acecode_update_runner_" + std::to_string(pid));
 #endif
 }
 
diff --git a/src/adapters/upgrade/diagnostics.cpp b/src/adapters/upgrade/diagnostics.cpp
index e24f1f029..93a9ca17d 100644
--- a/src/adapters/upgrade/diagnostics.cpp
+++ b/src/adapters/upgrade/diagnostics.cpp
@@ -2,6 +2,7 @@
 
 #include "apply.hpp"
 #include "utils/encoding.hpp"
+#include "utils/generated_file_names.hpp"
 #include "utils/logger.hpp"
 #include "utils/paths.hpp"
 #include "utils/utf8_path.hpp"
@@ -99,7 +100,7 @@ DiagnosticLog::DiagnosticLog(const std::string& operation,
         operation_id_ = pid + "-" + now + "-" + std::to_string(++next_operation);
         const auto root = directory.empty()
             ? path_from_utf8(get_acecode_dir()) / "logs" : directory;
-        path_ = root / ("upgrade-" + now.substr(0, 10) + "-" + pid + ".log");
+        path_ = root / generated_file_name("upgrade_" + now.substr(0, 10) + "_" + pid + ".log");
         std::error_code ec;
         std::filesystem::create_directories(root, ec);
         if (ec) {
diff --git a/src/adapters/upgrade/macos_app_installer.mm b/src/adapters/upgrade/macos_app_installer.mm
index 31745df91..8e7dbdc14 100644
--- a/src/adapters/upgrade/macos_app_installer.mm
+++ b/src/adapters/upgrade/macos_app_installer.mm
@@ -2,6 +2,7 @@
 #import <Security/Security.h>
 
 #include "macos_app_installer.hpp"
+#include "utils/generated_file_names.hpp"
 #include "diagnostics.hpp"
 
 #include "macos_bundle.hpp"
@@ -416,7 +417,7 @@ bool install_macos_app_update(const fs::path& installed_bundle,
         // The old bundle may still own running processes until restart. Keep
         // its actual app name stable for macOS permission/display-name lookup.
         MacosAppUpdateWorkspace workspace(applications_dir /
-            (".acecode-update-" + std::string([[[NSUUID UUID] UUIDString] UTF8String])));
+            generated_file_name(".acecode_update_" + std::string([[[NSUUID UUID] UUIDString] UTF8String])));
         if (!workspace.create(error)) return false;
         const fs::path temporary_path = workspace.staged_bundle();
         const fs::path previous_path = workspace.previous_bundle();
diff --git a/src/adapters/upgrade/macos_bundle.cpp b/src/adapters/upgrade/macos_bundle.cpp
index 280f6dfeb..90e27d9a1 100644
--- a/src/adapters/upgrade/macos_bundle.cpp
+++ b/src/adapters/upgrade/macos_bundle.cpp
@@ -106,6 +106,7 @@ bool macos_app_install_path_is_safe(const fs::path& bundle, std::string* error)
         std::transform(name.begin(), name.end(), name.begin(),
             [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
         if (name == "apptranslocation" || name.rfind(".acecode-update-", 0) == 0 ||
+            name.rfind(".acecode_update_", 0) == 0 ||
             fs::path(name).extension() == ".app") return reject();
     }
     std::error_code ec;
diff --git a/src/adapters/upgrade/upgrade.cpp b/src/adapters/upgrade/upgrade.cpp
index dd44cf82e..d7ffff0a6 100644
--- a/src/adapters/upgrade/upgrade.cpp
+++ b/src/adapters/upgrade/upgrade.cpp
@@ -37,7 +37,7 @@ constexpr int kNoUpgradeTimeoutMs = 0;
 fs::path unique_update_workspace_dir() {
     const auto ticks = std::chrono::steady_clock::now().time_since_epoch().count();
     return upgrade_workspace_base_dir() /
-           ("acecode-update-" + std::to_string(current_process_id()) + "-" +
+           ("acecode_update_" + std::to_string(current_process_id()) + "_" +
             std::to_string(ticks));
 }
 
diff --git a/src/apps/daemon/startup_diagnostics.cpp b/src/apps/daemon/startup_diagnostics.cpp
index 9960eab66..801277bbf 100644
--- a/src/apps/daemon/startup_diagnostics.cpp
+++ b/src/apps/daemon/startup_diagnostics.cpp
@@ -47,7 +47,7 @@ void append_startup_diagnostic(const std::string& message) {
     fs::create_directories(run_dir, ec);
     if (ec) return;
 
-    std::ofstream out(run_dir / "daemon-startup.log",
+    std::ofstream out(run_dir / "daemon_startup.log",
                       std::ios::binary | std::ios::app);
     if (!out.is_open()) return;
     out << local_timestamp() << " elapsed_ms=" << startup_elapsed_ms()
diff --git a/src/apps/desktop/context_items.cpp b/src/apps/desktop/context_items.cpp
index e37a7c970..b5f19de62 100644
--- a/src/apps/desktop/context_items.cpp
+++ b/src/apps/desktop/context_items.cpp
@@ -1,6 +1,7 @@
 #include "context_items.hpp"
 
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 #include "utils/base64.hpp"
 #include "platform/clipboard.hpp"
 #include "utils/uuid.hpp"
@@ -155,13 +156,13 @@ ContextItemsResult store_context_data_files(
                 if (static_cast<unsigned char>(ch) < 32 || std::string("<>:\"|?*").find(ch) != std::string::npos) ch = '_';
             }
             while (!name.empty() && (name.back() == '.' || name.back() == ' ')) name.pop_back();
-            if (name.empty()) name = "clipboard-file";
+            if (name.empty()) name = "clipboard_file";
             // Avoid Windows device filenames while keeping ordinary names intact.
             std::string stem = name.substr(0, name.find('.'));
             std::transform(stem.begin(), stem.end(), stem.begin(), [](unsigned char ch) { return static_cast<char>(std::toupper(ch)); });
             if (stem == "CON" || stem == "PRN" || stem == "AUX" || stem == "NUL"
                 || (stem.size() == 4 && (stem.substr(0, 3) == "COM" || stem.substr(0, 3) == "LPT") && stem[3] >= '1' && stem[3] <= '9')) name = '_' + name;
-            const auto folder = root / generate_uuid();
+            const auto folder = root / generated_file_name(generate_uuid());
             if (!fs::create_directory(folder)) throw std::runtime_error("cannot create context data directory");
             created.push_back(folder);
             const auto path = folder / path_from_utf8(name);
diff --git a/src/apps/desktop/daemon_pool.cpp b/src/apps/desktop/daemon_pool.cpp
index 62043cdce..50790214b 100644
--- a/src/apps/desktop/daemon_pool.cpp
+++ b/src/apps/desktop/daemon_pool.cpp
@@ -283,7 +283,8 @@ ExistingDaemonProbeResult inspect_existing_daemon(
 
     // One-release migration for the pre-manifest Desktop daemon.
     const bool legacy_reserved_dir =
-        std::filesystem::path(req.run_dir).filename() == "desktop-shared";
+        (std::filesystem::path(req.run_dir).filename() == "desktop-shared" ||
+         std::filesystem::path(req.run_dir).filename() == "desktop_shared");
     if (!snapshot.desktop_managed.has_value() && !health_managed &&
         legacy_reserved_dir &&
         acecode::daemon::process_is_acecode_daemon(result.pid)) {
diff --git a/src/apps/desktop/desktop_pet.cpp b/src/apps/desktop/desktop_pet.cpp
index eb64682e3..ef5308238 100644
--- a/src/apps/desktop/desktop_pet.cpp
+++ b/src/apps/desktop/desktop_pet.cpp
@@ -229,7 +229,7 @@ struct PetController : std::enable_shared_from_this<PetController> {
     bool pinned = true;
     bool drag_tracking = false;   // 系统标题栏拖动循环进行中,陪伴宠物据此做左右跑动画
     DesktopPetDragTracker drag_tracker;
-    int docked_side = 0;          // 鲸鱼娘吸附在工作区左(-1)/右(+1)边,0 = 未吸附
+    int docked_side = 0;          // 陪伴宠物吸附在工作区左(-1)/右(+1)边,0 = 未吸附
     DesktopPetRect resize_start{};
     POINT resize_cursor{};
 
@@ -243,11 +243,13 @@ struct PetController : std::enable_shared_from_this<PetController> {
         if (pet_kind == kind) return;
         const bool same_page = pet_kind != "office" && kind != "office";
         pet_kind = kind;
-        if (kind != "whale") docked_side = 0;   // 只有鲸鱼娘有趴边偷看的样子
+        if (!desktop_pet_has_edge_peek(kind)) docked_side = 0;   // 虚拟办公室没有趴边偷看的样子
         if (!webview || closed) return;
         hit_overlays.clear();
-        if (same_page) publish_character();
-        else {
+        if (same_page) {
+            publish_character();
+            publish_dock();   // 贴着边换宠物:新宠物接着趴在同一条边上
+        } else {
             page_ready = false;
             load_page();
         }
@@ -283,12 +285,12 @@ struct PetController : std::enable_shared_from_this<PetController> {
         webview->PostWebMessageAsJson(utf8_to_wide(event.dump()).c_str());
     }
 
-    // 拖动松手后:鲸鱼娘离左/右边足够近就贴到那条边,页面换成趴边偷看;
+    // 拖动松手后:陪伴宠物离左/右边足够近就贴到那条边,页面换成趴边偷看;
     // 其它情况把窗口收回工作区,头顶的会话卡片不会被屏幕边截掉。
     void settle_dock() {
         const DesktopPetRect work = window_work_area();
         const DesktopPetRect current = window_rect();
-        docked_side = pet_kind == "whale" ? desktop_pet_dock_side(current, work) : 0;
+        docked_side = desktop_pet_has_edge_peek(pet_kind) ? desktop_pet_dock_side(current, work) : 0;
         const DesktopPetRect next = docked_side ? dock_desktop_pet(current, work, docked_side)
                                                 : keep_desktop_pet_in_work_area(current, work);
         if (next.x != current.x || next.y != current.y) apply_placement({next, placement.scale});
diff --git a/src/apps/desktop/desktop_pet_layout.cpp b/src/apps/desktop/desktop_pet_layout.cpp
index 04e83100a..c4e85395a 100644
--- a/src/apps/desktop/desktop_pet_layout.cpp
+++ b/src/apps/desktop/desktop_pet_layout.cpp
@@ -176,6 +176,9 @@ std::vector<DesktopPetOverlay> desktop_pet_overlays_from_message(const nlohmann:
     if (const auto it = message.find("rect"); it != message.end() && overlay_from_json(*it, rect)) {
         overlays.push_back(rect);
     }
+    if (const auto it = message.find("grip"); it != message.end() && overlay_from_json(*it, rect)) {
+        overlays.push_back(rect);
+    }
     if (const auto it = message.find("bubbles"); it != message.end() && it->is_array()) {
         for (const auto& item : *it) {
             if (overlays.size() >= kDesktopPetMaxOverlays) break;
@@ -185,10 +188,15 @@ std::vector<DesktopPetOverlay> desktop_pet_overlays_from_message(const nlohmann:
     return overlays;
 }
 
-bool desktop_pet_resize_grip_hit_test(double width, double height, double x, double y) {
+bool desktop_pet_resize_grip_hit_test(double width, double height, double x, double y,
+                                      const DesktopPetOverlay* grip) {
     if (!std::isfinite(width) || !std::isfinite(height) ||
         !std::isfinite(x) || !std::isfinite(y) ||
         width <= 0 || height <= 0 || x < 0 || y < 0 || x >= width || y >= height) return false;
+    if (grip) {
+        return x >= (*grip)[0] * width && x < (*grip)[2] * width &&
+               y >= (*grip)[1] * height && y < (*grip)[3] * height;
+    }
     const double left = 11.0 * width / kDesktopPetSceneWidth;
     const double top = 112.0 * height / kDesktopPetSceneHeight;
     return x >= left && x < left + 16.0 && y >= top && y < top + 16.0;
diff --git a/src/apps/desktop/desktop_pet_layout.hpp b/src/apps/desktop/desktop_pet_layout.hpp
index e34d2e452..7e3061ac8 100644
--- a/src/apps/desktop/desktop_pet_layout.hpp
+++ b/src/apps/desktop/desktop_pet_layout.hpp
@@ -10,6 +10,7 @@
 // 透明角落的点击会落到后面的窗口上。
 
 #include <array>
+#include <string_view>
 #include <vector>
 
 #include <nlohmann/json_fwd.hpp>
@@ -71,7 +72,7 @@ std::vector<DesktopPetPoint> desktop_pet_hit_polygon(double scale);
 using DesktopPetOverlay = std::array<double, 4>;
 inline constexpr std::size_t kDesktopPetMaxOverlays = 24;
 
-// 解析页面发来的 {"type":"overlay","controls":[...]|null,"rect":[...]|null,"bubbles":[[...],...]}:
+// 解析页面发来的 {"type":"overlay","controls":[...]|null,"rect":[...]|null,"grip":[...]|null,"bubbles":[[...],...]}:
 // 非数字 / 非有限值 / 空矩形整条丢弃,坐标夹到 [0, 1],最多保留 kDesktopPetMaxOverlays 个。
 std::vector<DesktopPetOverlay> desktop_pet_overlays_from_message(const nlohmann::json& message);
 
@@ -80,11 +81,12 @@ std::vector<DesktopPetOverlay> desktop_pet_overlays_from_message(const nlohmann:
 bool desktop_pet_hit_test(double scale, int width, int height,
                           const std::vector<DesktopPetOverlay>& overlays, double x, double y, bool office = true);
 
-// macOS uses logical points (CSS pixels). The handle's position scales with the
-// viewport, but its 16px target does not; keep this aligned with .grip in the page.
-bool desktop_pet_resize_grip_hit_test(double width, double height, double x, double y);
+// macOS uses logical points (CSS pixels). Companions report their visible grip;
+// nullptr retains the Office page's fixed position and 16px target.
+bool desktop_pet_resize_grip_hit_test(double width, double height, double x, double y,
+                                      const DesktopPetOverlay* grip = nullptr);
 
-// 鲸鱼娘拖到工作区左/右边缘松手时吸附,改成趴在屏幕边上偷看的样子。
+// 陪伴宠物拖到工作区左/右边缘松手时吸附,改成趴在屏幕边上偷看的样子。
 // 窗口中心离左/右边缘不超过窗口宽度的 1/4(或已越过边缘)返回 -1(左)/ +1(右),否则 0。
 // 1/4 大约是宠物身体碰到屏幕边的位置(身体宽约窗口的 40%,居中)。
 int desktop_pet_dock_side(const DesktopPetRect& window, const DesktopPetRect& work_area);
@@ -110,6 +112,11 @@ inline constexpr std::array<DesktopPetKind, 4> kDesktopPetKinds{{
     {"whale", "鲸鱼娘", "Whale Girl"},
 }};
 
+// 有趴边偷看素材(peek.png)、能吸附到屏幕左/右边的宠物:三只陪伴宠物都有,虚拟办公室没有。
+inline bool desktop_pet_has_edge_peek(std::string_view kind) {
+    return kind == "clippy" || kind == "rover" || kind == "whale";
+}
+
 // 拖动陪伴宠物时按窗口横向位移判断朝向(仿 Codex:往右拖向右跑,往左拖向左跑)。
 // 相对上次报告的位置累计超过 threshold 才报一次 -1(左)/ +1(右),
 // 小于阈值的抖动与纯竖直移动返回 0;每次报告后以当前位置为新起点。
diff --git a/src/apps/desktop/desktop_pet_mac.mm b/src/apps/desktop/desktop_pet_mac.mm
index e48f65de9..38938b445 100644
--- a/src/apps/desktop/desktop_pet_mac.mm
+++ b/src/apps/desktop/desktop_pet_mac.mm
@@ -133,6 +133,7 @@ explicit PetController(WebHost& owner) : host_(owner) {}
     std::string pet_kind_ = "office";
     std::vector<DesktopPetOverlay> overlays_;
     std::vector<DesktopPetOverlay> foreground_overlays_;
+    DesktopPetOverlay resize_grip_{};
     NSPanel* panel_ = nil;
     WKWebView* webview_ = nil;
     WKUserContentController* content_ = nil;
@@ -151,7 +152,7 @@ explicit PetController(WebHost& owner) : host_(owner) {}
     bool resizing_ = false;
     bool dragging_ = false;
     DesktopPetDragTracker drag_tracker_;   // 陪伴宠物按拖动方向播放左右跑动画
-    int docked_side_ = 0;                  // 鲸鱼娘吸附在工作区左(-1)/右(+1)边,0 = 未吸附
+    int docked_side_ = 0;                  // 陪伴宠物吸附在工作区左(-1)/右(+1)边,0 = 未吸附
     bool mouse_pressed_ = false;
     bool owns_cursor_ = false;
     bool pinned_ = true;
@@ -426,6 +427,7 @@ - (void)choose:(NSMenuItem*)item {
     end_gesture();
     overlays_.clear();
     foreground_overlays_.clear();
+    resize_grip_ = {};
     page_ready_ = false;
     load_page();
 }
@@ -452,13 +454,16 @@ - (void)choose:(NSMenuItem*)item {
     if (pet_kind_ == kind) return;
     const bool same_page = pet_kind_ != "office" && kind != "office";
     pet_kind_ = kind;
-    if (kind != "whale") docked_side_ = 0;   // 只有鲸鱼娘有趴边偷看的样子
+    if (!desktop_pet_has_edge_peek(kind)) docked_side_ = 0;   // 虚拟办公室没有趴边偷看的样子
     if (!webview_ || closed_) return;
     end_gesture();
     overlays_.clear();
     foreground_overlays_.clear();
-    if (same_page) publish_character();
-    else {
+    resize_grip_ = {};
+    if (same_page) {
+        publish_character();
+        publish_dock();   // 贴着边换宠物:新宠物接着趴在同一条边上
+    } else {
         page_ready_ = false;
         load_page();
     }
@@ -476,12 +481,12 @@ - (void)choose:(NSMenuItem*)item {
     deliver({{"type", "pet-dock"}, {"side", docked_side_ < 0 ? "left" : docked_side_ > 0 ? "right" : ""}});
 }
 
-// 拖动松手后:鲸鱼娘离左/右边足够近就贴到那条边,页面换成趴边偷看;
+// 拖动松手后:陪伴宠物离左/右边足够近就贴到那条边,页面换成趴边偷看;
 // 其它情况把窗口收回可见区域,头顶的会话卡片不会被屏幕边截掉。
 void PetController::settle_dock() {
     const DesktopPetRect work = work_area();
     const DesktopPetRect current = window_rect();
-    docked_side_ = pet_kind_ == "whale" ? desktop_pet_dock_side(current, work) : 0;
+    docked_side_ = desktop_pet_has_edge_peek(pet_kind_) ? desktop_pet_dock_side(current, work) : 0;
     const DesktopPetRect next = docked_side_ ? dock_desktop_pet(current, work, docked_side_)
                                              : keep_desktop_pet_in_work_area(current, work);
     if (next.x != current.x || next.y != current.y) apply_placement({next, current_scale()});
@@ -566,10 +571,13 @@ - (void)choose:(NSMenuItem*)item {
     }
     if (type == "overlay") {
         overlays_ = desktop_pet_overlays_from_message(value);
+        const auto grips = desktop_pet_overlays_from_message({{"rect", value.value("grip", nlohmann::json())}});
+        resize_grip_ = grips.empty() ? DesktopPetOverlay{} : grips.front();
         // Bubbles are below the handle and pointer-transparent. Controls and
         // the member list/notice are above it and must retain their own cursor.
         auto foreground = value;
         foreground.erase("bubbles");
+        foreground.erase("grip");
         foreground_overlays_ = desktop_pet_overlays_from_message(foreground);
         return;
     }
@@ -783,7 +791,8 @@ - (void)choose:(NSMenuItem*)item {
     const NSRect frame = panel_.frame;
     const double x = mouse.x - frame.origin.x;
     const double y = frame.origin.y + frame.size.height - mouse.y;
-    if (!desktop_pet_resize_grip_hit_test(frame.size.width, frame.size.height, x, y)) return false;
+    if (!page_ready_ || !desktop_pet_resize_grip_hit_test(frame.size.width, frame.size.height, x, y,
+                                                        pet_kind_ == "office" ? nullptr : &resize_grip_)) return false;
     return std::none_of(foreground_overlays_.begin(), foreground_overlays_.end(), [&](const auto& rect) {
         return x >= rect[0] * frame.size.width && x < rect[2] * frame.size.width &&
                y >= rect[1] * frame.size.height && y < rect[3] * frame.size.height;
diff --git a/src/apps/desktop/desktop_pet_mac_support.hpp b/src/apps/desktop/desktop_pet_mac_support.hpp
index d8c60222b..611622c00 100644
--- a/src/apps/desktop/desktop_pet_mac_support.hpp
+++ b/src/apps/desktop/desktop_pet_mac_support.hpp
@@ -5,6 +5,7 @@
 // 只由 desktop_pet_mac.mm 包含(ObjC++,ARC);从那里拆出来是为了守住单文件 1000 行上限。
 
 #include "desktop_pet_layout.hpp"
+#include "utils/generated_file_names.hpp"
 #include "platform/native_ui/strings.hpp"
 
 #import <AppKit/AppKit.h>
@@ -101,7 +102,7 @@ std::filesystem::path pet_root_dir() {
     const char* path = base ? base.fileSystemRepresentation : nullptr;
     std::filesystem::path root = path ? std::filesystem::path(path)
                                       : std::filesystem::temp_directory_path();
-    return root / "ACECode" / "desktop-pet";
+    return acecode::compatible_generated_path(root / "ACECode", "desktop-pet");
 }
 
 double load_logical_scale() {
diff --git a/src/apps/desktop/desktop_pet_resources.hpp b/src/apps/desktop/desktop_pet_resources.hpp
index 13e0d1362..2e9b8aed9 100644
--- a/src/apps/desktop/desktop_pet_resources.hpp
+++ b/src/apps/desktop/desktop_pet_resources.hpp
@@ -14,8 +14,12 @@ const unsigned char* classic_pet_page_data();
 std::size_t classic_pet_page_size();
 const unsigned char* clippy_pet_sprite_data();
 std::size_t clippy_pet_sprite_size();
+const unsigned char* clippy_pet_peek_data();
+std::size_t clippy_pet_peek_size();
 const unsigned char* rover_pet_sprite_data();
 std::size_t rover_pet_sprite_size();
+const unsigned char* rover_pet_peek_data();
+std::size_t rover_pet_peek_size();
 const unsigned char* whale_pet_sprite_data();
 std::size_t whale_pet_sprite_size();
 const unsigned char* whale_pet_peek_data();
@@ -30,16 +34,14 @@ inline std::string desktop_pet_html(std::string_view kind) {
 }
 
 inline nlohmann::json desktop_pet_character(std::string_view kind) {
-    const bool rover = kind == "rover";
-    const auto* data = kind == "whale" ? whale_pet_sprite_data() : rover ? rover_pet_sprite_data() : clippy_pet_sprite_data();
-    const auto size = kind == "whale" ? whale_pet_sprite_size() : rover ? rover_pet_sprite_size() : clippy_pet_sprite_size();
-    nlohmann::json character = {{"type", "pet-character"}, {"kind", kind},
-            {"sprite", "data:image/png;base64," + base64_encode({reinterpret_cast<const char*>(data), size})}};
-    // Edge-peek frames used while Whale Girl is docked to the left/right of the screen.
-    if (kind == "whale") {
-        character["peek"] = "data:image/png;base64," +
-            base64_encode({reinterpret_cast<const char*>(whale_pet_peek_data()), whale_pet_peek_size()});
-    }
-    return character;
+    const bool rover = kind == "rover", whale = kind == "whale";
+    const auto* data = whale ? whale_pet_sprite_data() : rover ? rover_pet_sprite_data() : clippy_pet_sprite_data();
+    const auto size = whale ? whale_pet_sprite_size() : rover ? rover_pet_sprite_size() : clippy_pet_sprite_size();
+    // Edge-peek frames used while the pet is docked to the left/right of the screen.
+    const auto* peek = whale ? whale_pet_peek_data() : rover ? rover_pet_peek_data() : clippy_pet_peek_data();
+    const auto peek_size = whale ? whale_pet_peek_size() : rover ? rover_pet_peek_size() : clippy_pet_peek_size();
+    return {{"type", "pet-character"}, {"kind", kind},
+            {"sprite", "data:image/png;base64," + base64_encode({reinterpret_cast<const char*>(data), size})},
+            {"peek", "data:image/png;base64," + base64_encode({reinterpret_cast<const char*>(peek), peek_size})}};
 }
 } // namespace acecode::desktop
diff --git a/src/apps/desktop/edge_app_launcher.cpp b/src/apps/desktop/edge_app_launcher.cpp
index 25b99e57b..3736e68d4 100644
--- a/src/apps/desktop/edge_app_launcher.cpp
+++ b/src/apps/desktop/edge_app_launcher.cpp
@@ -4,6 +4,7 @@
 #include "utils/logger.hpp"
 #include "utils/paths.hpp"
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 
 #include <sstream>
 #include <system_error>
@@ -80,7 +81,7 @@ fs::path known_folder_path(REFKNOWNFOLDERID id) {
 }
 
 fs::path edge_user_data_dir_root() {
-    return acecode::path_from_utf8(acecode::get_acecode_dir()) / "edge-app-profile";
+    return acecode::compatible_generated_path(acecode::path_from_utf8(acecode::get_acecode_dir()), "edge-app-profile");
 }
 
 // 准备本次启动专用的干净 user-data-dir:
diff --git a/src/apps/desktop/main.cpp b/src/apps/desktop/main.cpp
index 5b75058b6..2f52b4534 100644
--- a/src/apps/desktop/main.cpp
+++ b/src/apps/desktop/main.cpp
@@ -58,6 +58,7 @@
 #include "utils/logger.hpp"
 #include "workspace_state.hpp"
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 #include "utils/uuid.hpp"
 #include "version.hpp"
 
@@ -854,9 +855,8 @@ int main(int argc, char** argv) {
     }
 
     const std::int64_t desktop_owner_pid = acecode::daemon::current_pid();
-    const std::string shared_run_dir = path_to_utf8(
-        path_from_utf8(acecode::get_acecode_dir()) / "run" /
-        path_from_utf8(instance_plan.run_subdirectory));
+    const std::string shared_run_dir = path_to_utf8(acecode::compatible_generated_path(
+        path_from_utf8(acecode::get_acecode_dir()) / "run", instance_plan.run_subdirectory));
     if (!instance_plan.primary) {
         LOG_INFO("[desktop] developer multi-instance startup with isolated daemon runtime");
     }
@@ -2614,7 +2614,7 @@ int main(int argc, char** argv) {
                 files.push_back({value.at("name").get<std::string>(), value.at("data_base64").get<std::string>()});
             }
             const auto stored = acecode::desktop::store_context_data_files(
-                path_to_utf8(path_from_utf8(acecode::get_acecode_dir()) / "composer-files"), files);
+                path_to_utf8(acecode::compatible_generated_path(path_from_utf8(acecode::get_acecode_dir()), "composer-files")), files);
             if (!stored) return nlohmann::json{{"ok", false}, {"error", stored.error}}.dump();
             auto items = nlohmann::json::array();
             for (const auto& item : stored.items) items.push_back(context_item_json(item));
diff --git a/src/apps/headless/headless_options.cpp b/src/apps/headless/headless_options.cpp
index 969b60db2..456812328 100644
--- a/src/apps/headless/headless_options.cpp
+++ b/src/apps/headless/headless_options.cpp
@@ -80,7 +80,7 @@ bool append_csv_names(const std::string& raw,
 // 无法区分 —— SessionStorage::list_sessions 会把这种文件名当 legacy 数据
 // 隐藏,创建出来的会话在所有列表里隐身,所以 --session-id 直接拒绝。
 bool looks_like_legacy_pid_session_id(const std::string& id) {
-    static const std::regex re(R"(^\d{8}-\d{6}-[0-9a-f]{4}-\d+$)");
+    static const std::regex re(R"(^\d{8}[-_]\d{6}[-_][0-9a-f]{4}[-_]\d+$)");
     return std::regex_match(id, re);
 }
 
diff --git a/src/apps/web/handlers/security_handler.cpp b/src/apps/web/handlers/security_handler.cpp
index 0d4d3b765..98947f5d1 100644
--- a/src/apps/web/handlers/security_handler.cpp
+++ b/src/apps/web/handlers/security_handler.cpp
@@ -535,9 +535,9 @@ std::string audit_export_filename(const std::string& format, std::int64_t now_ms
     localtime_r(&seconds, &tm);
 #endif
     char stamp[32];
-    std::snprintf(stamp, sizeof(stamp), "%04d%02d%02d-%02d%02d%02d",
+    std::snprintf(stamp, sizeof(stamp), "%04d%02d%02d_%02d%02d%02d",
                   tm.tm_year + 1900, tm.tm_mon + 1, tm.tm_mday, tm.tm_hour, tm.tm_min, tm.tm_sec);
-    return std::string("acecode-audit-") + stamp + (format == "csv" ? ".csv" : ".jsonl");
+    return std::string("acecode_audit_") + stamp + (format == "csv" ? ".csv" : ".jsonl");
 }
 
 } // namespace acecode::web
diff --git a/src/apps/web/remote_web_proxy.cpp b/src/apps/web/remote_web_proxy.cpp
index 6072f3b7c..6c2f1f3d5 100644
--- a/src/apps/web/remote_web_proxy.cpp
+++ b/src/apps/web/remote_web_proxy.cpp
@@ -4,6 +4,7 @@
 #include "utils/atomic_file.hpp"
 #include "utils/encoding.hpp"
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 #include "utils/uuid.hpp"
 
 #include <asio.hpp>
@@ -727,7 +728,7 @@ RemoteWebProxyStatus ManagedRemoteWebProxyController::start_candidate_locked(
 
     const fs::path ready_path =
         acecode::path_from_utf8(runtime_dir_) /
-        ("remote-web-proxy-" + acecode::generate_uuid_v7() + ".json");
+        acecode::generated_file_name("remote_web_proxy_" + acecode::generate_uuid_v7() + ".json");
     const std::string ready_file = acecode::path_to_utf8(ready_path);
     std::error_code filesystem_error;
     fs::create_directories(ready_path.parent_path(), filesystem_error);
diff --git a/src/base/config/config_recovery.cpp b/src/base/config/config_recovery.cpp
index 3ec97fecf..bb757c29b 100644
--- a/src/base/config/config_recovery.cpp
+++ b/src/base/config/config_recovery.cpp
@@ -3,6 +3,7 @@
 #include "utils/atomic_file.hpp"
 #include "utils/logger.hpp"
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 
 #include <nlohmann/json.hpp>
 
@@ -61,7 +62,7 @@ std::string utc_filename_timestamp() {
 #endif
     std::ostringstream out;
     out << std::put_time(&tm, "%Y%m%dT%H%M%S")
-        << '-' << std::setw(3) << std::setfill('0') << millis.count() << 'Z';
+        << '_' << std::setw(3) << std::setfill('0') << millis.count() << 'Z';
     return out.str();
 }
 
@@ -70,10 +71,10 @@ std::string unique_recovery_filename(const fs::path& config_path,
     const std::uint64_t sequence =
         g_recovery_file_sequence.fetch_add(1, std::memory_order_relaxed);
     std::ostringstream out;
-    out << path_to_utf8(config_path.stem()) << '-' << label << '-'
-        << utc_filename_timestamp() << '-' << process_id() << '-'
+    out << path_to_utf8(config_path.stem()) << '_' << label << '_'
+        << utc_filename_timestamp() << '_' << process_id() << '_'
         << sequence << ".json";
-    return out.str();
+    return generated_file_name(out.str());
 }
 
 std::optional<std::string> read_binary_file(const std::string& path,
@@ -132,16 +133,16 @@ ConfigRecoveryPaths config_recovery_paths(const std::string& config_path) {
     fs::path active = path_from_utf8(config_path);
     fs::path parent = active.parent_path();
     if (parent.empty()) parent = fs::current_path();
-    const fs::path root = parent / "config-backups";
+    const fs::path root = compatible_generated_path(parent, "config-backups");
     const fs::path filename = active.filename().empty()
         ? fs::path("config.json")
         : active.filename();
     return {
         path_to_utf8(root),
-        path_to_utf8(root / "last-good" / filename),
+        path_to_utf8(compatible_generated_path(root, "last-good") / filename),
         path_to_utf8(root / "invalid"),
         path_to_utf8(root / "staging"),
-        path_to_utf8(root / "recovery-notice.json"),
+        path_to_utf8(compatible_generated_path(root, "recovery-notice.json")),
     };
 }
 
diff --git a/src/base/config/saved_models.cpp b/src/base/config/saved_models.cpp
index 1986dd8d2..1f93e4cc5 100644
--- a/src/base/config/saved_models.cpp
+++ b/src/base/config/saved_models.cpp
@@ -753,6 +753,47 @@ std::optional<ModelSamplingOptions> parse_model_sampling_options(
     return result;
 }
 
+std::optional<ModelSamplingOptions> parse_model_sampling_overrides(
+    const nlohmann::json& node, std::string& err) {
+    if (node.is_null()) return ModelSamplingOptions{};
+    if (node.is_object()) {
+        for (const auto& item : node.items()) {
+            if (item.key() != "temperature" && item.key() != "top_p" &&
+                item.key() != "top_k" && item.key() != "min_p") {
+                err = "unknown sampling field: " + item.key();
+                return std::nullopt;
+            }
+        }
+    }
+    return parse_model_sampling_options(node, err);
+}
+
+ModelSamplingOptions merge_model_sampling_options(
+    ModelSamplingOptions defaults, const ModelSamplingOptions& overrides) {
+    if (overrides.temperature) defaults.temperature = overrides.temperature;
+    if (overrides.top_p) defaults.top_p = overrides.top_p;
+    if (overrides.top_k) defaults.top_k = overrides.top_k;
+    if (overrides.min_p) defaults.min_p = overrides.min_p;
+    return defaults;
+}
+
+nlohmann::json model_sampling_overrides_schema() {
+    using json = nlohmann::json;
+    return {
+        {"type", json::array({"object", "null"})},
+        {"description", "Optional per-agent sampling overrides. Fields inherit from the "
+                        "selected expert, then the model profile when omitted or null. "
+                        "Only use parameters supported by the selected provider/protocol."},
+        {"additionalProperties", false},
+        {"properties", {
+            {"temperature", {{"type", json::array({"number", "null"})}, {"minimum", 0}, {"maximum", 2}}},
+            {"top_p", {{"type", json::array({"number", "null"})}, {"exclusiveMinimum", 0}, {"maximum", 1}}},
+            {"top_k", {{"type", json::array({"integer", "null"})}, {"minimum", 1}, {"maximum", 2147483647}}},
+            {"min_p", {{"type", json::array({"number", "null"})}, {"minimum", 0}, {"maximum", 1}}},
+        }},
+    };
+}
+
 nlohmann::json model_sampling_options_to_json(
     const ModelSamplingOptions& options) {
     nlohmann::json result = nlohmann::json::object();
diff --git a/src/base/config/saved_models.hpp b/src/base/config/saved_models.hpp
index 69d0cd2ee..87801b95e 100644
--- a/src/base/config/saved_models.hpp
+++ b/src/base/config/saved_models.hpp
@@ -117,6 +117,12 @@ std::optional<ModelSamplingOptions> parse_model_sampling_options(
     std::string& err);
 nlohmann::json model_sampling_options_to_json(
     const ModelSamplingOptions& options);
+// Per-agent overrides: null inherits, unknown fields are rejected.
+std::optional<ModelSamplingOptions> parse_model_sampling_overrides(
+    const nlohmann::json& node, std::string& err);
+ModelSamplingOptions merge_model_sampling_options(
+    ModelSamplingOptions defaults, const ModelSamplingOptions& overrides);
+nlohmann::json model_sampling_overrides_schema();
 // 只校验取值范围(与 provider 无关):temperature ∈ [0,2]、top_p ∈ (0,1]、
 // top_k ≥ 1、min_p ∈ [0,1]。
 bool validate_model_sampling_ranges(const ModelSamplingOptions& options,
diff --git a/src/base/environment/data_dir_migration.cpp b/src/base/environment/data_dir_migration.cpp
index de6732c3d..8401183a4 100644
--- a/src/base/environment/data_dir_migration.cpp
+++ b/src/base/environment/data_dir_migration.cpp
@@ -3,6 +3,7 @@
 #include "data_dir_migration.hpp"
 
 #include "utils/encoding.hpp"
+#include "utils/generated_file_names.hpp"
 #include "utils/logger.hpp"
 #include "utils/utf8_path.hpp"
 #include "utils/uuid.hpp"
@@ -25,6 +26,11 @@ namespace fs = std::filesystem;
 namespace {
 std::shared_mutex write_gate;
 std::atomic<bool> writes_blocked{false};
+
+bool is_data_dir_redirect_file(const fs::path& relative) {
+    return relative == fs::path(kDataDirRedirectFileName) ||
+           relative == fs::path(generated_file_name(kDataDirRedirectFileName));
+}
 }
 std::shared_mutex& data_dir_write_mutex() { return write_gate; }
 bool data_dir_writes_blocked() { return writes_blocked.load(); }
@@ -327,7 +333,7 @@ MigrationTargetCheck validate_migration_target(const std::string& current_dir,
     }
 
     // 真写一个探针文件确认可写(只读盘 / 权限不足在这里暴露,而不是复制到一半)。
-    const fs::path probe = target_c / ".acecode-write-probe";
+    const fs::path probe = target_c / ".acecode_write_probe";
     {
         std::ofstream ofs(probe, std::ios::binary | std::ios::trunc);
         if (!ofs.is_open()) {
@@ -349,8 +355,8 @@ bool migration_excludes_entry(const fs::path& relative) {
     const std::string first = path_to_utf8(*relative.begin());
     // edge-app-profile:webapp 兼容模式下 Edge --app 的 user-data-dir,每次启动都用全新的
     // PID 子目录并清掉旧的,持续在写又没有要保留的数据,整个排除。
-    if (first == "run" || first == "tmp" || first == "edge-app-profile") return true;
-    if (first == kDataDirRedirectFileName && std::distance(relative.begin(), relative.end()) == 1) {
+    if (first == "run" || first == "tmp" || first == "edge-app-profile" || first == "edge_app_profile") return true;
+    if (is_data_dir_redirect_file(relative)) {
         return true;
     }
     // cache/no-workspace/<id>/.acecode/tmp/**:无工作区会话的 ACECODE_TMPDIR(临时脚本、
@@ -361,7 +367,7 @@ bool migration_excludes_entry(const fs::path& relative) {
     for (auto part = relative.begin(); part != relative.end() && count < 5; ++part) {
         segments[count++] = path_to_utf8(*part);
     }
-    if (count == 5 && segments[0] == "cache" && segments[1] == "no-workspace" &&
+    if (count == 5 && segments[0] == "cache" && (segments[1] == "no-workspace" || segments[1] == "no_workspace") &&
         segments[3] == ".acecode" && segments[4] == "tmp") {
         return true;
     }
@@ -465,7 +471,7 @@ MigrationProgress run_data_dir_migration(const std::string& current_dir,
         const fs::path relative = it->path().lexically_relative(source_io);
         if (migration_excludes_entry(relative)) {
             // 指针文件清理时保留,不算旧数据。
-            if (relative != fs::path(kDataDirRedirectFileName)) {
+            if (!is_data_dir_redirect_file(relative)) {
                 left_behind_bytes += measure_left_behind_bytes(it->path());
             }
             if (it->is_directory(ec)) it.disable_recursion_pending();
@@ -802,7 +808,7 @@ std::string cleanup_previous_data_dir(const std::string& previous_dir,
         prefix_key(canonical_or_normal(path_from_utf8(default_dir)));
     std::string first_error;
     for (const auto& entry : fs::directory_iterator(prev_io, ec)) {
-        if (keep_pointer && entry.path().filename() == kDataDirRedirectFileName) continue;
+        if (keep_pointer && is_data_dir_redirect_file(entry.path().filename())) continue;
         std::error_code rm_ec;
         fs::remove_all(entry.path(), rm_ec);
         if (rm_ec && first_error.empty()) {
@@ -849,7 +855,7 @@ DataDirStatus data_dir_status(RunMode mode) {
             // 默认目录只剩指针文件时不算"仍有旧数据"。
             bool has_content = false;
             for (const auto& entry : fs::directory_iterator(prev, ec)) {
-                if (entry.path().filename() == kDataDirRedirectFileName) continue;
+                if (is_data_dir_redirect_file(entry.path().filename())) continue;
                 has_content = true;
                 break;
             }
diff --git a/src/base/environment/data_dir_migration.hpp b/src/base/environment/data_dir_migration.hpp
index a097292f9..a88ab612e 100644
--- a/src/base/environment/data_dir_migration.hpp
+++ b/src/base/environment/data_dir_migration.hpp
@@ -86,7 +86,7 @@ inline constexpr unsigned long long kCleanupPromptThresholdBytes = 100ULL * 1024
 // 曾经是 ".acecode-migration-" + 完整 uuid,共 55 字符,正是它把 staging 下的深层路径
 // 先于最终路径顶破 MAX_PATH。现在前缀 + 8 位 hex 共 21 字符。IO 虽然已走扩展长度路径,
 // 短名仍有意义:失败清理、杀软扫描、用户手工查看时路径不会比最终路径先撞线。
-inline constexpr const char* kMigrationStagingPrefix = ".acecode-mig-";
+inline constexpr const char* kMigrationStagingPrefix = ".acecode_mig_";
 
 // kMigrationStagingPrefix + uuid 前 8 位 hex。
 std::string make_migration_staging_name();
diff --git a/src/base/ipc/agent_browser_runtime.cpp b/src/base/ipc/agent_browser_runtime.cpp
index 349a2bdc6..6e07154c4 100644
--- a/src/base/ipc/agent_browser_runtime.cpp
+++ b/src/base/ipc/agent_browser_runtime.cpp
@@ -4,6 +4,7 @@
 #include "utils/paths.hpp"
 #include "utils/url_encoding.hpp"
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 
 #include <fstream>
 #include <nlohmann/json.hpp>
@@ -99,7 +100,7 @@ std::string normalize_file_url(std::string value) {
 } // namespace
 
 std::filesystem::path agent_browser_root_path(const std::string& acecode_dir) {
-    return data_root(acecode_dir) / "agent-browser";
+    return compatible_generated_path(data_root(acecode_dir), "agent-browser");
 }
 
 std::filesystem::path agent_browser_user_data_path(const std::string& acecode_dir) {
@@ -108,17 +109,17 @@ std::filesystem::path agent_browser_user_data_path(const std::string& acecode_di
 
 std::filesystem::path agent_browser_macos_profile_identifier_path(
     const std::string& acecode_dir) {
-    return agent_browser_root_path(acecode_dir) / "macos-profile-id";
+    return compatible_generated_path(agent_browser_root_path(acecode_dir), "macos-profile-id");
 }
 
 std::filesystem::path agent_browser_proxy_socket_path(
     const std::string& acecode_dir) {
-    return data_root(acecode_dir) / "run" / "agent-browser.sock";
+    return compatible_generated_path(data_root(acecode_dir) / "run", "agent-browser.sock");
 }
 
 std::filesystem::path agent_browser_runtime_manifest_path(
     const std::string& acecode_dir) {
-    return data_root(acecode_dir) / "run" / "agent-browser.json";
+    return compatible_generated_path(data_root(acecode_dir) / "run", "agent-browser.json");
 }
 
 std::optional<std::string> normalize_agent_browser_url(
@@ -227,7 +228,8 @@ std::string validate_agent_browser_runtime_manifest(
     const std::filesystem::path socket_path =
         path_from_utf8(manifest.pipe_name);
     if (!socket_path.is_absolute() ||
-        socket_path.filename() != "agent-browser.sock" ||
+        (socket_path.filename() != "agent-browser.sock" &&
+         socket_path.filename() != "agent_browser.sock") ||
         socket_path.parent_path().filename() != "run") {
         return "agent browser proxy socket is invalid";
     }
diff --git a/src/base/ipc/open_request.cpp b/src/base/ipc/open_request.cpp
index d18672938..4d540363a 100644
--- a/src/base/ipc/open_request.cpp
+++ b/src/base/ipc/open_request.cpp
@@ -3,6 +3,7 @@
 #include "utils/atomic_file.hpp"
 #include "utils/paths.hpp"
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 #include "utils/uuid.hpp"
 
 #include <nlohmann/json.hpp>
@@ -128,8 +129,8 @@ DesktopOpenRequestParseResult parse_desktop_open_request_arguments(
 }
 
 std::string desktop_open_request_path() {
-    return path_to_utf8(
-        path_from_utf8(get_run_dir()) / "desktop-open-request.json");
+    return path_to_utf8(compatible_generated_path(
+        path_from_utf8(get_run_dir()), "desktop-open-request.json"));
 }
 
 bool publish_pending_desktop_open_request(
@@ -174,7 +175,7 @@ std::optional<DesktopOpenRequest> take_pending_desktop_open_request(
     }
 
     fs::path claimed = source;
-    claimed += ".processing-" + generate_uuid();
+    claimed += ".processing_" + generated_file_name(generate_uuid());
     fs::rename(source, claimed, ec);
     if (ec) {
         if (error) {
diff --git a/src/base/ipc/runtime_files.cpp b/src/base/ipc/runtime_files.cpp
index 476d72ccc..5d30aa95f 100644
--- a/src/base/ipc/runtime_files.cpp
+++ b/src/base/ipc/runtime_files.cpp
@@ -2,6 +2,7 @@
 
 #include "utils/atomic_file.hpp"
 #include "utils/constants.hpp"
+#include "utils/generated_file_names.hpp"
 #include "utils/logger.hpp"
 #include "utils/paths.hpp"
 #include "utils/utf8_path.hpp"
@@ -58,7 +59,7 @@ std::string ensure_run_dir_for(const std::string& run_dir) {
 }
 
 std::string run_path_for(const std::string& run_dir, const char* fname) {
-    return path_to_utf8(effective_run_dir_path(run_dir) / fname);
+    return path_to_utf8(compatible_generated_path(effective_run_dir_path(run_dir), fname));
 }
 
 std::string run_path(const char* fname) {
diff --git a/src/base/platform/native_ui/strings.cpp b/src/base/platform/native_ui/strings.cpp
index b30251165..253462635 100644
--- a/src/base/platform/native_ui/strings.cpp
+++ b/src/base/platform/native_ui/strings.cpp
@@ -38,7 +38,7 @@ constexpr Catalog kZhCn = {
     "主题压缩包 (*.zip)",
     "ACECode 启动失败",
     "ACECode 桌面版启动时遇到未预期的错误，即将退出。",
-    "请把日志文件 %USERPROFILE%\\.acecode\\logs\\desktop-*.log 发给 IT/开发团队。",
+    "请把日志文件 %USERPROFILE%\\.acecode\\logs\\desktop_*.log（旧版为 desktop-*.log）发给 IT/开发团队。",
     "异常信息：",
     "无法找到 acecode.exe。请确认它与 acecode-desktop.exe 位于同一目录。",
     "无法为工作区启动后台服务",
@@ -78,7 +78,7 @@ constexpr Catalog kEnUs = {
     "Theme package (*.zip)",
     "ACECode startup failed",
     "ACECode Desktop encountered an unexpected startup error and will exit.",
-    "Send %USERPROFILE%\\.acecode\\logs\\desktop-*.log to your IT or development team.",
+    "Send %USERPROFILE%\\.acecode\\logs\\desktop_*.log (desktop-*.log in older versions) to your IT or development team.",
     "Exception details: ",
     "Cannot locate acecode.exe. Place it in the same directory as acecode-desktop.exe.",
     "Failed to start the background service for workspace",
diff --git a/src/base/utils/generated_file_names.hpp b/src/base/utils/generated_file_names.hpp
new file mode 100644
index 000000000..3733b79ea
--- /dev/null
+++ b/src/base/utils/generated_file_names.hpp
@@ -0,0 +1,30 @@
+#pragma once
+
+#include "utf8_path.hpp"
+
+#include <algorithm>
+#include <filesystem>
+#include <string>
+#include <system_error>
+
+namespace acecode {
+
+// Apply only to names generated by ACECode, never to an existing identity or
+// a user-supplied path. Protocol UUIDs keep their standard representation.
+inline std::string generated_file_name(std::string name) {
+    std::replace(name.begin(), name.end(), '-', '_');
+    return name;
+}
+
+// Reuse an existing legacy resource instead of opening a second, empty store.
+// Legacy wins if both names exist; leave reconciliation to the owning module.
+inline std::filesystem::path compatible_generated_path(
+    const std::filesystem::path& directory, const std::string& legacy_name) {
+    const auto legacy = directory / path_from_utf8(legacy_name);
+    if (legacy_name.find('-') == std::string::npos) return legacy;
+    std::error_code ec;
+    if (std::filesystem::exists(legacy, ec) || ec) return legacy;
+    return directory / path_from_utf8(generated_file_name(legacy_name));
+}
+
+} // namespace acecode
diff --git a/src/base/utils/logger.hpp b/src/base/utils/logger.hpp
index fd2c31d51..a11c293de 100644
--- a/src/base/utils/logger.hpp
+++ b/src/base/utils/logger.hpp
@@ -24,6 +24,7 @@
 #include <utility>
 
 #include "append_file.hpp"
+#include "generated_file_names.hpp"
 
 namespace acecode {
 
@@ -68,7 +69,7 @@ class Logger {
         enabled_ = ofs_.is_open();
     }
 
-    // 滚动模式:写入 dir/<base_name>-<YYYY-MM-DD>.log,跨本地午夜
+    // 滚动模式:写入 dir/<base_name>_<YYYY_MM_DD>.log,跨本地午夜
     // 自动滚动到新日期文件。mirror_stderr=true 时每条日志同时写 stderr
     // (foreground 模式)。dir 不存在会被创建。
     void init_with_rotation(const std::string& dir,
@@ -224,7 +225,7 @@ class Logger {
     void open_rotated_locked_(const std::string& date) {
         if (ofs_.is_open()) ofs_.close();
         auto path = path_from_utf8_(rotation_dir_) /
-                    (rotation_base_ + "-" + date + ".log");
+                    generated_file_name(rotation_base_ + "_" + date + ".log");
         ofs_.open(path);
         last_open_date_ = date;
         enabled_ = ofs_.is_open();
diff --git a/src/base/utils/paths.cpp b/src/base/utils/paths.cpp
index ef41f0959..f42d93d1b 100644
--- a/src/base/utils/paths.cpp
+++ b/src/base/utils/paths.cpp
@@ -5,6 +5,7 @@
 #include "encoding.hpp"
 #include "logger.hpp"
 #include "utf8_path.hpp"
+#include "generated_file_names.hpp"
 
 #include <nlohmann/json.hpp>
 
@@ -178,7 +179,7 @@ std::string resolve_default_data_dir(RunMode mode) {
 // ── 数据目录重定向指针 ─────────────────────────────────────────────────────
 
 std::string data_dir_redirect_path(const std::string& default_dir) {
-    return path_to_utf8(path_from_utf8(default_dir) / kDataDirRedirectFileName);
+    return path_to_utf8(compatible_generated_path(path_from_utf8(default_dir), kDataDirRedirectFileName));
 }
 
 std::optional<DataDirRedirect> read_data_dir_redirect(const std::string& default_dir) {
diff --git a/src/domain/experts/expert_definition.cpp b/src/domain/experts/expert_definition.cpp
new file mode 100644
index 000000000..54aeeef73
--- /dev/null
+++ b/src/domain/experts/expert_definition.cpp
@@ -0,0 +1,73 @@
+#include "expert_registry.hpp"
+
+#include <algorithm>
+
+namespace acecode {
+namespace fs = std::filesystem;
+
+const ExpertAgent* ExpertDefinition::agent(const std::string& agent_id) const {
+    const auto it = std::find_if(agents.begin(), agents.end(), [&](const ExpertAgent& item) {
+        return item.id == agent_id;
+    });
+    return it == agents.end() ? nullptr : &*it;
+}
+
+std::vector<fs::path> ExpertDefinition::selected_skill_roots(
+    const std::string& member_id) const {
+    std::vector<fs::path> roots = skill_roots;
+    if (const ExpertAgent* selected = selected_agent(member_id)) {
+        for (const auto& root : selected->skill_roots) {
+            if (std::find(roots.begin(), roots.end(), root) == roots.end()) {
+                roots.push_back(root);
+            }
+        }
+    }
+    return roots;
+}
+
+ExpertCapabilityScopes ExpertDefinition::selected_capabilities(
+    const std::string& member_id) const {
+    if (references_existing_experts) {
+        if (const ExpertAgent* selected = selected_agent(member_id)) {
+            return selected->capabilities;
+        }
+    }
+    return capabilities;
+}
+
+ModelSamplingOptions ExpertDefinition::selected_sampling(const std::string& member_id) const {
+    if (const auto* selected = selected_agent(member_id)) {
+        return merge_model_sampling_options(sampling, selected->sampling);
+    }
+    return sampling;
+}
+
+bool ExpertDefinition::is_declared_member(const std::string& member_id) const {
+    return type == ExpertType::Team &&
+           std::find(member_agent_ids.begin(), member_agent_ids.end(), member_id) !=
+               member_agent_ids.end();
+}
+
+const char* to_string(ExpertType type) {
+    return type == ExpertType::Team ? "team" : "agent";
+}
+
+bool ExpertRegistry::valid_id(const std::string& id) {
+    if (id.empty() || id.size() > 64 || id.front() == '-' || id.back() == '-') return false;
+    return std::all_of(id.begin(), id.end(), [](unsigned char ch) {
+        return (ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9') || ch == '-';
+    });
+}
+
+bool is_known_expert_avatar_state(std::string_view state) {
+    return std::find(kExpertAvatarStates.begin(), kExpertAvatarStates.end(),
+                     state) != kExpertAvatarStates.end();
+}
+
+bool is_supported_expert_avatar_mime(std::string_view mime) {
+    return mime == "image/png" || mime == "image/jpeg" ||
+           mime == "image/gif" || mime == "image/webp" ||
+           mime == "image/bmp" || mime == "image/x-icon";
+}
+
+} // namespace acecode
diff --git a/src/domain/experts/expert_registry.cpp b/src/domain/experts/expert_registry.cpp
index 0fdfc30d4..580c1b303 100644
--- a/src/domain/experts/expert_registry.cpp
+++ b/src/domain/experts/expert_registry.cpp
@@ -347,6 +347,15 @@ std::optional<ExpertDefinition> load_package(const fs::path& package_root,
     }
 
     ExpertDefinition expert;
+    if (const auto sampling = manifest.find("sampling"); sampling != manifest.end()) {
+        std::string sampling_error;
+        auto parsed = parse_model_sampling_overrides(*sampling, sampling_error);
+        if (!parsed) {
+            set_error(error, sampling_error);
+            return std::nullopt;
+        }
+        expert.sampling = *parsed;
+    }
     expert.id = json_text(manifest, "name");
     if (!ExpertRegistry::valid_id(expert.id)) {
         set_error(error, "manifest name is not a valid expert ID");
@@ -540,6 +549,15 @@ std::optional<ExpertDefinition> load_package(const fs::path& package_root,
             }
             expert.agents.push_back({id, display_name, profession,
                                      std::move(document.body), std::move(agent_path), {}});
+            if (entry.is_object() && entry.contains("sampling")) {
+                std::string sampling_error;
+                auto parsed = parse_model_sampling_overrides(entry["sampling"], sampling_error);
+                if (!parsed) {
+                    set_error(error, "Agent " + id + ": " + sampling_error);
+                    return std::nullopt;
+                }
+                expert.agents.back().sampling = *parsed;
+            }
         }
 
         expert.lead_agent_id = json_text(manifest, "agentName");
@@ -651,6 +669,11 @@ std::string agent_markdown(const ExpertAgentDraft& agent);
 json draft_manifest(const ExpertDraft& draft);
 
 bool validate_draft(const ExpertDraft& draft, std::string* error) {
+    std::string sampling_error;
+    if (!validate_model_sampling_ranges(draft.sampling, sampling_error)) {
+        set_error(error, sampling_error);
+        return false;
+    }
     if (!ExpertRegistry::valid_id(draft.id)) {
         set_error(error, "expert ID must use lowercase letters, digits, and hyphens");
         return false;
@@ -824,6 +847,9 @@ json draft_manifest(const ExpertDraft& draft) {
         result["capabilities"] =
             capability_scopes_to_json(draft.capabilities);
     }
+    if (!draft.sampling.empty()) {
+        result["sampling"] = model_sampling_options_to_json(draft.sampling);
+    }
     if (draft.state_avatars_present || !draft.state_avatars.empty()) {
         result["stateAvatars"] = draft.state_avatars;
     }
@@ -1065,6 +1091,19 @@ bool materialize_draft(const fs::path& root,
         manifest.erase("capabilities");
     }
 
+    if (materialized.sampling_present || !materialized.sampling.empty()) {
+        if (materialized.sampling.empty()) manifest.erase("sampling");
+        else manifest["sampling"] = model_sampling_options_to_json(materialized.sampling);
+        // A managed single-expert edit replaces its complete preset, including
+        // a package-authored lead override. Team member presets remain owned
+        // by the referenced experts.
+        if (materialized.type == ExpertType::Agent) {
+            for (auto& agent : manifest["agents"]) {
+                if (agent.is_object() && agent_entry_id(agent) == materialized.lead.id) agent.erase("sampling");
+            }
+        }
+    }
+
     if (materialized.state_avatars_present) {
         json state_avatars = json::object();
         const auto existing = manifest.find("stateAvatars");
@@ -1411,17 +1450,6 @@ bool validate_team_reference_targets(
 
 } // namespace
 
-bool is_known_expert_avatar_state(std::string_view state) {
-    return std::find(kExpertAvatarStates.begin(), kExpertAvatarStates.end(),
-                     state) != kExpertAvatarStates.end();
-}
-
-bool is_supported_expert_avatar_mime(std::string_view mime) {
-    return mime == "image/png" || mime == "image/jpeg" ||
-           mime == "image/gif" || mime == "image/webp" ||
-           mime == "image/bmp" || mime == "image/x-icon";
-}
-
 bool validate_expert_avatar_file(const std::filesystem::path& path,
                                  std::string* error) {
     std::error_code ec;
@@ -1443,58 +1471,11 @@ bool validate_expert_avatar_file(const std::filesystem::path& path,
     return true;
 }
 
-const ExpertAgent* ExpertDefinition::agent(const std::string& agent_id) const {
-    const auto it = std::find_if(agents.begin(), agents.end(), [&](const ExpertAgent& item) {
-        return item.id == agent_id;
-    });
-    return it == agents.end() ? nullptr : &*it;
-}
-
-std::vector<fs::path> ExpertDefinition::selected_skill_roots(
-    const std::string& member_id) const {
-    std::vector<fs::path> roots = skill_roots;
-    if (const ExpertAgent* selected = selected_agent(member_id)) {
-        for (const auto& root : selected->skill_roots) {
-            if (std::find(roots.begin(), roots.end(), root) == roots.end()) {
-                roots.push_back(root);
-            }
-        }
-    }
-    return roots;
-}
-
-ExpertCapabilityScopes ExpertDefinition::selected_capabilities(
-    const std::string& member_id) const {
-    if (references_existing_experts) {
-        if (const ExpertAgent* selected = selected_agent(member_id)) {
-            return selected->capabilities;
-        }
-    }
-    return capabilities;
-}
-
-bool ExpertDefinition::is_declared_member(const std::string& member_id) const {
-    return type == ExpertType::Team &&
-           std::find(member_agent_ids.begin(), member_agent_ids.end(), member_id) !=
-               member_agent_ids.end();
-}
-
-const char* to_string(ExpertType type) {
-    return type == ExpertType::Team ? "team" : "agent";
-}
-
 ExpertRegistry::ExpertRegistry(fs::path global_root)
     : global_root_(global_root.empty()
                        ? path_from_utf8(get_acecode_dir()) / "experts"
                        : std::move(global_root)) {}
 
-bool ExpertRegistry::valid_id(const std::string& id) {
-    if (id.empty() || id.size() > 64 || id.front() == '-' || id.back() == '-') return false;
-    return std::all_of(id.begin(), id.end(), [](unsigned char ch) {
-        return (ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9') || ch == '-';
-    });
-}
-
 std::vector<ExpertDefinition> ExpertRegistry::list(
     const std::string& working_dir,
     std::vector<ExpertDiagnostic>* diagnostics) const {
@@ -1572,6 +1553,7 @@ std::vector<ExpertDefinition> ExpertRegistry::list(
             }
             projected.skill_roots = referenced.selected_skill_roots();
             projected.capabilities = referenced.selected_capabilities();
+            projected.sampling = referenced.selected_sampling();
             expert.agents.push_back(std::move(projected));
             return true;
         };
@@ -1744,6 +1726,18 @@ std::optional<ExpertDraft> ExpertRegistry::draft_from_json(const json& value,
         }
     }
 
+    const auto sampling = value.find("sampling");
+    if (sampling != value.end()) {
+        draft.sampling_present = true;
+        std::string sampling_error;
+        auto parsed = parse_model_sampling_overrides(*sampling, sampling_error);
+        if (!parsed) {
+            set_error(error, sampling_error);
+            return std::nullopt;
+        }
+        draft.sampling = *parsed;
+    }
+
     const auto capabilities = value.find("capabilities");
     if (capabilities != value.end()) {
         draft.capabilities_present = true;
@@ -1840,6 +1834,7 @@ json expert_definition_to_json(const ExpertDefinition& expert,
             {"avatar_identity", expert.avatar_identity(agent.id)},
         };
         if (include_instructions) item["instructions"] = agent.instructions;
+        item["sampling"] = model_sampling_options_to_json(expert.selected_sampling(agent.id));
         agents.push_back(std::move(item));
     }
     json result = {
@@ -1864,6 +1859,8 @@ json expert_definition_to_json(const ExpertDefinition& expert,
         {"agents", std::move(agents)},
         {"source", expert.source},
         {"managed_global", expert.managed_global},
+        {"sampling", model_sampling_options_to_json(
+            expert.type == ExpertType::Agent ? expert.selected_sampling() : expert.sampling)},
     };
     if (!expert.references_existing_experts &&
         has_any_capability_scope(expert.capabilities)) {
diff --git a/src/domain/experts/expert_registry.hpp b/src/domain/experts/expert_registry.hpp
index 277a0c3ea..f9c6bef59 100644
--- a/src/domain/experts/expert_registry.hpp
+++ b/src/domain/experts/expert_registry.hpp
@@ -11,6 +11,7 @@
 #include <vector>
 
 #include <nlohmann/json.hpp>
+#include "config/saved_models.hpp"
 
 namespace acecode {
 
@@ -55,6 +56,7 @@ struct ExpertAgent {
     std::filesystem::path document_path;
     std::vector<std::filesystem::path> skill_roots;
     ExpertCapabilityScopes capabilities;
+    ModelSamplingOptions sampling;
 };
 
 struct ExpertDefinition {
@@ -77,6 +79,8 @@ struct ExpertDefinition {
     std::string updated_at;
     ExpertCapabilityScopes capabilities;
 
+    ModelSamplingOptions sampling;
+
     std::string lead_agent_id;
     std::vector<ExpertAgent> agents;
     std::vector<std::string> member_agent_ids;
@@ -96,6 +100,7 @@ struct ExpertDefinition {
         const std::string& member_id = {}) const;
     ExpertCapabilityScopes selected_capabilities(
         const std::string& member_id = {}) const;
+    ModelSamplingOptions selected_sampling(const std::string& member_id = {}) const;
     bool is_declared_member(const std::string& member_id) const;
 };
 
@@ -129,6 +134,9 @@ struct ExpertDraft {
     // authoritative either way: omitted managed scope keys mean inheritance,
     // while unknown capability extension keys remain package-owned data.
     bool capabilities_present = false;
+    ModelSamplingOptions sampling;
+    // Omission preserves existing package data; null/{} explicitly clears it.
+    bool sampling_present = false;
     ExpertStateAvatars state_avatars;
     // Omitted preserves package-owned state data; a present object is
     // authoritative for the three known state keys, including explicit clear.
diff --git a/src/domain/memory/memory_inbox.cpp b/src/domain/memory/memory_inbox.cpp
index 594d70c1c..492af0adf 100644
--- a/src/domain/memory/memory_inbox.cpp
+++ b/src/domain/memory/memory_inbox.cpp
@@ -6,6 +6,7 @@
 #include "utils/encoding.hpp"
 #include "utils/logger.hpp"
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 
 #include <nlohmann/json.hpp>
 
@@ -37,7 +38,7 @@ bool write_atomic(const fs::path& target, const std::string& content, std::strin
     }
     std::random_device rd;
     fs::path tmp = target;
-    tmp += ".tmp-" + std::to_string(std::mt19937_64(rd())());
+    tmp += ".tmp_" + std::to_string(std::mt19937_64(rd())());
     {
         std::ofstream ofs(tmp, std::ios::binary | std::ios::trunc);
         ofs.write(content.data(), static_cast<std::streamsize>(content.size()));
@@ -100,13 +101,15 @@ std::vector<fs::path> json_files_in(const fs::path& dir) {
 
 std::string memory_observation_file_stem(const std::string& session_id,
                                          std::int64_t from, std::int64_t to) {
-    return session_id + "-" + std::to_string(from) + "-" + std::to_string(to);
+    return generated_file_name(session_id) + "_" + std::to_string(from) + "_" + std::to_string(to);
 }
 
 bool write_memory_observation_file(const fs::path& scope_dir, MemoryObservationFile& file,
                                    std::string* error) {
-    const std::string stem = memory_observation_file_stem(file.session_id, file.from, file.to);
-    file.path = memory_inbox_dir(scope_dir) / (stem + ".json");
+    const auto legacy_name = file.session_id + "-" + std::to_string(file.from) +
+        "-" + std::to_string(file.to) + ".json";
+    file.path = compatible_generated_path(memory_inbox_dir(scope_dir), legacy_name);
+    const std::string stem = path_to_utf8(file.path.stem());
     if (file.created_at.empty()) file.created_at = memory_now_iso8601();
     nlohmann::json observations = nlohmann::json::array();
     for (std::size_t i = 0; i < file.observations.size(); ++i) {
@@ -134,8 +137,9 @@ bool write_memory_observation_file(const fs::path& scope_dir, MemoryObservationF
 void remove_memory_observation_file(const fs::path& scope_dir, const std::string& session_id,
                                     std::int64_t from, std::int64_t to) {
     std::error_code ec;
-    fs::remove(memory_inbox_dir(scope_dir) /
-               (memory_observation_file_stem(session_id, from, to) + ".json"), ec);
+    const auto legacy_name = session_id + "-" + std::to_string(from) +
+        "-" + std::to_string(to) + ".json";
+    fs::remove(compatible_generated_path(memory_inbox_dir(scope_dir), legacy_name), ec);
 }
 
 std::vector<MemoryObservationFile> list_memory_inbox(const fs::path& scope_dir) {
@@ -159,7 +163,7 @@ std::size_t count_memory_inbox_observations(const fs::path& scope_dir) {
 bool archive_memory_observation_files(const fs::path& scope_dir,
                                       const std::vector<fs::path>& files,
                                       const std::string& date, std::string* error) {
-    const fs::path target_dir = memory_archive_dir(scope_dir) / date;
+    const fs::path target_dir = compatible_generated_path(memory_archive_dir(scope_dir), date);
     std::error_code ec;
     fs::create_directories(target_dir, ec);
     if (ec) {
@@ -206,7 +210,9 @@ int cleanup_memory_archive(const fs::path& scope_dir, std::int64_t now_seconds,
     std::vector<fs::path> expired;
     for (auto it = fs::directory_iterator(archive, ec); !ec && it != fs::directory_iterator();
          it.increment(ec)) {
-        const auto day = parse_memory_iso8601(path_to_utf8(it->path().filename()) + "T00:00:00Z");
+        auto date = path_to_utf8(it->path().filename());
+        std::replace(date.begin(), date.end(), '_', '-');
+        const auto day = parse_memory_iso8601(date + "T00:00:00Z");
         if (!day) continue;
         if (now_seconds - *day > static_cast<std::int64_t>(keep_days) * 86400) {
             expired.push_back(it->path());
diff --git a/src/domain/memory/memory_registry.cpp b/src/domain/memory/memory_registry.cpp
index 084e5145f..9c6094727 100644
--- a/src/domain/memory/memory_registry.cpp
+++ b/src/domain/memory/memory_registry.cpp
@@ -40,7 +40,7 @@ std::string atomic_write(const fs::path& target, const std::string& content) {
     std::mt19937_64 gen(rd());
     auto suffix = std::to_string(gen());
     fs::path tmp = target;
-    tmp += ".tmp-" + suffix;
+    tmp += ".tmp_" + suffix;
 
     {
         std::ofstream ofs(tmp, std::ios::binary | std::ios::trunc);
diff --git a/src/domain/sandbox/sandbox_policy.cpp b/src/domain/sandbox/sandbox_policy.cpp
index 9e8bdba0c..de8f3fd2c 100644
--- a/src/domain/sandbox/sandbox_policy.cpp
+++ b/src/domain/sandbox/sandbox_policy.cpp
@@ -3,6 +3,7 @@
 #include "utils/logger.hpp"
 #include "utils/paths.hpp"
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 #include "utils/sha1.hpp"
 
 #include <algorithm>
@@ -46,7 +47,7 @@ std::string temporary_write_root(const std::string& write_root,
         if (c == '\\') c = '/';
     }
     // 保留预期路径,不要在这里跟随专用目录上的 junction;prepare_request 会核验。
-    return path_to_utf8(path_from_utf8(base) / "acecode-sandbox" / sha1_hex(identity));
+    return path_to_utf8(compatible_generated_path(path_from_utf8(base), "acecode-sandbox") / sha1_hex(identity));
 #else
     return base;
 #endif
diff --git a/src/domain/session/file_checkpoint_store.cpp b/src/domain/session/file_checkpoint_store.cpp
index 8fdf1dfa0..9538d4485 100644
--- a/src/domain/session/file_checkpoint_store.cpp
+++ b/src/domain/session/file_checkpoint_store.cpp
@@ -3,6 +3,7 @@
 #include "utils/diff_utils.hpp"
 #include "utils/logger.hpp"
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 #include "utils/uuid.hpp"
 
 #include <nlohmann/json.hpp>
@@ -194,7 +195,7 @@ void FileCheckpointStore::reset() {
 
 std::string FileCheckpointStore::checkpoint_dir() const {
     if (project_dir_.empty() || session_id_.empty()) return {};
-    return path_to_utf8(path_from_utf8(project_dir_) / "file-checkpoints" / session_id_);
+    return path_to_utf8(compatible_generated_path(path_from_utf8(project_dir_), "file-checkpoints") / session_id_);
 }
 
 std::string FileCheckpointStore::normalize_tracking_path(const std::string& file_path) const {
@@ -213,7 +214,7 @@ std::string FileCheckpointStore::normalize_tracking_path(const std::string& file
 std::string FileCheckpointStore::backup_path(const std::string& backup_file_name,
                                              const std::string& session_id_override) const {
     const std::string& sid = session_id_override.empty() ? session_id_ : session_id_override;
-    return path_to_utf8(path_from_utf8(project_dir_) / "file-checkpoints" / sid / backup_file_name);
+    return path_to_utf8(compatible_generated_path(path_from_utf8(project_dir_), "file-checkpoints") / sid / backup_file_name);
 }
 
 std::string FileCheckpointStore::make_backup_file_name(
@@ -598,7 +599,7 @@ void FileCheckpointStore::remove_session_backups(
     const std::string& project_dir,
     const std::string& session_id) {
     std::error_code ec;
-    fs::remove_all(path_from_utf8(project_dir) / "file-checkpoints" / session_id, ec);
+    fs::remove_all(compatible_generated_path(path_from_utf8(project_dir), "file-checkpoints") / session_id, ec);
 }
 
 void FileCheckpointStore::enforce_snapshot_cap() {
diff --git a/src/domain/session/session_client.hpp b/src/domain/session/session_client.hpp
index 70b1fb74e..4d5c94ae9 100644
--- a/src/domain/session/session_client.hpp
+++ b/src/domain/session/session_client.hpp
@@ -164,6 +164,8 @@ struct SessionOptions {
     std::string model_name;
     // Session-local reasoning choice. Missing inherits the saved model profile.
     std::optional<std::string> reasoning_effort;
+    // Per-agent sampling, layered over expert and saved model defaults.
+    std::optional<ModelSamplingOptions> sampling;
 
     // 可选 permission mode override(default / auto / plan / yolo;accept-edits 是 auto 的别名)。
     // 留空 = 用 daemon/TUI 共享默认值。
diff --git a/src/domain/session/session_data_diagnostics.cpp b/src/domain/session/session_data_diagnostics.cpp
index f0cfba8ce..cc7467b8c 100644
--- a/src/domain/session/session_data_diagnostics.cpp
+++ b/src/domain/session/session_data_diagnostics.cpp
@@ -51,7 +51,7 @@ nlohmann::json diagnose_session_data(
         result["cancelled"] = true;
         return true;
     };
-    const std::regex canonical("[0-9]{8}-[0-9]{6}-[0-9a-fA-F]{4}\\.jsonl");
+    const std::regex canonical("[0-9]{8}[-_][0-9]{6}[-_][0-9a-fA-F]{4}\\.jsonl");
     for (const auto& workspace : workspaces) {
         if (cancelled()) break;
         // Hashes, never cwd, select directories beneath the supplied root.
diff --git a/src/domain/session/session_manager.cpp b/src/domain/session/session_manager.cpp
index 90916ebe9..5ccefb39f 100644
--- a/src/domain/session/session_manager.cpp
+++ b/src/domain/session/session_manager.cpp
@@ -226,6 +226,7 @@ void SessionManager::start_session(const std::string& cwd,
     model_name_ = model;
     model_preset_ = model_preset;
     reasoning_effort_.reset();
+    sampling_ = {};
     surface_ = surface.empty() ? "unknown" : surface;
     no_workspace_ = no_workspace;
     memory_mode_.clear();
@@ -312,6 +313,7 @@ bool SessionManager::ensure_created() {
     meta.model = model_name_;
     meta.model_preset = model_preset_;
     meta.reasoning_effort = reasoning_effort_;
+    meta.sampling = sampling_;
     meta.title = pending_title_;
     meta.title_source = title_source_;
     meta.input_draft = input_draft_;
@@ -654,6 +656,7 @@ std::vector<ChatMessage> SessionManager::resume_session(const std::string& sessi
         worktree_ = meta.worktree;
         adopt_swarm_identity_locked(meta);
         reasoning_effort_ = meta.reasoning_effort;
+        sampling_ = meta.sampling;
         if (model_preset_.empty()) {
             model_preset_ = meta.model_preset;
         }
@@ -699,66 +702,6 @@ std::string SessionManager::last_error() const {
     return last_error_;
 }
 
-bool SessionManager::set_active_provider(const std::string& provider,
-                                         const std::string& model) {
-    return set_active_provider(provider, model, std::string{});
-}
-
-bool SessionManager::set_active_provider(const std::string& provider,
-                                         const std::string& model,
-                                         const std::string& model_preset) {
-    std::lock_guard<std::mutex> lk(mu_);
-    provider_name_ = provider;
-    model_name_ = model;
-    if (model_preset_ != model_preset) reasoning_effort_.reset();
-    model_preset_ = model_preset;
-    if (created_) {
-        return update_meta();
-    }
-    return true;
-}
-
-bool SessionManager::set_active_model_state(
-    const std::string& provider,
-    const std::string& model,
-    const std::string& model_preset,
-    const std::optional<std::string>& reasoning_effort,
-    bool persist_immediately) {
-    std::lock_guard<std::mutex> lk(mu_);
-    const auto old_provider = provider_name_;
-    const auto old_model = model_name_;
-    const auto old_preset = model_preset_;
-    const auto old_effort = reasoning_effort_;
-    if (!persist_immediately && old_provider == provider && old_model == model &&
-        old_preset == model_preset && old_effort == reasoning_effort) return true;
-    provider_name_ = provider;
-    model_name_ = model;
-    model_preset_ = model_preset;
-    reasoning_effort_ = reasoning_effort;
-    bool written = false;
-    try {
-        if (persist_immediately && !created_) ensure_created();
-        written = created_ ? update_meta() : !persist_immediately;
-    } catch (...) {
-        written = false;
-    }
-    if (!written) {
-        provider_name_ = old_provider;
-        model_name_ = old_model;
-        model_preset_ = old_preset;
-        reasoning_effort_ = old_effort;
-        // If initial materialization succeeded before a later write failed,
-        // make a best-effort attempt to restore the durable selection too.
-        try { if (created_) (void)update_meta(); } catch (...) {}
-    }
-    return written;
-}
-
-std::string SessionManager::current_model_preset() const {
-    std::lock_guard<std::mutex> lk(mu_);
-    return model_preset_;
-}
-
 void SessionManager::end_current_session() {
     std::lock_guard<std::mutex> lk(mu_);
     if (created_ && !finalized_) {
@@ -1043,6 +986,7 @@ std::string SessionManager::fork_session_to_new_id(
     meta.model           = model_name_;
     meta.model_preset    = model_preset_;
     meta.reasoning_effort = reasoning_effort_;
+    meta.sampling = sampling_;
     meta.title           = title;
     meta.title_source    = title.empty() ? std::string{} : "user";
     meta.input_draft     = std::string{};
@@ -1220,6 +1164,7 @@ bool SessionManager::update_meta(
     meta.model = model_name_;
     meta.model_preset = model_preset_;
     meta.reasoning_effort = reasoning_effort_;
+    meta.sampling = sampling_;
     meta.title = pending_title_;
     meta.title_source = title_source_;
     meta.input_draft = input_draft_;
@@ -1553,6 +1498,7 @@ void SessionManager::set_input_draft(std::string draft, nlohmann::json composer_
         meta.model = model_name_;
         meta.model_preset = model_preset_;
         meta.reasoning_effort = reasoning_effort_;
+        meta.sampling = sampling_;
         meta.title = pending_title_;
         meta.title_source = title_source_;
         meta.permission_mode = permission_mode_;
diff --git a/src/domain/session/session_manager.hpp b/src/domain/session/session_manager.hpp
index e489dc78b..463a468d7 100644
--- a/src/domain/session/session_manager.hpp
+++ b/src/domain/session/session_manager.hpp
@@ -227,6 +227,8 @@ class SessionManager {
     // reasoning choice; mesh children inherit both from their spawner.
     std::string current_cwd() const;
     std::optional<std::string> current_reasoning_effort() const;
+    bool set_sampling_overrides(ModelSamplingOptions sampling, bool persist_immediately = false);
+    ModelSamplingOptions current_sampling_overrides() const;
 
     // Persist the current expert identity selected for this session.
     void set_expert_binding(std::string expert_id, std::string member_id = {});
@@ -330,6 +332,7 @@ class SessionManager {
     std::string model_name_;
     std::string model_preset_;
     std::optional<std::string> reasoning_effort_;
+    ModelSamplingOptions sampling_;
     std::string surface_ = "tui";
     bool no_workspace_ = false;
     std::string memory_mode_;  // "off" = 本会话关闭记忆;空 = 开启
diff --git a/src/domain/session/session_manager_model.cpp b/src/domain/session/session_manager_model.cpp
new file mode 100644
index 000000000..91dba546a
--- /dev/null
+++ b/src/domain/session/session_manager_model.cpp
@@ -0,0 +1,90 @@
+#include "session_manager.hpp"
+
+#include <utility>
+
+namespace acecode {
+
+bool SessionManager::set_active_provider(const std::string& provider,
+                                         const std::string& model) {
+    return set_active_provider(provider, model, std::string{});
+}
+
+bool SessionManager::set_active_provider(const std::string& provider,
+                                         const std::string& model,
+                                         const std::string& model_preset) {
+    std::lock_guard<std::mutex> lk(mu_);
+    provider_name_ = provider;
+    model_name_ = model;
+    if (model_preset_ != model_preset) reasoning_effort_.reset();
+    model_preset_ = model_preset;
+    if (created_) {
+        return update_meta();
+    }
+    return true;
+}
+
+bool SessionManager::set_active_model_state(
+    const std::string& provider,
+    const std::string& model,
+    const std::string& model_preset,
+    const std::optional<std::string>& reasoning_effort,
+    bool persist_immediately) {
+    std::lock_guard<std::mutex> lk(mu_);
+    const auto old_provider = provider_name_;
+    const auto old_model = model_name_;
+    const auto old_preset = model_preset_;
+    const auto old_effort = reasoning_effort_;
+    if (!persist_immediately && old_provider == provider && old_model == model &&
+        old_preset == model_preset && old_effort == reasoning_effort) return true;
+    provider_name_ = provider;
+    model_name_ = model;
+    model_preset_ = model_preset;
+    reasoning_effort_ = reasoning_effort;
+    bool written = false;
+    try {
+        if (persist_immediately && !created_) ensure_created();
+        written = created_ ? update_meta() : !persist_immediately;
+    } catch (...) {
+        written = false;
+    }
+    if (!written) {
+        provider_name_ = old_provider;
+        model_name_ = old_model;
+        model_preset_ = old_preset;
+        reasoning_effort_ = old_effort;
+        // If initial materialization succeeded before a later write failed,
+        // make a best-effort attempt to restore the durable selection too.
+        try { if (created_) (void)update_meta(); } catch (...) {}
+    }
+    return written;
+}
+
+bool SessionManager::set_sampling_overrides(ModelSamplingOptions sampling, bool persist_immediately) {
+    std::lock_guard<std::mutex> lk(mu_);
+    const auto previous = sampling_;
+    sampling_ = std::move(sampling);
+    bool written = false;
+    try {
+        if (persist_immediately && !created_) ensure_created();
+        written = created_ ? update_meta() : !persist_immediately;
+    } catch (...) {
+        written = false;
+    }
+    if (!written) {
+        sampling_ = previous;
+        try { if (created_) (void)update_meta(); } catch (...) {}
+    }
+    return written;
+}
+
+ModelSamplingOptions SessionManager::current_sampling_overrides() const {
+    std::lock_guard<std::mutex> lk(mu_);
+    return sampling_;
+}
+
+std::string SessionManager::current_model_preset() const {
+    std::lock_guard<std::mutex> lk(mu_);
+    return model_preset_;
+}
+
+} // namespace acecode
diff --git a/src/domain/session/session_markdown_export.cpp b/src/domain/session/session_markdown_export.cpp
index 995494dd1..7576b000c 100644
--- a/src/domain/session/session_markdown_export.cpp
+++ b/src/domain/session/session_markdown_export.cpp
@@ -120,7 +120,7 @@ std::string sanitize_filename_stem(const std::string& preferred,
     std::string result;
     result.reserve(preferred.size());
     for (unsigned char c : preferred) {
-        if (c < 0x20 || c == '<' || c == '>' || c == ':' || c == '"' ||
+        if (c < 0x20 || c == '-' || c == '<' || c == '>' || c == ':' || c == '"' ||
             c == '/' || c == '\\' || c == '|' || c == '?' || c == '*') {
             result.push_back('_');
         } else {
@@ -132,6 +132,7 @@ std::string sanitize_filename_stem(const std::string& preferred,
     }
     if (result.empty()) result = fallback;
     if (result.empty()) result = "session";
+    std::replace(result.begin(), result.end(), '-', '_');
     if (is_reserved_windows_name(result)) result.insert(0, 1, '_');
     return result;
 }
diff --git a/src/domain/session/session_storage.cpp b/src/domain/session/session_storage.cpp
index 62ba97eeb..12731c160 100644
--- a/src/domain/session/session_storage.cpp
+++ b/src/domain/session/session_storage.cpp
@@ -145,11 +145,11 @@ std::string SessionStorage::generate_session_id() {
         << std::setw(4) << (tm_buf.tm_year + 1900)
         << std::setw(2) << (tm_buf.tm_mon + 1)
         << std::setw(2) << tm_buf.tm_mday
-        << '-'
+        << '_'
         << std::setw(2) << tm_buf.tm_hour
         << std::setw(2) << tm_buf.tm_min
         << std::setw(2) << tm_buf.tm_sec
-        << '-';
+        << '_';
 
     // 4 hex random chars
     std::random_device rd;
@@ -308,6 +308,9 @@ bool SessionStorage::write_meta(const std::string& meta_path, const SessionMeta&
     if (meta.reasoning_effort.has_value()) {
         j["reasoning_effort"] = *meta.reasoning_effort;
     }
+    if (!meta.sampling.empty()) {
+        j["sampling"] = model_sampling_options_to_json(meta.sampling);
+    }
     if (!meta.title.empty()) {
         j["title"] = meta.title;
     }
@@ -408,6 +411,12 @@ SessionMeta SessionStorage::read_meta(const std::string& meta_path) {
         if (j.contains("reasoning_effort") && j["reasoning_effort"].is_string()) {
             meta.reasoning_effort = j["reasoning_effort"].get<std::string>();
         }
+        if (j.contains("sampling")) {
+            std::string error;
+            const auto sampling = parse_model_sampling_overrides(j["sampling"], error);
+            if (!sampling) return {};
+            meta.sampling = *sampling;
+        }
         meta.title           = j.value("title",           std::string{});
         meta.title_source    = j.value("title_source",    std::string{});
         if (!meta.title.empty() && meta.title_source.empty()) {
@@ -472,22 +481,22 @@ SessionMeta SessionStorage::read_meta(const std::string& meta_path) {
 }
 
 // Canonical filename match:
-//   group 1 = session_id (YYYYMMDD-HHMMSS-XXXX)
+//   group 1 = session_id (new underscores or legacy hyphens)
 static const std::regex& session_filename_regex() {
     static const std::regex re(
-        R"(^(\d{8}-\d{6}-[0-9a-f]{4})\.jsonl$)");
+        R"(^(\d{8}[-_]\d{6}[-_][0-9a-f]{4})\.jsonl$)");
     return re;
 }
 
 static const std::regex& pid_session_filename_regex() {
     static const std::regex re(
-        R"(^(\d{8}-\d{6}-[0-9a-f]{4})-(\d+)\.jsonl$)");
+        R"(^(\d{8}[-_]\d{6}[-_][0-9a-f]{4})[-_](\d+)\.jsonl$)");
     return re;
 }
 
 static const std::regex& pid_meta_filename_regex() {
     static const std::regex re(
-        R"(^(\d{8}-\d{6}-[0-9a-f]{4})-(\d+)\.meta\.json$)");
+        R"(^(\d{8}[-_]\d{6}[-_][0-9a-f]{4})[-_](\d+)\.meta\.json$)");
     return re;
 }
 
@@ -510,7 +519,7 @@ static std::int64_t file_mtime_epoch(const fs::directory_entry& entry) {
     return static_cast<std::int64_t>(ftime.time_since_epoch().count());
 }
 
-// 自动生成的 id 是 YYYYMMDD-HHMMSS-XXXX,但 headless `-p --session-id`
+// 自动生成的 id 是 YYYYMMDD_HHMMSS_XXXX，旧连字符格式仍可读。headless `-p --session-id`
 // 允许调用方自定 [A-Za-z0-9_-]{1,64} 的 id(否则自定 id 会话在 TUI /resume、
 // Web 列表与 -p -c 里全部隐身)。下面这组手写判定就是按这个宽字符集匹配的,
 // 语义与原来的 meta_filename_regex + pid_meta_filename_regex 组合逐字符
@@ -550,7 +559,8 @@ static bool all_lower_hex(std::string_view text) {
 static bool is_pid_suffixed_session_stem(std::string_view stem) {
     constexpr std::size_t kMinLength = 8 + 1 + 6 + 1 + 4 + 1 + 1;
     if (stem.size() < kMinLength) return false;
-    if (stem[8] != '-' || stem[15] != '-' || stem[20] != '-') return false;
+    const auto separator = [](char c) { return c == '-' || c == '_'; };
+    if (!separator(stem[8]) || !separator(stem[15]) || !separator(stem[20])) return false;
     if (!all_ascii_digits(stem.substr(0, 8))) return false;
     if (!all_ascii_digits(stem.substr(9, 6))) return false;
     if (!all_lower_hex(stem.substr(16, 4))) return false;
diff --git a/src/domain/session/session_storage.hpp b/src/domain/session/session_storage.hpp
index dfb9aa5d1..81a39af86 100644
--- a/src/domain/session/session_storage.hpp
+++ b/src/domain/session/session_storage.hpp
@@ -1,6 +1,7 @@
 #pragma once
 
 #include "llm/llm_provider.hpp"
+#include "config/saved_models.hpp"
 #include "todo_state.hpp"
 #include <cstddef>
 #include <functional>
@@ -58,6 +59,7 @@ struct SessionMeta {
     std::string model;
     std::string model_preset;  // optional saved_models name for this session
     std::optional<std::string> reasoning_effort;  // absent = inherit model profile
+    ModelSamplingOptions sampling; // Explicit session overrides only.
     std::string title;  // optional window title; empty = unset
     // "user" = explicit rename, "user-cleared" = explicit empty title,
     // "generated" = hidden title generator, "legacy" = pre-provenance
@@ -130,7 +132,8 @@ class SessionStorage {
     // Returns first 16 hex chars of a hash of the canonical path.
     static std::string compute_project_hash(const std::string& cwd);
 
-    // Generate a new session ID: YYYYMMDD-HHMMSS-<4 hex random>
+    // Generate a new session ID: YYYYMMDD_HHMMSS_<4 hex random>.
+    // Existing hyphen IDs retain their identity and remain readable.
     static std::string generate_session_id();
 
     // Get the project directory for a given CWD: ~/.acecode/projects/<hash>/
diff --git a/src/domain/session/tool_result_storage.cpp b/src/domain/session/tool_result_storage.cpp
index 1d7d8e693..1395851cd 100644
--- a/src/domain/session/tool_result_storage.cpp
+++ b/src/domain/session/tool_result_storage.cpp
@@ -2,6 +2,7 @@
 
 #include "llm/tool_icons.hpp"
 #include "utils/encoding.hpp"
+#include "utils/generated_file_names.hpp"
 #include "utils/logger.hpp"
 #include "utils/utf8_path.hpp"
 #include "utils/uuid.hpp"
@@ -35,7 +36,7 @@ std::string sanitize_tool_call_id(std::string id) {
 std::string tool_result_path(const std::string& tool_results_dir,
                              const std::string& tool_call_id) {
     return path_to_utf8(path_from_utf8(tool_results_dir) /
-                        (sanitize_tool_call_id(tool_call_id) + "-" + generate_uuid_v7() + ".txt"));
+                        generated_file_name(sanitize_tool_call_id(tool_call_id) + "_" + generate_uuid_v7() + ".txt"));
 }
 
 std::string generate_preview(const std::string& content,
diff --git a/src/engine/agent/detail/agent_payloads.cpp b/src/engine/agent/detail/agent_payloads.cpp
index 0068c3b5d..b8484b764 100644
--- a/src/engine/agent/detail/agent_payloads.cpp
+++ b/src/engine/agent/detail/agent_payloads.cpp
@@ -1,5 +1,6 @@
 #include "agent_payloads.hpp"
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 #include "session/session_manager.hpp"
 #include "utils/encoding.hpp"
 #include "prompt/context_usage_breakdown.hpp"
@@ -123,7 +124,7 @@ std::string build_session_scratch_dir(const std::string& cwd,
     const std::string session_id = session_manager->ensure_active_session_id();
     if (session_id.empty()) return {};
     return path_to_utf8(path_from_utf8(cwd) / ".acecode" / "tmp" /
-                        ("session-" + session_id));
+                        generated_file_name("session_" + session_id));
 }
 
 } // namespace acecode::agent::detail
diff --git a/src/host/channels/core/conversations.cpp b/src/host/channels/core/conversations.cpp
index 762b2bd31..be5c057d1 100644
--- a/src/host/channels/core/conversations.cpp
+++ b/src/host/channels/core/conversations.cpp
@@ -563,7 +563,7 @@ void Conversations::submit(const im::Inbound& inbound) {
         nlohmann::json saved = nlohmann::json::array();
         std::filesystem::create_directories(deps_.media_dir);
         for (const auto& file : files) {
-            const auto temp = deps_.media_dir / ("in-" + platform::secure_random_token(16));
+            const auto temp = deps_.media_dir / ("in_" + platform::secure_random_token(16));
             std::string error;
             if (!transport->download(file, temp, &error)) {
                 std::error_code ec;
diff --git a/src/host/loop/loop_store.cpp b/src/host/loop/loop_store.cpp
index 89c918f4a..7b855c3e0 100644
--- a/src/host/loop/loop_store.cpp
+++ b/src/host/loop/loop_store.cpp
@@ -2,6 +2,7 @@
 
 #include "utils/paths.hpp"
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 #include "utils/uuid.hpp"
 
 #include <sqlite3.h>
@@ -256,7 +257,7 @@ LoopStore::~LoopStore() {
 }
 
 std::filesystem::path LoopStore::default_database_path() {
-    return path_from_utf8(get_acecode_dir()) / "scheduled-loops.sqlite3";
+    return compatible_generated_path(path_from_utf8(get_acecode_dir()), "scheduled-loops.sqlite3");
 }
 
 bool LoopStore::initialize(StoreError* error) {
diff --git a/src/host/session_host/mesh/mesh_agent_service.hpp b/src/host/session_host/mesh/mesh_agent_service.hpp
index c8ecda368..9f4b49268 100644
--- a/src/host/session_host/mesh/mesh_agent_service.hpp
+++ b/src/host/session_host/mesh/mesh_agent_service.hpp
@@ -20,6 +20,7 @@
 // resume / destroy, which may join agent workers.
 
 #include "session/agent_fork_history.hpp"
+#include "config/saved_models.hpp"
 #include "session/agent_path.hpp"
 #include "session/inter_agent_message.hpp"
 #include "session/scoped_subscription.hpp"
@@ -71,6 +72,7 @@ struct SpawnArgs {
     std::string agent_type;
     std::string model;
     std::optional<std::string> reasoning_effort;
+    std::optional<ModelSamplingOptions> sampling;
     ForkTurns fork;
 };
 
diff --git a/src/host/session_host/mesh/mesh_agent_spawn.cpp b/src/host/session_host/mesh/mesh_agent_spawn.cpp
index 06a9f5ea5..1612eab14 100644
--- a/src/host/session_host/mesh/mesh_agent_spawn.cpp
+++ b/src/host/session_host/mesh/mesh_agent_spawn.cpp
@@ -76,6 +76,7 @@ SpawnResult MeshAgentService::spawn(const ToolContext& ctx, const SpawnArgs& arg
         return result;
     }
     SessionOptions opts;
+    opts.sampling = args.sampling;
     if (!args.model.empty()) {
         const auto names = saved_model_names();
         if (std::find(names.begin(), names.end(), args.model) == names.end()) {
diff --git a/src/host/session_host/session_model_resolution.cpp b/src/host/session_host/session_model_resolution.cpp
new file mode 100644
index 000000000..10fde6bba
--- /dev/null
+++ b/src/host/session_host/session_model_resolution.cpp
@@ -0,0 +1,88 @@
+#include "session_model_resolution.hpp"
+#include "session_registry.hpp"
+#include "config/saved_models_revision.hpp"
+
+#include <algorithm>
+#include <stdexcept>
+
+namespace acecode::session_model_detail {
+
+ModelConfigSnapshot snapshot_model_config(const SessionRegistryDeps& deps) {
+    if (!deps.config) return {};
+    if (deps.config_mutex) {
+        std::shared_lock<std::shared_mutex> lock(*deps.config_mutex);
+        return {
+            std::make_shared<AppConfig>(*deps.config),
+            current_saved_models_revision(),
+        };
+    }
+    return {
+        std::make_shared<AppConfig>(*deps.config),
+        current_saved_models_revision(),
+    };
+}
+
+// Only explicitly enabled effort-capable HTTP routes accept a session choice.
+bool supports_session_reasoning_effort(const ModelProfile& profile,
+                                       const std::string& effort) {
+    if ((profile.provider != "openai" && profile.provider != "anthropic") ||
+        !profile.reasoning.has_value()) return false;
+    const auto& reasoning = *profile.reasoning;
+    return reasoning.supported &&
+        (reasoning.mandatory || reasoning.enabled.value_or(reasoning.default_enabled)) &&
+        !effort.empty() &&
+        std::find(reasoning.supported_efforts.begin(),
+                  reasoning.supported_efforts.end(), effort) != reasoning.supported_efforts.end();
+}
+
+std::optional<std::string> apply_session_reasoning_effort(
+    ModelProfile& profile, const std::optional<std::string>& effort,
+    bool strict) {
+    if (!effort.has_value()) return std::nullopt;
+    if (!supports_session_reasoning_effort(profile, *effort)) {
+        if (strict) throw SessionReasoningValidationError();
+        return std::nullopt;
+    }
+    profile.reasoning->enabled = true;
+    profile.reasoning->effort = *effort;
+    profile.reasoning->max_tokens.reset();
+    return effort;
+}
+
+void apply_session_sampling(ModelProfile& profile, const ModelSamplingOptions& sampling) {
+    profile.sampling = merge_model_sampling_options(profile.sampling, sampling);
+    std::string error;
+    if (!validate_model_sampling_support(profile, error)) {
+        throw std::invalid_argument(error);
+    }
+}
+
+SessionModelResolvedTarget resolve_target_for_name(
+    const SessionRegistryDeps& deps,
+    const std::string& name,
+    const std::optional<std::string>& effort,
+    bool strict_effort,
+    const ModelSamplingOptions& sampling) {
+    auto snapshot = snapshot_model_config(deps);
+    SessionModelResolvedTarget target;
+    target.revision = snapshot.revision;
+    target.config = snapshot.config;
+    if (!snapshot.config) return target;
+    const auto found = std::find_if(
+        snapshot.config->saved_models.begin(),
+        snapshot.config->saved_models.end(),
+        [&name](const ModelProfile& candidate) {
+            return candidate.name == name;
+        });
+    if (found != snapshot.config->saved_models.end()) {
+        target.profile = *found;
+        apply_session_sampling(*target.profile, sampling);
+        const auto applied = apply_session_reasoning_effort(
+            *target.profile, effort, strict_effort);
+        target.state = session_model_state_from_profile(*snapshot.config, *target.profile);
+        target.state.reasoning_effort = applied;
+    }
+    return target;
+}
+
+} // namespace acecode::session_model_detail
diff --git a/src/host/session_host/session_model_resolution.hpp b/src/host/session_host/session_model_resolution.hpp
new file mode 100644
index 000000000..0433b5855
--- /dev/null
+++ b/src/host/session_host/session_model_resolution.hpp
@@ -0,0 +1,27 @@
+#pragma once
+
+#include "provider/session_model_binding.hpp"
+
+namespace acecode {
+struct SessionRegistryDeps;
+
+namespace session_model_detail {
+
+struct ModelConfigSnapshot {
+    // Shared immutable config used by the resolver and provider construction.
+    std::shared_ptr<const AppConfig> config;
+    SavedModelsRevision revision = 0;
+};
+
+ModelConfigSnapshot snapshot_model_config(const SessionRegistryDeps& deps);
+std::optional<std::string> apply_session_reasoning_effort(
+    ModelProfile& profile, const std::optional<std::string>& effort,
+    bool strict = false);
+void apply_session_sampling(ModelProfile& profile, const ModelSamplingOptions& sampling);
+SessionModelResolvedTarget resolve_target_for_name(
+    const SessionRegistryDeps& deps, const std::string& name,
+    const std::optional<std::string>& effort = std::nullopt,
+    bool strict_effort = false, const ModelSamplingOptions& sampling = {});
+
+} // namespace session_model_detail
+} // namespace acecode
diff --git a/src/host/session_host/session_registry.cpp b/src/host/session_host/session_registry.cpp
index 68479f006..4b7239fe5 100644
--- a/src/host/session_host/session_registry.cpp
+++ b/src/host/session_host/session_registry.cpp
@@ -1,4 +1,5 @@
 #include "session_registry.hpp"
+#include "session_model_resolution.hpp"
 #include "session/session_load_metrics.hpp"
 
 #include "session/compact_checkpoint.hpp"
@@ -32,8 +33,8 @@
 #include "utils/cwd_hash.hpp"
 #include "platform/power_inhibitor.hpp"
 #include "utils/utf8_path.hpp"
+#include "utils/generated_file_names.hpp"
 #include "utils/scope_exit.hpp"
-
 #include <algorithm>
 #include <cctype>
 #include <filesystem>
@@ -50,6 +51,11 @@ namespace acecode {
 
 namespace {
 
+using session_model_detail::snapshot_model_config;
+using session_model_detail::apply_session_reasoning_effort;
+using session_model_detail::apply_session_sampling;
+using session_model_detail::resolve_target_for_name;
+
 std::string session_dir_name_from_id(const std::string& session_id) {
     std::string out;
     out.reserve(session_id.size());
@@ -161,79 +167,6 @@ struct ResolvedSessionModel {
     SavedModelsRevision revision = 0;
 };
 
-struct ModelConfigSnapshot {
-    std::shared_ptr<const AppConfig> config;
-    SavedModelsRevision revision = 0;
-};
-
-ModelConfigSnapshot snapshot_model_config(const SessionRegistryDeps& deps) {
-    if (!deps.config) return {};
-    if (deps.config_mutex) {
-        std::shared_lock<std::shared_mutex> lock(*deps.config_mutex);
-        return {
-            std::make_shared<AppConfig>(*deps.config),
-            current_saved_models_revision(),
-        };
-    }
-    return {
-        std::make_shared<AppConfig>(*deps.config),
-        current_saved_models_revision(),
-    };
-}
-
-// Only explicitly enabled effort-capable HTTP routes accept a session choice.
-bool supports_session_reasoning_effort(const ModelProfile& profile,
-                                       const std::string& effort) {
-    if ((profile.provider != "openai" && profile.provider != "anthropic") ||
-        !profile.reasoning.has_value()) return false;
-    const auto& reasoning = *profile.reasoning;
-    return reasoning.supported &&
-        (reasoning.mandatory || reasoning.enabled.value_or(reasoning.default_enabled)) &&
-        !effort.empty() &&
-        std::find(reasoning.supported_efforts.begin(),
-                  reasoning.supported_efforts.end(), effort) != reasoning.supported_efforts.end();
-}
-
-std::optional<std::string> apply_session_reasoning_effort(
-    ModelProfile& profile, const std::optional<std::string>& effort,
-    bool strict = false) {
-    if (!effort.has_value()) return std::nullopt;
-    if (!supports_session_reasoning_effort(profile, *effort)) {
-        if (strict) throw SessionReasoningValidationError();
-        return std::nullopt;
-    }
-    profile.reasoning->enabled = true;
-    profile.reasoning->effort = *effort;
-    profile.reasoning->max_tokens.reset();
-    return effort;
-}
-
-SessionModelResolvedTarget resolve_target_for_name(
-    const SessionRegistryDeps& deps,
-    const std::string& name,
-    const std::optional<std::string>& effort = std::nullopt,
-    bool strict_effort = false) {
-    auto snapshot = snapshot_model_config(deps);
-    SessionModelResolvedTarget target;
-    target.revision = snapshot.revision;
-    target.config = snapshot.config;
-    if (!snapshot.config) return target;
-    const auto found = std::find_if(
-        snapshot.config->saved_models.begin(),
-        snapshot.config->saved_models.end(),
-        [&name](const ModelProfile& candidate) {
-            return candidate.name == name;
-        });
-    if (found != snapshot.config->saved_models.end()) {
-        target.profile = *found;
-        const auto applied = apply_session_reasoning_effort(
-            *target.profile, effort, strict_effort);
-        target.state = session_model_state_from_profile(*snapshot.config, *target.profile);
-        target.state.reasoning_effort = applied;
-    }
-    return target;
-}
-
 ResolvedSessionModel resolve_from_profile(
     std::shared_ptr<const AppConfig> config,
     SavedModelsRevision revision,
@@ -679,7 +612,7 @@ BuiltinCommandResult execute_plan_builtin(SessionEntry& entry,
 } // namespace
 
 std::string default_no_workspace_cache_root() {
-    return path_to_utf8(path_from_utf8(get_acecode_dir()) / "cache" / "no-workspace");
+    return path_to_utf8(compatible_generated_path(path_from_utf8(get_acecode_dir()) / "cache", "no-workspace"));
 }
 
 std::string no_workspace_session_cwd(const std::string& session_id,
@@ -795,6 +728,10 @@ std::string SessionRegistry::create(const SessionOptions& opts) {
     SessionOptions resolved = with_resolved_workspace(deps_, create_opts, id);
 
     auto entry = make_entry_locked(id, resolved, nullptr);
+    if (!entry->sampling.empty() &&
+        !entry->sm->set_sampling_overrides(entry->sampling, true)) {
+        throw std::runtime_error("session sampling metadata could not be persisted");
+    }
     if (resolved.reasoning_effort) {
         const auto state = entry->model_binding->state_snapshot();
         if (!entry->sm->set_active_model_state(
@@ -877,6 +814,38 @@ SessionRegistry::make_entry_locked(const std::string& id,
         : (opts.workspace_hash.empty()
         ? compute_cwd_hash(entry->cwd)
         : opts.workspace_hash);
+    if (!entry->expert_id.empty()) {
+        if (deps_.expert_registry) {
+            entry->expert = deps_.expert_registry->find(entry->cwd, entry->expert_id);
+        }
+        if (!entry->expert_member_id.empty() &&
+            (!entry->expert ||
+             !entry->expert->is_declared_member(entry->expert_member_id))) {
+            entry->expert.reset();
+        }
+        if (!entry->expert) {
+            entry->expert_missing = true;
+            if (!resumed_meta) {
+                throw std::invalid_argument("unknown or invalid expert component: " +
+                                            entry->expert_id);
+            }
+        }
+    } else if (!entry->expert_member_id.empty()) {
+        entry->expert_missing = true;
+        if (!resumed_meta) {
+            throw std::invalid_argument(
+                "expert member requires a team expert binding");
+        }
+    }
+    entry->sampling = opts.sampling.value_or(resumed_meta ? resumed_meta->sampling : ModelSamplingOptions{});
+    entry->effective_sampling = merge_model_sampling_options(
+        entry->expert ? entry->expert->selected_sampling(entry->expert_member_id) : ModelSamplingOptions{},
+        entry->sampling);
+    if (resolved_model.profile) {
+        apply_session_sampling(*resolved_model.profile, entry->effective_sampling);
+    } else if (!entry->effective_sampling.empty()) {
+        throw std::invalid_argument("sampling requires a resolvable model profile");
+    }
     entry->model_binding = std::make_shared<SessionModelBinding>();
     if (resolved_model.profile.has_value() && resolved_model.config) {
         SessionModelResolvedTarget target;
@@ -889,12 +858,16 @@ SessionRegistry::make_entry_locked(const std::string& id,
         // `(session:<id>)` profiles stay on the explicit target inside the
         // binding and never enter this saved-model resolver.
         auto initial_resolver = [this, effort = resolved_model.state.reasoning_effort,
-                                 strict = opts.reasoning_effort.has_value()](const std::string& name) {
-            return resolve_target_for_name(deps_, name, effort, strict);
+                                 strict = opts.reasoning_effort.has_value(),
+                                 sampling = entry->effective_sampling](const std::string& name) {
+            return resolve_target_for_name(deps_, name, effort, strict, sampling);
         };
         const auto installed = entry->model_binding->install_explicit(
             std::move(target), initial_resolver);
         if (!installed.ok) {
+            if (!entry->effective_sampling.empty()) {
+                throw std::runtime_error("session sampling provider construction failed");
+            }
             if (opts.reasoning_effort) {
                 throw std::runtime_error("session reasoning provider construction failed");
             }
@@ -914,29 +887,6 @@ SessionRegistry::make_entry_locked(const std::string& id,
     const AppConfig* entry_config = resolved_model.config
         ? resolved_model.config.get()
         : deps_.config;
-    if (!entry->expert_id.empty()) {
-        if (deps_.expert_registry) {
-            entry->expert = deps_.expert_registry->find(entry->cwd, entry->expert_id);
-        }
-        if (!entry->expert_member_id.empty() &&
-            (!entry->expert ||
-             !entry->expert->is_declared_member(entry->expert_member_id))) {
-            entry->expert.reset();
-        }
-        if (!entry->expert) {
-            entry->expert_missing = true;
-            if (!resumed_meta) {
-                throw std::invalid_argument("unknown or invalid expert component: " +
-                                            entry->expert_id);
-            }
-        }
-    } else if (!entry->expert_member_id.empty()) {
-        entry->expert_missing = true;
-        if (!resumed_meta) {
-            throw std::invalid_argument(
-                "expert member requires a team expert binding");
-        }
-    }
     const ExpertCapabilityScopes expert_scopes =
         entry->expert
             ? entry->expert->selected_capabilities(entry->expert_member_id)
@@ -975,6 +925,7 @@ SessionRegistry::make_entry_locked(const std::string& id,
         // 子会话身份写进 meta(lazy:首条消息落盘时随初始 meta 一起写)。
         entry->sm->set_parent_session_id(entry->parent_session_id);
     }
+    entry->sm->set_sampling_overrides(entry->sampling);
     if (opts.inherited_worktree.active()) {
         // 子会话共享父会话的 worktree:身份进 meta(系统提示 / UI / resume 都
         // 以它为准),标 inherited 让 ExitWorktree 拒绝、AgentLoop 据此算写边界。
@@ -1186,6 +1137,7 @@ bool SessionRegistry::resume(const std::string& id, const SessionOptions& opts)
     entry_opts.model_name = resolved.model_name;
     entry_opts.permission_mode = resolved.permission_mode;
     entry_opts.reasoning_effort = resolved.reasoning_effort;
+    entry_opts.sampling = resolved.sampling;
 
     entry_opts.inherit_dangerous_mode = resolved.inherit_dangerous_mode;
     entry_opts.expert_id = meta.expert_id;
@@ -1199,6 +1151,7 @@ bool SessionRegistry::resume(const std::string& id, const SessionOptions& opts)
     const auto resumed_model = entry->model_binding->state_snapshot();
     entry->sm->set_active_model_state(resumed_model.provider, resumed_model.model,
                                      resumed_model.name, resumed_model.reasoning_effort);
+    if (!entry->sm->set_sampling_overrides(entry->sampling)) return false;
     restore_loop_history(*entry, messages);
     // worktree 会话恢复:meta 记录的 worktree 目录还在就把 AgentLoop 的
     // 工作目录切回去(SessionEntry::cwd / 会话存储位置不动 —— worktree
@@ -1758,6 +1711,21 @@ ExpertSwitchResult SessionRegistry::switch_expert(
     }
 
     auto expert = std::make_shared<ExpertDefinition>(std::move(*resolved));
+    // Fail before enqueueing an incompatible expert. Revalidate again at the
+    // control boundary in case the model changed while this switch was queued.
+    {
+        std::lock_guard<std::mutex> model_lock(entry->model_control_mu);
+        const auto sampling = merge_model_sampling_options(expert->selected_sampling(), entry->sampling);
+        if (!model_sampling_options_equal(sampling, entry->effective_sampling)) {
+            try {
+                const auto state = entry->model_binding->state_snapshot();
+                const auto target = resolve_target_for_name(deps_, state.name, state.reasoning_effort, false, sampling);
+                if (!target.profile) throw std::invalid_argument("sampling requires a resolvable model profile");
+            } catch (const std::invalid_argument& ex) {
+                return {ExpertSwitchStatus::Failed, std::nullopt, ex.what()};
+            }
+        }
+    }
     const ExpertCapabilityScopes expert_scopes =
         expert->selected_capabilities();
     const ToolCapabilityPolicy tool_policy =
@@ -1808,13 +1776,29 @@ ExpertSwitchResult SessionRegistry::switch_expert(
             // A later switch or metadata-only detach superseded this queued
             // intent. Treat it as consumed without touching AgentLoop state.
             if (active.expert_binding_revision != binding_revision) return true;
+            std::lock_guard<std::mutex> model_lock(active.model_control_mu);
+            const auto sampling = merge_model_sampling_options(expert->selected_sampling(), active.sampling);
+            std::optional<SessionModelRuntimeSnapshot> previous_model;
+            if (!model_sampling_options_equal(sampling, active.effective_sampling)) {
+                const auto state = active.model_binding->state_snapshot();
+                SessionModelResolver resolver = [&registry, effort = state.reasoning_effort, sampling](const std::string& name) {
+                    return resolve_target_for_name(registry.deps_, name, effort, false, sampling);
+                };
+                auto target = resolver(state.name);
+                if (!target.profile) return false;
+                previous_model = active.model_binding->runtime_snapshot();
+                const auto installed = active.model_binding->install_explicit(std::move(target), resolver);
+                if (!installed.ok) return false;
+            }
             if (active.sm &&
                 !active.sm->set_expert_binding_and_input_draft(
                     expert->id, {}, draft_text)) {
+                if (previous_model) active.model_binding->install_cloned_snapshot(std::move(*previous_model));
                 LOG_ERROR("[registry] failed to persist expert switch for " +
                           active.id);
                 return false;
             }
+            active.effective_sampling = sampling;
             active.expert_id = expert->id;
             active.expert_member_id.clear();
             active.expert_missing = false;
@@ -1947,14 +1931,21 @@ bool SessionRegistry::switch_model(const std::string& id,
 
     std::lock_guard<std::mutex> model_lock(entry->model_control_mu);
     const auto before = entry->model_binding->state_snapshot();
+    try {
+        auto candidate = profile;
+        apply_session_sampling(candidate, entry->effective_sampling);
+    } catch (const std::invalid_argument& ex) {
+        if (error) *error = ex.what();
+        return false;
+    }
     const auto effort = before.name == profile.name ? before.reasoning_effort : std::nullopt;
     auto config_snapshot = snapshot_model_config(deps_);
     if (!config_snapshot.config) {
         if (error) *error = "config unavailable";
         return false;
     }
-    SessionModelResolver resolver = [this, effort](const std::string& name) {
-        return resolve_target_for_name(deps_, name, effort);
+    SessionModelResolver resolver = [this, effort, sampling = entry->effective_sampling](const std::string& name) {
+        return resolve_target_for_name(deps_, name, effort, false, sampling);
     };
 
     ApplyModelDeps apply_deps;
@@ -1996,8 +1987,8 @@ SessionRegistry::reload_model_profile(const std::string& id, bool force) {
 
     std::lock_guard<std::mutex> model_lock(entry->model_control_mu);
     const auto effort = entry->model_binding->state_snapshot().reasoning_effort;
-    SessionModelResolver resolver = [this, effort](const std::string& name) {
-        return resolve_target_for_name(deps_, name, effort);
+    SessionModelResolver resolver = [this, effort, sampling = entry->effective_sampling](const std::string& name) {
+        return resolve_target_for_name(deps_, name, effort, false, sampling);
     };
 
     auto result = entry->model_binding->ensure_current(
@@ -2026,8 +2017,8 @@ SessionReasoningResult SessionRegistry::set_reasoning_effort(
     // Lock order: model control -> binding -> session metadata; no queue gate.
     std::lock_guard<std::mutex> model_lock(entry->model_control_mu);
     result.state = entry->model_binding->state_snapshot();
-    SessionModelResolver resolver = [this, effort](const std::string& name) {
-        return resolve_target_for_name(deps_, name, effort, true);
+    SessionModelResolver resolver = [this, effort, sampling = entry->effective_sampling](const std::string& name) {
+        return resolve_target_for_name(deps_, name, effort, true, sampling);
     };
     SessionModelResolvedTarget target;
     try {
@@ -2036,6 +2027,9 @@ SessionReasoningResult SessionRegistry::set_reasoning_effort(
         result.status = SessionReasoningStatus::InvalidEffort;
         result.error = ex.what();
         return result;
+    } catch (const std::invalid_argument& ex) {
+        result.error = ex.what();
+        return result;
     }
     if (!target.profile || !target.config) {
         result.status = SessionReasoningStatus::Unavailable;
diff --git a/src/host/session_host/session_registry.hpp b/src/host/session_host/session_registry.hpp
index dfe06a3ba..2701c1bfc 100644
--- a/src/host/session_host/session_registry.hpp
+++ b/src/host/session_host/session_registry.hpp
@@ -96,6 +96,10 @@ struct SessionEntry {
     // snapshot acquisition, including persistence failure rollback.
     // Never acquire the AgentLoop queue gate while holding this mutex.
     std::mutex model_control_mu;
+    // Explicit task override and effective expert + task overlay. Mutations
+    // after construction hold model_control_mu; resolvers capture by value.
+    ModelSamplingOptions sampling;
+    ModelSamplingOptions effective_sampling;
     std::shared_ptr<SessionModelBinding> model_binding;
     std::shared_ptr<SkillRegistry>       skill_registry;
     // Inputs required to re-apply a changed global Skill policy without
diff --git a/src/host/session_host/tools/mesh_agent_tools.cpp b/src/host/session_host/tools/mesh_agent_tools.cpp
index 8e6e41c98..1cd092964 100644
--- a/src/host/session_host/tools/mesh_agent_tools.cpp
+++ b/src/host/session_host/tools/mesh_agent_tools.cpp
@@ -126,6 +126,7 @@ ToolImpl create_spawn_tool(std::weak_ptr<MeshAgentService> weak, const AppConfig
     const bool expose_model_overrides = config.swarm.mesh.expose_model_overrides;
     json properties = {
         {"message", string_property("Initial plain-text task for the new agent.")},
+        {"sampling", model_sampling_overrides_schema()},
         {"task_name", string_property(
             "Task name for the new agent. Use lowercase letters, digits, and underscores.")},
         {"agent_type", string_property(
@@ -151,7 +152,7 @@ ToolImpl create_spawn_tool(std::weak_ptr<MeshAgentService> weak, const AppConfig
         auto service = weak.lock();
         if (!service) return failure(kUnavailable);
         std::set<std::string> allowed = {"message", "task_name", "agent_type", "fork_turns",
-                                         "fork_context"};
+                                         "fork_context", "sampling"};
         if (expose_model_overrides) allowed.insert({"model", "reasoning_effort"});
         json args;
         if (auto error = parse_object(arguments, allowed, args); !error.empty()) {
@@ -161,6 +162,11 @@ ToolImpl create_spawn_tool(std::weak_ptr<MeshAgentService> weak, const AppConfig
             return failure("fork_context is not supported in MultiAgentV2; use fork_turns instead");
         }
         mesh::SpawnArgs spawn;
+        if (args.contains("sampling")) {
+            std::string error;
+            spawn.sampling = parse_model_sampling_overrides(args["sampling"], error);
+            if (!spawn.sampling) return failure(error);
+        }
         std::string fork_turns;
         std::string effort;
         std::string error;
diff --git a/src/host/session_host/tools/spawn_subagent_tool.cpp b/src/host/session_host/tools/spawn_subagent_tool.cpp
index 09771cf83..33a1c6365 100644
--- a/src/host/session_host/tools/spawn_subagent_tool.cpp
+++ b/src/host/session_host/tools/spawn_subagent_tool.cpp
@@ -313,6 +313,7 @@ ToolImpl create_spawn_subagent_tool(std::shared_ptr<SubagentToolDeps> deps) {
                 {"type", "string"},
                 {"description", "Optional selected expert ID from the current "
                                 "team expert. Only a team lead may use it."}}},
+            {"sampling", model_sampling_overrides_schema()},
             {"timeout_seconds", json{
                 {"type", "integer"},
                 {"description", "Optional wait timeout. 0 or omitted = wait "
@@ -351,6 +352,12 @@ ToolImpl create_spawn_subagent_tool(std::shared_ptr<SubagentToolDeps> deps) {
             args.contains("expert_member") && args["expert_member"].is_string()
                 ? args["expert_member"].get<std::string>() : std::string{};
         const int timeout_seconds = parse_timeout_seconds(args);
+        std::optional<ModelSamplingOptions> sampling;
+        if (args.contains("sampling")) {
+            std::string error;
+            sampling = parse_model_sampling_overrides(args["sampling"], error);
+            if (!sampling) return error_result(error);
+        }
 
         // 深度限制:子代理不能再派生。父会话 id 从注入的 SessionManager 拿。
         std::string parent_id;
@@ -422,6 +429,7 @@ ToolImpl create_spawn_subagent_tool(std::shared_ptr<SubagentToolDeps> deps) {
             }
         }
         opts.model_name = model_name;
+        opts.sampling = sampling;
         if (opts.model_name.empty() && ctx.session_manager) {
             // Read the live parent selection, including TUI parents outside the
             // registry. An empty preset preserves the configured fallback.
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 6332ed2c1..838c0ff84 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -74,9 +74,7 @@ add_executable(acecode_unit_tests ${ACECODE_TEST_SOURCES})
 add_executable(acecode_runtime_log_fixture
     ${CMAKE_CURRENT_SOURCE_DIR}/utils/helpers/runtime_log_fixture.cpp
     ${CMAKE_SOURCE_DIR}/src/base/utils/append_file.cpp)
-target_include_directories(acecode_runtime_log_fixture PRIVATE
-    ${CMAKE_SOURCE_DIR}/external/ftxui/src)
-target_link_libraries(acecode_runtime_log_fixture PRIVATE acecode_include_roots)
+target_link_libraries(acecode_runtime_log_fixture PRIVATE acecode_include_roots ftxui::component)
 if(MSVC)
     set_target_properties(acecode_runtime_log_fixture PROPERTIES
         MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
@@ -219,9 +217,9 @@ if(APPLE)
         ${ACECODE_COMPUTER_USE_NATIVE_MAC_SMOKE_SOURCES})
     target_link_libraries(computer_use_native_mac_smoke PRIVATE acecode_include_roots)
     target_link_libraries(computer_use_native_mac_smoke PRIVATE nlohmann_json::nlohmann_json
-        "-framework AppKit" "-framework ApplicationServices")
+        "-framework AppKit" "-framework ApplicationServices" "-framework ScreenCaptureKit")
     target_compile_options(computer_use_native_mac_smoke PRIVATE
-        "$<$<COMPILE_LANGUAGE:OBJCXX>:-fobjc-arc>")
+        "$<$<COMPILE_LANGUAGE:OBJCXX>:-fobjc-arc>" -mmacosx-version-min=14.0)
     set_target_properties(computer_use_native_mac_smoke PROPERTIES
         OBJCXX_STANDARD 17 OBJCXX_STANDARD_REQUIRED YES
         MACOSX_BUNDLE_BUNDLE_NAME "ACECode Computer Use Fixture"
diff --git a/tests/computer_use/helpers/native_macos_smoke.mm b/tests/computer_use/helpers/native_macos_smoke.mm
index d1b205efa..1f02a4ca4 100644
--- a/tests/computer_use/helpers/native_macos_smoke.mm
+++ b/tests/computer_use/helpers/native_macos_smoke.mm
@@ -1,11 +1,14 @@
 #import <AppKit/AppKit.h>
 #import <ApplicationServices/ApplicationServices.h>
+#import <ScreenCaptureKit/ScreenCaptureKit.h>
 #include "computer_use/availability.hpp"
 #include "computer_use/runtime.hpp"
 #include <chrono>
 #include <cmath>
 #include <cstdlib>
 #include <iostream>
+#include <libproc.h>
+#include <memory>
 #include <stdexcept>
 #include <thread>
 #include <unistd.h>
@@ -201,6 +204,102 @@ void check_pointer_color(const json& state, double red, double green, double blu
         std::to_string(color.redComponent) + "," + std::to_string(color.greenComponent) + "," +
         std::to_string(color.blueComponent) + " at " + std::to_string(x) + "," + std::to_string(y));
 }
+NSArray<NSDictionary*>* pointer_windows() {
+    // Identify only this fixture's real helper, not another app or a pointer
+    // drawn into a tool attachment. No production test hook is involved.
+    NSString* expected = [NSBundle.mainBundle.executablePath.stringByDeletingLastPathComponent
+        stringByAppendingPathComponent:@"acecode-computer-use"];
+    NSArray* windows = CFBridgingRelease(CGWindowListCopyWindowInfo(
+        kCGWindowListOptionOnScreenOnly | kCGWindowListExcludeDesktopElements, kCGNullWindowID));
+    NSMutableArray* matches = [NSMutableArray new];
+    for (NSDictionary* window in windows) {
+        const pid_t pid = [window[(__bridge NSString*)kCGWindowOwnerPID] intValue];
+        proc_bsdinfo info{};
+        char path[PROC_PIDPATHINFO_MAXSIZE]{};
+        if (proc_pidinfo(pid, PROC_PIDTBSDINFO, 0, &info, sizeof(info)) != sizeof(info) ||
+            info.pbi_ppid != getpid() || proc_pidpath(pid, path, sizeof(path)) <= 0 ||
+            ![expected isEqualToString:[NSString stringWithUTF8String:path]]) continue;
+        [matches addObject:window];
+    }
+    return matches;
+}
+void check_overlay(ACEInputFixture* fixture, NSView* target, double red, double green, double blue) {
+    require(CGPreflightScreenCaptureAccess(), "Independent overlay capture requires Screen Recording for the fixture launch");
+    NSArray<NSDictionary*>* windows = pointer_windows();
+    require(windows.count == 1, "Exactly one real helper overlay is on the desktop");
+    NSDictionary* overlay = windows.firstObject;
+    const CGWindowID id = [overlay[(__bridge NSString*)kCGWindowNumber] unsignedIntValue];
+    require([overlay[(__bridge NSString*)kCGWindowAlpha] doubleValue] > 0.99, "Native overlay is not transparent at window level");
+    require([overlay[(__bridge NSString*)kCGWindowLayer] integerValue] >= NSStatusWindowLevel, "Native overlay is above normal windows");
+    CGRect bounds{};
+    require(CGRectMakeWithDictionaryRepresentation((__bridge CFDictionaryRef)overlay[(__bridge NSString*)kCGWindowBounds], &bounds),
+        "Native overlay has WindowServer geometry");
+    __block NSRect expected;
+    __block bool focused;
+    main_sync(^{
+        expected = [fixture.window convertRectToScreen:[target convertRect:target.bounds toView:nil]];
+        expected.origin.y = NSScreen.screens.firstObject.frame.size.height - NSMaxY(expected);
+        focused = fixture.window.isKeyWindow && NSWorkspace.sharedWorkspace.frontmostApplication.processIdentifier == getpid();
+    });
+    require(focused, "Native overlay does not steal application or window focus");
+    require(NSPointInRect(NSMakePoint(bounds.origin.x + 10, bounds.origin.y + 10), expected),
+        "Actual overlay hotspot is over the expected fixture control");
+
+    struct Capture {
+        dispatch_semaphore_t ready = dispatch_semaphore_create(0);
+        __strong SCShareableContent* content = nil;
+        __strong NSBitmapImageRep* image = nil;
+        __strong NSError* error = nil;
+    };
+    auto capture = std::make_shared<Capture>();
+    [SCShareableContent getShareableContentExcludingDesktopWindows:YES onScreenWindowsOnly:YES
+        completionHandler:^(SCShareableContent* content, NSError* error) {
+            capture->content = content; capture->error = error; dispatch_semaphore_signal(capture->ready);
+        }];
+    require(dispatch_semaphore_wait(capture->ready, dispatch_time(DISPATCH_TIME_NOW, 3 * NSEC_PER_SEC)) == 0,
+        "Independent overlay enumeration completes");
+    SCWindow* window = nil;
+    for (SCWindow* candidate in capture->content.windows) if (candidate.windowID == id) window = candidate;
+    require(window && window.isOnScreen, "ScreenCaptureKit independently sees the on-screen helper overlay");
+    SCContentFilter* filter = [[SCContentFilter alloc] initWithDesktopIndependentWindow:window];
+    SCStreamConfiguration* config = [SCStreamConfiguration new];
+    config.width = std::lround(bounds.size.width * filter.pointPixelScale);
+    config.height = std::lround(bounds.size.height * filter.pointPixelScale);
+    config.showsCursor = NO;
+    config.ignoreShadowsSingleWindow = YES;
+    if (@available(macOS 14.2, *)) config.includeChildWindows = NO;
+    [SCScreenshotManager captureImageWithFilter:filter configuration:config
+        completionHandler:^(CGImageRef image, NSError* error) {
+            if (image) capture->image = [[NSBitmapImageRep alloc] initWithCGImage:image];
+            capture->error = error; dispatch_semaphore_signal(capture->ready);
+        }];
+    require(dispatch_semaphore_wait(capture->ready, dispatch_time(DISPATCH_TIME_NOW, 3 * NSEC_PER_SEC)) == 0 && capture->image,
+        "Independent capture of actual overlay pixels completes");
+    NSBitmapImageRep* image = capture->image;
+    const int x = std::lround(13 * image.pixelsWide / bounds.size.width);
+    const int y = std::lround(20 * image.pixelsHigh / bounds.size.height);
+    NSColor* color = screenshot_pixel(image, x, y);
+    require(color.alphaComponent > 0.9 && std::abs(color.redComponent - red) < 0.08 &&
+        std::abs(color.greenComponent - green) < 0.08 && std::abs(color.blueComponent - blue) < 0.08,
+        "Actual WindowServer overlay pixels match the theme, independently of pointer_composite; got " +
+        std::to_string(color.redComponent) + "," + std::to_string(color.greenComponent) + "," +
+        std::to_string(color.blueComponent) + ", alpha=" + std::to_string(color.alphaComponent));
+    const char* folder = std::getenv("ACECODE_MAC_FIXTURE_ARTIFACTS");
+    if (folder) {
+        NSString* directory = [NSString stringWithUTF8String:folder];
+        require([NSFileManager.defaultManager createDirectoryAtPath:directory withIntermediateDirectories:YES attributes:nil error:nil],
+            "Create optional overlay artifact directory");
+        NSData* png = [image representationUsingType:NSBitmapImageFileTypePNG properties:@{}];
+        require([png writeToFile:[directory stringByAppendingPathComponent:@"native-overlay.png"] atomically:YES],
+            "Save independently captured helper overlay");
+    }
+}
+void check_overlay_removed() {
+    const auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (pointer_windows().count != 0 && std::chrono::steady_clock::now() < deadline)
+        std::this_thread::sleep_for(std::chrono::milliseconds(20));
+    require(pointer_windows().count == 0, "Release removes the real WindowServer overlay");
+}
 int run(ACEInputFixture* fixture, bool inputs) {
     try {
         const auto readiness = cu::availability();
@@ -209,6 +308,10 @@ int run(ACEInputFixture* fixture, bool inputs) {
             std::cerr << "Native fixture not verified; required OS permissions: " << readiness.dump() << '\n';
             return 77;
         }
+        if (inputs && !CGPreflightScreenCaptureAccess()) {
+            std::cerr << "Native overlay not verified; independent fixture capture requires Screen Recording.\n";
+            return 77;
+        }
         __block int native_window;
         main_sync(^{ native_window = static_cast<int>(fixture.window.windowNumber); });
         const int window = native_window;
@@ -264,11 +367,12 @@ int run(ACEInputFixture* fixture, bool inputs) {
         state = observe(window);
         require(state["output"]["screenshots"][0]["cursor"].value("visible", false), "ACE pointer is composed after clicking");
         check_pointer_color(state, 37.0 / 255, 99.0 / 255, 235.0 / 255);
+        check_overlay(fixture, fixture.button, 37.0 / 255, 99.0 / 255, 235.0 / 255);
         check_image(state);
         auto click = coordinate(state, window, "click", element(state, "Count click"));
         call(click); settle();
         main_sync(^{ count = fixture.clicks; });
-        require(count == 2, "Screenshot-coordinate mouse click reaches same button");
+        require(count == 2, "Click passes through the visible native overlay to the same button");
         state = observe(window, false);
         use_element(state, "perform_secondary_action", window, "Count click", {{"secondary_action", "invoke"}});
         main_sync(^{ count = fixture.clicks; });
@@ -285,10 +389,16 @@ int run(ACEInputFixture* fixture, bool inputs) {
         require(value == "native AX value", "Writable AX control updates");
         state = observe(window, false);
         use_element(state, "click", window, "Editable fixture text");
+        call({{"action", "release"}});
+        check_overlay_removed();
         state = observe(window, false);
         auto key = target(state, "press_key", window); key["key"] = "Cmd+A"; call(key); settle();
+        check_overlay(fixture, fixture.field, 37.0 / 255, 99.0 / 255, 235.0 / 255);
+        call({{"action", "release"}});
+        check_overlay_removed();
         state = observe(window, false);
         auto type = target(state, "type_text", window); type["text"] = "ACE \u4e2d\u6587 \U0001f642"; call(type); settle();
+        check_overlay(fixture, fixture.field, 37.0 / 255, 99.0 / 255, 235.0 / 255);
         main_sync(^{ value = fixture.field.stringValue.UTF8String; });
         require(value == "ACE \u4e2d\u6587 \U0001f642", "Unicode keyboard input and Cmd+A preserve text exactly; actual value: " + value);
         const auto press = [&](const char* chord) {
@@ -329,6 +439,7 @@ int run(ACEInputFixture* fixture, bool inputs) {
         state = observe(window);
         require(state["output"]["screenshots"][0]["cursor"].value("visible", false), "Pointer survives appearance updates");
         check_pointer_color(state, 1, 0.4, 0);
+        check_overlay(fixture, fixture.canvas, 1, 0.4, 0);
         check_image(state);
         std::cout << "Passed native scrolling, drag and ACE/plain pointer pixels." << std::endl;
 
@@ -389,6 +500,7 @@ int run(ACEInputFixture* fixture, bool inputs) {
             "; menu events: " + menu_events + "; target: " + element(state, "Fixture menu action").dump());
         std::cout << "Passed owned sheet and context-menu capture/input." << std::endl;
         call({{"action", "release"}});
+        check_overlay_removed();
         state = observe(window);
         require(!state["output"]["screenshots"][0]["cursor"].value("visible", true), "Release removes the pointer from screenshots");
         cu::shutdown();
@@ -407,6 +519,10 @@ int main(int argc, char** argv) {
     }
     @autoreleasepool {
         [NSApplication sharedApplication];
+        if ([NSWorkspace.sharedWorkspace.frontmostApplication.bundleIdentifier isEqualToString:@"com.apple.loginwindow"]) {
+            std::cerr << "Native overlay/input verification requires an unlocked desktop; not verified.\n";
+            return 77;
+        }
         [NSApp setActivationPolicy:NSApplicationActivationPolicyRegular];
         NSMenu* menu = [NSMenu new];
         NSMenuItem* app = [menu addItemWithTitle:@"Fixture" action:nil keyEquivalent:@""];
diff --git a/tests/config/config_recovery_test.cpp b/tests/config/config_recovery_test.cpp
index 7d6653006..e46b357f8 100644
--- a/tests/config/config_recovery_test.cpp
+++ b/tests/config/config_recovery_test.cpp
@@ -1,6 +1,7 @@
 #include "config/config_recovery.hpp"
 #include "config/config.hpp"
 #include "utils/logger.hpp"
+#include "utils/uuid.hpp"
 
 #include <gtest/gtest.h>
 #include <nlohmann/json.hpp>
@@ -19,7 +20,7 @@ class TempRecoveryConfig {
     TempRecoveryConfig() {
         static std::atomic<unsigned long long> sequence{0};
         root = fs::temp_directory_path() /
-            ("acecode-config-recovery-test-" +
+            ("acecode_config_recovery_test_" + acecode::generated_file_name(acecode::generate_uuid()) + "_" +
              std::to_string(sequence.fetch_add(1)));
         fs::create_directories(root);
         config = root / "config.json";
@@ -84,15 +85,25 @@ TEST(ConfigRecoveryPersistence, PathsStayBesideExplicitConfig) {
     TempRecoveryConfig temp;
     const auto paths = acecode::config_recovery_paths(temp.config.string());
 
-    EXPECT_EQ(fs::path(paths.root_dir), temp.root / "config-backups");
+    EXPECT_EQ(fs::path(paths.root_dir), temp.root / "config_backups");
     EXPECT_EQ(fs::path(paths.last_good_path),
-              temp.root / "config-backups" / "last-good" / "config.json");
+              temp.root / "config_backups" / "last_good" / "config.json");
     EXPECT_EQ(fs::path(paths.invalid_dir),
-              temp.root / "config-backups" / "invalid");
+              temp.root / "config_backups" / "invalid");
     EXPECT_EQ(fs::path(paths.staging_dir),
-              temp.root / "config-backups" / "staging");
+              temp.root / "config_backups" / "staging");
     EXPECT_EQ(fs::path(paths.notice_path),
-              temp.root / "config-backups" / "recovery-notice.json");
+              temp.root / "config_backups" / "recovery_notice.json");
+}
+
+TEST(ConfigRecoveryPersistence, ReusesLegacySnapshotsWithoutCreatingAnEmptyStore) {
+    TempRecoveryConfig temp;
+    const auto legacy = temp.root / "config-backups" / "last-good" / "config.json";
+    fs::create_directories(legacy.parent_path());
+    { std::ofstream out(legacy); out << "{}"; }
+    const auto paths = acecode::config_recovery_paths(temp.config.string());
+    EXPECT_EQ(fs::path(paths.last_good_path), legacy);
+    EXPECT_FALSE(fs::exists(temp.root / "config_backups"));
 }
 
 TEST(ConfigRecoveryPersistence, SnapshotAndArchivesPreserveExactBytes) {
@@ -126,7 +137,7 @@ TEST(ConfigRecoveryPersistence, SnapshotAndArchivesPreserveExactBytes) {
 
 TEST(ConfigRecoveryPersistence, NoticeReadAndAcknowledgeAreDurableAndIdempotent) {
     TempRecoveryConfig temp;
-    const fs::path invalid = temp.root / "config-backups" / "invalid" /
+    const fs::path invalid = temp.root / "config_backups" / "invalid" /
         "config-invalid.json";
     std::string error;
 
@@ -206,7 +217,7 @@ TEST(ConfigRecoveryLoad, MalformedJsonRestoresSnapshotAndArchivesExactBytes) {
     ASSERT_FALSE(notice.invalid_backup_path.empty());
     EXPECT_EQ(read_bytes(notice.invalid_backup_path), invalid);
     EXPECT_EQ(fs::path(notice.invalid_backup_dir),
-              temp.root / "config-backups" / "invalid");
+              temp.root / "config_backups" / "invalid");
 
     const std::string logs = read_bytes(log_path);
     EXPECT_NE(logs.find("active config rejected"), std::string::npos);
diff --git a/tests/daemon/concurrent_session_e2e_test.cpp b/tests/daemon/concurrent_session_e2e_test.cpp
index f48cedc30..4dd539e02 100644
--- a/tests/daemon/concurrent_session_e2e_test.cpp
+++ b/tests/daemon/concurrent_session_e2e_test.cpp
@@ -78,8 +78,8 @@ TEST(SessionConcurrencyE2E, TwoRealSubprocessesProduceCanonicalSessionFiles) {
         << "project_dir should be created by a writer subprocess: "
         << project_dir.string();
 
-    std::regex canonical_re(R"(^\d{8}-\d{6}-[0-9a-f]{4}\.jsonl$)");
-    std::regex pid_re(R"(^\d{8}-\d{6}-[0-9a-f]{4}-\d+\.jsonl$)");
+    std::regex canonical_re(R"(^\d{8}_\d{6}_[0-9a-f]{4}\.jsonl$)");
+    std::regex pid_re(R"(^\d{8}[-_]\d{6}[-_][0-9a-f]{4}[-_]\d+\.jsonl$)");
     std::vector<fs::path> jsonl_paths;
     for (const auto& e : fs::directory_iterator(project_dir)) {
         if (!e.is_regular_file()) continue;
diff --git a/tests/desktop/desktop_pet_layout_test.cpp b/tests/desktop/desktop_pet_layout_test.cpp
index 4c84e2d55..fac66cb7e 100644
--- a/tests/desktop/desktop_pet_layout_test.cpp
+++ b/tests/desktop/desktop_pet_layout_test.cpp
@@ -324,7 +324,7 @@ TEST(DesktopPetLayout, DragTrackerHandlesNegativeAndInvalidCoordinates) {
     EXPECT_EQ(tracker.move(-1926), 1);
 }
 
-// 场景:1920 宽工作区上把 430 宽的鲸鱼娘窗口拖到不同位置后松手。
+// 场景:1920 宽工作区上把 430 宽的陪伴宠物窗口拖到不同位置后松手。
 // 期望:窗口中心进入离右边 1/4 窗口宽(107.5)以内或越过右边 → 吸附右边(+1);左边同理(-1);
 // 屏幕中间不吸附;副屏负坐标同样按工作区边界判断;空窗口/空工作区不吸附。
 TEST(DesktopPetLayout, DockSideDependsOnDistanceToTheWorkAreaEdge) {
@@ -344,6 +344,21 @@ TEST(DesktopPetLayout, DockSideDependsOnDistanceToTheWorkAreaEdge) {
     EXPECT_EQ(desktop_pet_dock_side({0, 0, 430, 315}, {0, 0, 0, 0}), 0);
 }
 
+// 场景:拖到屏幕边松手 / 右键菜单切换宠物时,判断当前宠物能不能吸附到左右边。
+// bug 表现:吸附曾写死只认 "whale",回形针和 Rover 拖到边上只会被拉回工作区,也没有偷看的样子。
+// 期望:三只陪伴宠物都有趴边偷看素材(peek.png),可以吸附;虚拟办公室、空串、大小写不符的 id 不吸附。
+// 菜单里每加一种陪伴宠物都要配一张 peek.png,循环那段就是提醒。
+TEST(DesktopPetLayout, CompanionPetsHaveEdgePeekButTheOfficeDoesNot) {
+    EXPECT_TRUE(desktop_pet_has_edge_peek("clippy"));
+    EXPECT_TRUE(desktop_pet_has_edge_peek("rover"));
+    EXPECT_TRUE(desktop_pet_has_edge_peek("whale"));
+    EXPECT_FALSE(desktop_pet_has_edge_peek("office"));
+    EXPECT_FALSE(desktop_pet_has_edge_peek(""));
+    EXPECT_FALSE(desktop_pet_has_edge_peek("Whale"));
+    for (const auto& kind : kDesktopPetKinds)
+        EXPECT_EQ(desktop_pet_has_edge_peek(kind.id), std::string_view(kind.id) != "office") << kind.id;
+}
+
 // 场景:吸附时窗口有一部分在工作区外(右边越界、上下越界)。
 // 期望:贴右边时窗口右缘等于工作区右缘,贴左边时左缘等于工作区左缘;竖直位置夹回工作区;
 // side 为 0 时原样返回。
diff --git a/tests/environment/data_dir_migration_test.cpp b/tests/environment/data_dir_migration_test.cpp
index 555bf022f..8f4c5076c 100644
--- a/tests/environment/data_dir_migration_test.cpp
+++ b/tests/environment/data_dir_migration_test.cpp
@@ -222,6 +222,8 @@ TEST_F(DataDirMigrationTest, ExclusionRules) {
     EXPECT_TRUE(migration_excludes_entry(fs::path("config.json.lock")));
     EXPECT_TRUE(migration_excludes_entry(fs::path("projects") / "a" / ".writer.lock"));
     EXPECT_TRUE(migration_excludes_entry(fs::path(acecode::kDataDirRedirectFileName)));
+    EXPECT_TRUE(migration_excludes_entry(fs::path("data_dir.redirect.json")));
+    EXPECT_FALSE(migration_excludes_entry(fs::path("projects") / "data_dir.redirect.json"));
     EXPECT_FALSE(migration_excludes_entry(fs::path("projects") / "a" / "s.jsonl"));
     EXPECT_FALSE(migration_excludes_entry(fs::path("runbook.md")));
     EXPECT_FALSE(migration_excludes_entry(fs::path("memory")));
@@ -284,6 +286,7 @@ TEST_F(DataDirMigrationTest, MigrationCopiesAndWritesPointer) {
     EXPECT_FALSE(fs::exists(target / "tmp"));
     EXPECT_FALSE(fs::exists(target / "config.json.lock"));
     EXPECT_FALSE(fs::exists(target / acecode::kDataDirRedirectFileName));
+    EXPECT_FALSE(fs::exists(target / "data_dir.redirect.json"));
 
     // 复制字节数 = 被复制文件大小之和(排除项不计)。
     unsigned long long expected = 0;
@@ -365,7 +368,7 @@ TEST_F(DataDirMigrationTest, CleanupPreviousKeepsPointerOnlyInDefaultDir) {
     ASSERT_TRUE(acecode::write_data_dir_redirect(s(default_dir), r));
 
     EXPECT_EQ(cleanup_previous_data_dir(s(default_dir), s(default_dir)), "");
-    EXPECT_TRUE(fs::exists(default_dir / acecode::kDataDirRedirectFileName));
+    EXPECT_TRUE(fs::exists(acecode::path_from_utf8(acecode::data_dir_redirect_path(s(default_dir)))));
     EXPECT_FALSE(fs::exists(default_dir / "config.json"));
     EXPECT_FALSE(fs::exists(default_dir / "projects"));
 
@@ -389,6 +392,26 @@ TEST_F(DataDirMigrationTest, CleanupPreviousKeepsPointerOnlyInDefaultDir) {
     EXPECT_FALSE(back->cleanup_pending);
 }
 
+TEST_F(DataDirMigrationTest, CleanupPreservesBothRedirectNamingGenerations) {
+    populate_source(default_dir);
+    write_file(default_dir / acecode::kDataDirRedirectFileName, "{}");
+    acecode::DataDirRedirect redirect;
+    redirect.data_dir = s(root / "elsewhere");
+    redirect.previous_data_dir = s(default_dir);
+    redirect.cleanup_pending = true;
+    ASSERT_TRUE(acecode::write_data_dir_redirect(s(default_dir), redirect));
+    // An older installation still owns the hyphenated pointer when both exist.
+    write_file(default_dir / "data_dir.redirect.json", "{}");
+
+    EXPECT_EQ(cleanup_previous_data_dir(s(default_dir), s(default_dir)), "");
+    EXPECT_TRUE(fs::exists(default_dir / acecode::kDataDirRedirectFileName));
+    EXPECT_TRUE(fs::exists(default_dir / "data_dir.redirect.json"));
+    const auto retained = acecode::read_data_dir_redirect(s(default_dir));
+    ASSERT_TRUE(retained.has_value());
+    EXPECT_EQ(retained->data_dir, redirect.data_dir);
+    EXPECT_FALSE(data_dir_status(acecode::RunMode::User).previous_exists);
+}
+
 // 场景:状态汇总与 100 MB 阈值。
 // 期望:大迁移 + pending + 旧目录仍有内容 → cleanup_prompt;小迁移 → 不提示但
 // previous_dir 仍报出;acknowledge 后不再提示;没有指针 → 纯默认状态。
diff --git a/tests/experts/expert_registry_test.cpp b/tests/experts/expert_registry_test.cpp
index 7f1ae46c7..bca50b71f 100644
--- a/tests/experts/expert_registry_test.cpp
+++ b/tests/experts/expert_registry_test.cpp
@@ -79,6 +79,98 @@ acecode::ExpertDraft make_agent(std::string id = "reviewer",
 
 } // namespace
 
+TEST(ExpertRegistry, SamplingPresetsRoundTripPreserveAndClear) {
+    TempDir temp;
+    acecode::ExpertRegistry registry(temp.path / "global");
+    auto draft = make_agent();
+    draft.sampling.temperature = 0.0;
+    draft.sampling.min_p = 0.0;
+    draft.sampling.top_k = 20;
+    std::string error;
+    ASSERT_TRUE(registry.create_global(draft, &error)) << error;
+    auto found = registry.find(temp.path.string(), draft.id);
+    ASSERT_TRUE(found);
+    EXPECT_EQ(found->selected_sampling().temperature, 0.0);
+    auto detail = acecode::expert_definition_to_json(*found, true);
+    detail["lead"] = {{"id", draft.lead.id}, {"instructions", draft.lead.instructions}};
+    EXPECT_EQ(detail["sampling"]["min_p"], 0);
+    auto round_trip = acecode::ExpertRegistry::draft_from_json(detail, &error);
+    ASSERT_TRUE(round_trip) << error;
+    EXPECT_EQ(round_trip->sampling.top_k, 20);
+
+    auto old_client = make_agent();
+    old_client.description = "Edited by old client";
+    ASSERT_TRUE(registry.update_global(draft.id, old_client, &error)) << error;
+    found = registry.find(temp.path.string(), draft.id);
+    ASSERT_TRUE(found);
+    EXPECT_EQ(found->sampling.top_k, 20);
+
+    const auto manifest_path = temp.path / "global" / draft.id / "expert.json";
+    for (const auto& clear : {nlohmann::json(nullptr), nlohmann::json::object()}) {
+        ASSERT_TRUE(registry.update_global(draft.id, draft, &error)) << error;
+        nlohmann::json manifest;
+        { std::ifstream input(manifest_path); input >> manifest; }
+        manifest["agents"][0]["sampling"] = {{"temperature", 0.6}};
+        { std::ofstream output(manifest_path); output << manifest.dump(); }
+        found = registry.find(temp.path.string(), draft.id);
+        ASSERT_TRUE(found);
+        EXPECT_EQ(acecode::expert_definition_to_json(*found, true)["sampling"]["temperature"], 0.6);
+        auto payload = detail;
+        payload["sampling"] = clear;
+        auto parsed = acecode::ExpertRegistry::draft_from_json(payload, &error);
+        ASSERT_TRUE(parsed) << error;
+        ASSERT_TRUE(registry.update_global(draft.id, *parsed, &error)) << error;
+        found = registry.find(temp.path.string(), draft.id);
+        ASSERT_TRUE(found);
+        EXPECT_TRUE(found->sampling.empty());
+        EXPECT_TRUE(found->selected_sampling().empty());
+    }
+    for (const auto& invalid : {nlohmann::json{{"top_k", 1.5}}, nlohmann::json{{"typo", 0.3}}}) {
+        auto payload = detail;
+        payload["sampling"] = invalid;
+        EXPECT_FALSE(acecode::ExpertRegistry::draft_from_json(payload, &error));
+        EXPECT_FALSE(error.empty());
+    }
+}
+
+TEST(ExpertRegistry, TeamProjectsMembersSamplingAndLegacyAgentOverrides) {
+    TempDir temp;
+    acecode::ExpertRegistry registry(temp.path / "global");
+    auto lead = make_agent("coordinator");
+    lead.sampling.temperature = 0.2;
+    auto member = make_agent("reviewer");
+    member.sampling.temperature = 0.4;
+    member.sampling.top_k = 20;
+    std::string error;
+    ASSERT_TRUE(registry.create_global(lead, &error)) << error;
+    ASSERT_TRUE(registry.create_global(member, &error)) << error;
+    acecode::ExpertDraft team;
+    team.id = "sample-team";
+    team.type = acecode::ExpertType::Team;
+    team.display_name = "Sampling team";
+    team.lead_expert_id = lead.id;
+    team.member_expert_ids = {member.id};
+    team.sampling.top_p = 0.8;
+    team.sampling.temperature = 0.9;
+    ASSERT_TRUE(registry.create_global(team, &error)) << error;
+    const auto found = registry.find(temp.path.string(), team.id);
+    ASSERT_TRUE(found);
+    EXPECT_EQ(found->selected_sampling().temperature, 0.2);
+    EXPECT_EQ(found->selected_sampling(member.id).temperature, 0.4);
+    EXPECT_EQ(found->selected_sampling(member.id).top_k, 20);
+    EXPECT_EQ(found->selected_sampling(member.id).top_p, 0.8);
+
+    const auto manifest_path = temp.path / "global" / member.id / "expert.json";
+    nlohmann::json manifest;
+    { std::ifstream input(manifest_path); input >> manifest; }
+    manifest["agents"][0]["sampling"] = {{"temperature", 0}};
+    { std::ofstream output(manifest_path); output << manifest.dump(); }
+    const auto overridden = registry.find(temp.path.string(), team.id);
+    ASSERT_TRUE(overridden);
+    EXPECT_EQ(overridden->selected_sampling(member.id).temperature, 0);
+    EXPECT_EQ(overridden->selected_sampling(member.id).top_k, 20);
+}
+
 TEST(ExpertRegistry, CreatesDiscoversUpdatesAndDeletesGlobalExpert) {
     TempDir temp;
     acecode::ExpertRegistry registry(temp.path / "global");
diff --git a/tests/feedback/feedback_upload_test.cpp b/tests/feedback/feedback_upload_test.cpp
index 515f237c3..9e75248e6 100644
--- a/tests/feedback/feedback_upload_test.cpp
+++ b/tests/feedback/feedback_upload_test.cpp
@@ -132,12 +132,12 @@ TEST(FeedbackUpload, BuildPackageIncludesSessionMetadataAndLogTail) {
     ASSERT_TRUE(result.ok) << result.error;
     EXPECT_TRUE(fs::is_regular_file(result.package_path));
     EXPECT_EQ(result.package_filename,
-              "acecode-feedback-20260618-010203-abcd-20260618-010203-windows-x64-QA-BOX-alice-example.zip");
+              "acecode_feedback_20260618_010203_abcd_20260618_010203_windows_x64_QA_BOX_alice_example.zip");
     EXPECT_TRUE(result.log_included);
     EXPECT_EQ(result.log_tail_bytes, 16u);
 
     EXPECT_EQ(read_zip_entry(result.package_path,
-                             "session/20260618-010203-abcd.jsonl"),
+                             "session/20260618_010203_abcd.jsonl"),
               "{\"role\":\"user\",\"content\":\"hello\"}\n");
     EXPECT_EQ(read_zip_entry(result.package_path, "logs/acecode.log.tail.txt"),
               "klmnopqrstuvwxyz");
@@ -177,7 +177,7 @@ TEST(FeedbackUpload, BuildDesktopPackageCanBeLogOnly) {
     ASSERT_TRUE(result.ok) << result.error;
     EXPECT_TRUE(fs::is_regular_file(result.package_path));
     EXPECT_EQ(result.package_filename,
-              "acecode-feedback-desktop-20260618-010203-windows-x64-Desk-tester.zip");
+              "acecode_feedback_desktop_20260618_010203_windows_x64_Desk_tester.zip");
     EXPECT_TRUE(result.log_included);
     EXPECT_EQ(read_zip_entry(result.package_path, "logs/desktop.log.tail.txt"),
               "desktop log line 2\n");
@@ -212,7 +212,7 @@ TEST(FeedbackUpload, BuildDesktopPackageMayIncludeSelectedSession) {
 
     auto result = acecode::feedback::build_feedback_package(req);
     ASSERT_TRUE(result.ok) << result.error;
-    EXPECT_EQ(read_zip_entry(result.package_path, "session/sid-selected.jsonl"),
+    EXPECT_EQ(read_zip_entry(result.package_path, "session/sid_selected.jsonl"),
               "{\"role\":\"user\",\"content\":\"selected\"}\n");
     EXPECT_EQ(read_zip_entry(result.package_path, "logs/desktop.log.tail.txt"),
               "desktop log");
@@ -578,7 +578,7 @@ TEST(FeedbackUpload, DuplicateLogEntryNamesDoNotOverwriteEachOther) {
     EXPECT_EQ(read_zip_entry(result.package_path, "logs/daemon.log.tail.txt.2"), "second");
 }
 
-TEST(FeedbackUpload, LogEntryNameDefaultsToTheSourceFilename) {
+TEST(FeedbackUpload, LogEntryNameUsesUnderscoresForLegacySourceFilename) {
     TempDir tmp("acecode_feedback_default_entry");
     const fs::path log = tmp.root / "daemon-2026-06-18.log";
     write_text(log, "daemon line");
@@ -591,10 +591,26 @@ TEST(FeedbackUpload, LogEntryNameDefaultsToTheSourceFilename) {
     auto result = acecode::feedback::build_feedback_package(req);
     ASSERT_TRUE(result.ok) << result.error;
     EXPECT_EQ(read_zip_entry(result.package_path,
-                             "logs/daemon-2026-06-18.log.tail.txt"),
+                             "logs/daemon_2026_06_18.log.tail.txt"),
               "daemon line");
 }
 
+TEST(FeedbackUpload, DiscoversBothNamingGenerationsAndUsesModificationTime) {
+    TempDir tmp("acecode_feedback_mixed_logs");
+    const auto old_log = tmp.root / "desktop-2099-12-31.log";
+    const auto new_log = tmp.root / "desktop_2026_10_16.log";
+    write_text(old_log, "old");
+    write_text(new_log, "new");
+    fs::last_write_time(old_log, fs::file_time_type::clock::now() - std::chrono::hours(1));
+    fs::last_write_time(new_log, fs::file_time_type::clock::now());
+    const auto latest = acecode::feedback::latest_desktop_log_path(tmp.root);
+    ASSERT_TRUE(latest);
+    EXPECT_EQ(*latest, new_log);
+    EXPECT_EQ(acecode::feedback::make_feedback_package_filename(
+        "old-session-id", "2026-10-16T10:00:00Z", "windows-x64", "QA-BOX", "user-name").find('-'),
+        std::string::npos);
+}
+
 TEST(FeedbackUpload, LatestRotatedLogPathPicksNewestMatchingBase) {
     TempDir tmp("acecode_feedback_latest_rotated");
     const fs::path logs = tmp.root / "logs";
@@ -637,13 +653,13 @@ TEST(FeedbackUpload, PackageFilenameAddsAvailableMachineSuffixFields) {
         acecode::feedback::make_feedback_package_filename(
             "sid", "2026-06-18T01:02:03Z", "windows/x64", "Build Box",
             "\xE7\x94\xA8\xE6\x88\xB7"),
-        "acecode-feedback-sid-20260618-010203-windows-x64-Build-Box"
-        "-xe7x94xa8xe6x88xb7.zip");
+        "acecode_feedback_sid_20260618_010203_windows_x64_Build_Box"
+        "_xe7x94xa8xe6x88xb7.zip");
 
     EXPECT_EQ(
         acecode::feedback::make_feedback_package_filename(
             "sid", "2026-06-18T01:02:03Z", "windows-x64", "", ""),
-        "acecode-feedback-sid-20260618-010203-windows-x64.zip");
+        "acecode_feedback_sid_20260618_010203_windows_x64.zip");
 }
 
 TEST(FeedbackUpload, BuildPackageSucceedsWhenLogIsMissing) {
@@ -764,11 +780,11 @@ TEST(FeedbackUpload, BuildPackageAttachesSessionTrajectory) {
 
     auto result = acecode::feedback::build_feedback_package(req);
     ASSERT_TRUE(result.ok) << result.error;
-    EXPECT_EQ(read_zip_entry(result.package_path, "session/sid-traj.trajectory.jsonl"),
+    EXPECT_EQ(read_zip_entry(result.package_path, "session/sid_traj.trajectory.jsonl"),
               trajectory_text);
     ASSERT_GE(result.included_files.size(), 3u);
-    EXPECT_EQ(result.included_files[0], "session/sid-traj.jsonl");
-    EXPECT_EQ(result.included_files[1], "session/sid-traj.trajectory.jsonl");
+    EXPECT_EQ(result.included_files[0], "session/sid_traj.jsonl");
+    EXPECT_EQ(result.included_files[1], "session/sid_traj.trajectory.jsonl");
     ASSERT_TRUE(result.trajectory.has_value());
     EXPECT_TRUE(result.trajectory->included);
     EXPECT_FALSE(result.trajectory->truncated);
@@ -776,7 +792,7 @@ TEST(FeedbackUpload, BuildPackageAttachesSessionTrajectory) {
     auto metadata = nlohmann::json::parse(
         read_zip_entry(result.package_path, "feedback.json"));
     ASSERT_TRUE(metadata.contains("trajectory"));
-    EXPECT_EQ(metadata["trajectory"]["entry_name"], "session/sid-traj.trajectory.jsonl");
+    EXPECT_EQ(metadata["trajectory"]["entry_name"], "session/sid_traj.trajectory.jsonl");
     EXPECT_EQ(metadata["trajectory"]["path"], acecode::path_to_utf8(trajectory));
     EXPECT_TRUE(metadata["trajectory"]["available"].get<bool>());
     EXPECT_EQ(metadata["trajectory"]["size_bytes"], trajectory_text.size());
@@ -801,7 +817,7 @@ TEST(FeedbackUpload, MissingTrajectoryIsRecordedButDoesNotFailPackage) {
 
     auto result = acecode::feedback::build_feedback_package(req);
     ASSERT_TRUE(result.ok) << result.error;
-    EXPECT_FALSE(zip_entry_exists(result.package_path, "session/sid-none.trajectory.jsonl"));
+    EXPECT_FALSE(zip_entry_exists(result.package_path, "session/sid_none.trajectory.jsonl"));
     for (const auto& name : result.included_files) {
         EXPECT_EQ(name.find("trajectory"), std::string::npos) << name;
     }
@@ -837,7 +853,7 @@ TEST(FeedbackUpload, OversizedTrajectoryKeepsNewestCompleteLines) {
     auto result = acecode::feedback::build_feedback_package(req);
     ASSERT_TRUE(result.ok) << result.error;
     const std::string packed =
-        read_zip_entry(result.package_path, "session/sid-big.trajectory.jsonl");
+        read_zip_entry(result.package_path, "session/sid_big.trajectory.jsonl");
     EXPECT_EQ(packed, line3);
     ASSERT_TRUE(result.trajectory.has_value());
     EXPECT_TRUE(result.trajectory->truncated);
@@ -870,7 +886,7 @@ TEST(FeedbackUpload, SingleOversizedTrajectoryRecordKeepsPartialTail) {
 
     auto result = acecode::feedback::build_feedback_package(req);
     ASSERT_TRUE(result.ok) << result.error;
-    EXPECT_EQ(read_zip_entry(result.package_path, "session/sid-one.trajectory.jsonl"),
+    EXPECT_EQ(read_zip_entry(result.package_path, "session/sid_one.trajectory.jsonl"),
               record.substr(record.size() - 20));
     ASSERT_TRUE(result.trajectory.has_value());
     EXPECT_TRUE(result.trajectory->truncated);
diff --git a/tests/headless/headless_options_test.cpp b/tests/headless/headless_options_test.cpp
index fad02a4cc..7969fd4da 100644
--- a/tests/headless/headless_options_test.cpp
+++ b/tests/headless/headless_options_test.cpp
@@ -444,6 +444,13 @@ TEST(HeadlessOptions, RejectsSessionIdShapedLikeLegacyPidFile) {
     auto ok = parse_headless_cli_options({"-p", "--session-id", "foo-123", "go"});
     EXPECT_TRUE(ok.error.empty()) << ok.error;
     EXPECT_EQ(ok.session_id, "foo-123");
+
+    const auto new_id = parse_headless_cli_options(
+        {"-p", "--session-id", "20261016_100000_abcd", "go"});
+    EXPECT_TRUE(new_id.error.empty()) << new_id.error;
+    const auto new_pid = parse_headless_cli_options(
+        {"-p", "--session-id", "20261016_100000_abcd_9999", "go"});
+    EXPECT_FALSE(new_pid.error.empty());
 }
 
 // 场景:is_valid_session_id_token 的边界 —— 恰好 64 字符(合法上限)与
diff --git a/tests/ipc/agent_browser_runtime_test.cpp b/tests/ipc/agent_browser_runtime_test.cpp
index f2a0b40c5..5b937a3fd 100644
--- a/tests/ipc/agent_browser_runtime_test.cpp
+++ b/tests/ipc/agent_browser_runtime_test.cpp
@@ -62,15 +62,23 @@ AgentBrowserRuntimeManifest valid_manifest(const fs::path& root) {
 TEST(AgentBrowserRuntime, PathsKeepPersistentProfileSeparateFromRuntimeFile) {
     TempDir dir;
     EXPECT_EQ(agent_browser_user_data_path(acecode::path_to_utf8(dir.path())),
-              dir.path() / "agent-browser" / "webview2");
+              dir.path() / "agent_browser" / "webview2");
     EXPECT_EQ(agent_browser_macos_profile_identifier_path(
                   acecode::path_to_utf8(dir.path())),
-              dir.path() / "agent-browser" / "macos-profile-id");
+              dir.path() / "agent_browser" / "macos_profile_id");
     EXPECT_EQ(agent_browser_proxy_socket_path(
                   acecode::path_to_utf8(dir.path())),
-              dir.path() / "run" / "agent-browser.sock");
+              dir.path() / "run" / "agent_browser.sock");
     EXPECT_EQ(agent_browser_runtime_manifest_path(acecode::path_to_utf8(dir.path())),
-              dir.path() / "run" / "agent-browser.json");
+              dir.path() / "run" / "agent_browser.json");
+}
+
+TEST(AgentBrowserRuntime, KeepsAnExistingLegacyBrowserProfile) {
+    TempDir dir;
+    fs::create_directories(dir.path() / "agent-browser" / "webview2");
+    EXPECT_EQ(agent_browser_user_data_path(acecode::path_to_utf8(dir.path())),
+              dir.path() / "agent-browser" / "webview2");
+    EXPECT_FALSE(fs::exists(dir.path() / "agent_browser"));
 }
 
 TEST(AgentBrowserRuntime, NormalizesWebAndAbsoluteLocalAddresses) {
diff --git a/tests/memory/memory_forget_test.cpp b/tests/memory/memory_forget_test.cpp
index 26c97f409..737cc15bf 100644
--- a/tests/memory/memory_forget_test.cpp
+++ b/tests/memory/memory_forget_test.cpp
@@ -66,7 +66,7 @@ TEST(MemoryInboxTest, ObservationFilesAreIdempotentPerRange) {
     const auto inbox = acecode::list_memory_inbox(scope);
     ASSERT_EQ(inbox.size(), 1u);
     EXPECT_EQ(inbox[0].observations.size(), 2u);
-    EXPECT_EQ(inbox[0].observations[1].id, "s1-0-8#1");
+    EXPECT_EQ(inbox[0].observations[1].id, "s1_0_8#1");
     EXPECT_EQ(acecode::count_memory_inbox_observations(scope), 2u);
 }
 
@@ -80,17 +80,37 @@ TEST(MemoryInboxTest, ArchiveMovesFilesAndCleansUpOldDays) {
     ASSERT_TRUE(acecode::write_memory_observation_file(scope, file));
     ASSERT_TRUE(acecode::archive_memory_observation_files(scope, {file.path}, "2026-08-01"));
     EXPECT_FALSE(fs::exists(file.path));
-    EXPECT_TRUE(fs::exists(acecode::memory_archive_dir(scope) / "2026-08-01" / file.path.filename()));
+    EXPECT_TRUE(fs::exists(acecode::memory_archive_dir(scope) / "2026_08_01" / file.path.filename()));
     ASSERT_TRUE(acecode::archive_memory_observation_files(scope, {file.path}, "2026-08-01"));
     fs::create_directories(acecode::memory_archive_dir(scope) / "2026-09-25");
 
     const auto now = acecode::parse_memory_iso8601("2026-10-01T00:00:00Z");
     ASSERT_TRUE(now.has_value());
     EXPECT_EQ(acecode::cleanup_memory_archive(scope, *now, 30), 1);
-    EXPECT_FALSE(fs::exists(acecode::memory_archive_dir(scope) / "2026-08-01"));
+    EXPECT_FALSE(fs::exists(acecode::memory_archive_dir(scope) / "2026_08_01"));
     EXPECT_TRUE(fs::exists(acecode::memory_archive_dir(scope) / "2026-09-25"));
 }
 
+TEST(MemoryInboxTest, LegacyObservationReplayKeepsOneFileAndStableLegacyIds) {
+    MemoryTestHome home("memory_inbox_legacy_naming");
+    const fs::path scope = acecode::get_memory_dir();
+    auto file = observation_file("legacy", 0, 4, 1);
+    ASSERT_TRUE(acecode::write_memory_observation_file(scope, file));
+    const auto new_path = file.path;
+    const auto old_path = file.path.parent_path() / "legacy-0-4.json";
+    fs::rename(new_path, old_path);
+    auto replay = observation_file("legacy", 0, 4, 2);
+    ASSERT_TRUE(acecode::write_memory_observation_file(scope, replay));
+    EXPECT_EQ(replay.path, old_path);
+    EXPECT_FALSE(fs::exists(new_path));
+    const auto files = acecode::list_memory_inbox(scope);
+    ASSERT_EQ(files.size(), 1u);
+    ASSERT_EQ(files.front().observations.size(), 2u);
+    EXPECT_EQ(files.front().observations.front().id, "legacy-0-4#0");
+    acecode::remove_memory_observation_file(scope, "legacy", 0, 4);
+    EXPECT_TRUE(acecode::list_memory_inbox(scope).empty());
+}
+
 // 场景:条目 only_s 只来源于会话 S;shared 来源于 S 与 T;手写条目 manual_note
 // 的来源也记着 S;S 在收件箱与归档里都有观察。永久删除 S。
 // 期望:only_s 删除并记墓碑;shared 只移除 S;手写条目保留;S 的观察全部删除,
diff --git a/tests/provider/model_sampling_request_test.cpp b/tests/provider/model_sampling_request_test.cpp
index ed668aa7a..2c6af3a98 100644
--- a/tests/provider/model_sampling_request_test.cpp
+++ b/tests/provider/model_sampling_request_test.cpp
@@ -54,6 +54,33 @@ ModelSamplingOptions glm_recommended() {
 
 } // namespace
 
+TEST(ModelSamplingOverrides, MergesFieldsWithoutLosingZeroOrMutatingDefaults) {
+    std::string error;
+    const auto defaults = glm_recommended();
+    const auto overrides = acecode::parse_model_sampling_overrides(
+        nlohmann::json{{"temperature", 0}, {"min_p", 0}, {"top_p", nullptr}}, error);
+    ASSERT_TRUE(overrides) << error;
+    const auto merged = acecode::merge_model_sampling_options(defaults, *overrides);
+    EXPECT_EQ(merged.temperature, 0);
+    EXPECT_EQ(merged.min_p, 0);
+    EXPECT_EQ(merged.top_p, 0.95);
+    EXPECT_EQ(merged.top_k, 20);
+    EXPECT_EQ(defaults.temperature, 1);
+    EXPECT_TRUE(acecode::parse_model_sampling_overrides(nullptr, error)->empty());
+}
+
+TEST(ModelSamplingOverrides, RejectsInvalidAndUnknownFields) {
+    for (const auto& value : {
+        R"({"temperature":"0.5"})", R"({"temperature":2.1})",
+        R"({"top_p":0})", R"({"top_k":1.5})", R"({"top_k":2147483648})",
+        R"({"top_k":18446744073709551615})", R"({"min_p":-0.1})",
+        R"({"temperatur":0.5})", R"([])"}) {
+        std::string error;
+        EXPECT_FALSE(acecode::parse_model_sampling_overrides(nlohmann::json::parse(value), error)) << value;
+        EXPECT_FALSE(error.empty()) << value;
+    }
+}
+
 // 触发场景:模型没有配置任何采样参数(所有现有用户的默认状态)。
 // 期望:Chat Completions 请求体里一个采样字段都没有,与加这个功能之前一致。
 TEST(ModelSamplingRequest, OpenAiOmitsSamplingFieldsWhenUnset) {
diff --git a/tests/sandbox/sandbox_backend_win_test.cpp b/tests/sandbox/sandbox_backend_win_test.cpp
index 107faa259..87ea4910f 100644
--- a/tests/sandbox/sandbox_backend_win_test.cpp
+++ b/tests/sandbox/sandbox_backend_win_test.cpp
@@ -48,7 +48,8 @@ struct ScopedSandboxTemp {
     ~ScopedSandboxTemp() {
         std::error_code ec;
         if (owned && !path.empty() &&
-            path.parent_path() == path_from_utf8(system_temp_dir()) / "acecode-sandbox" &&
+            (path.parent_path() == path_from_utf8(system_temp_dir()) / "acecode_sandbox" ||
+             path.parent_path() == path_from_utf8(system_temp_dir()) / "acecode-sandbox") &&
             fs::weakly_canonical(path, ec) == path && !ec) {
             fs::remove_all(path, ec);
         }
@@ -125,7 +126,8 @@ TEST(SandboxBackendWin, DefaultTempWritesWithoutChangingSharedTempAcl) {
     ScopedSandboxTemp temporary(request.policy.temporary_directory);
     const auto shared = path_from_utf8(system_temp_dir());
     ASSERT_NE(temporary.path, shared);
-    ASSERT_EQ(temporary.path.parent_path(), shared / "acecode-sandbox");
+    ASSERT_TRUE(temporary.path.parent_path() == shared / "acecode_sandbox" ||
+                temporary.path.parent_path() == shared / "acecode-sandbox");
     ASSERT_TRUE(temporary.owned);
     const auto shared_before = dacl_snapshot(shared);
     const auto unrelated_before = dacl_snapshot(unrelated);
diff --git a/tests/scripts/dev_desktop_test.py b/tests/scripts/dev_desktop_test.py
index 4127698d1..c9c97f0ae 100644
--- a/tests/scripts/dev_desktop_test.py
+++ b/tests/scripts/dev_desktop_test.py
@@ -131,7 +131,7 @@ def test_desktop_instance_identity_matches_web_runtime_naming(self) -> None:
             with mock.patch.object(dev_desktop, "desktop_instance_identity",
                                    wraps=dev_desktop.desktop_instance_identity):
                 actual = self._identity_with_commit(repo, identity)
-            self.assertEqual(actual, "my.worktree-0123456789ab")
+            self.assertEqual(actual, "my.worktree_0123456789ab")
             self.assertEqual(re.sub(r"[^A-Za-z0-9_.-]", "-", actual), actual)
 
     def test_desktop_instance_identity_sanitizes_unsafe_worktree_names(self) -> None:
@@ -139,7 +139,7 @@ def test_desktop_instance_identity_sanitizes_unsafe_worktree_names(self) -> None
             repo = Path(root_text) / "fix dev launcher+identity"
             repo.mkdir()
             actual = self._identity_with_commit(repo, "a" * 40)
-            self.assertEqual(actual, "fix-dev-launcher-identity-aaaaaaaaaaaa")
+        self.assertEqual(actual, "fix_dev_launcher_identity_aaaaaaaaaaaa")
 
     def _identity_with_commit(self, repo: Path, commit: str) -> str:
         """`desktop_instance_identity` 依赖 git，测试里替换掉 commit 查询。"""
@@ -154,7 +154,7 @@ def test_falls_back_to_worktree_name_when_commit_is_unknown(self) -> None:
             repo.mkdir()
             self.assertEqual(
                 self._identity_with_commit(repo, None),
-                "detached-detached",
+                "detached_detached",
             )
 
     def test_desktop_environment_injects_process_level_overrides(self) -> None:
@@ -167,7 +167,7 @@ def test_desktop_environment_injects_process_level_overrides(self) -> None:
             with mock.patch.dict(os.environ, {"ACECODE_TEST_SENTINEL": "kept"}, clear=False):
                 environment, identity = dev_desktop.desktop_environment(repo, web)
 
-            self.assertEqual(identity, "acecode-acecode")
+            self.assertEqual(identity, "acecode_acecode")
             self.assertEqual(environment["ACECODE_DESKTOP_INSTANCE_ID"], identity)
             self.assertEqual(environment["ACECODE_DESKTOP_ALLOW_MULTIPLE_INSTANCES"], "1")
             self.assertEqual(environment["ACECODE_DEV_WEB_DIR"], str(web.resolve()))
diff --git a/tests/scripts/dev_environment_review_test.py b/tests/scripts/dev_environment_review_test.py
index 84895b381..17c0d23d7 100644
--- a/tests/scripts/dev_environment_review_test.py
+++ b/tests/scripts/dev_environment_review_test.py
@@ -201,17 +201,26 @@ def test_runtime_failure_prevents_configuration_build_and_launch(self):
         launch.assert_not_called()
 
     def test_runtime_from_previous_commit_also_blocks_rebuild(self):
-        with tempfile.TemporaryDirectory() as directory:
-            root = Path(directory).resolve()
-            candidate = self.make_candidate(root)
-            previous = root / ".acecode/dev-run" / (root.name + "-oldcommit")
-            previous.mkdir(parents=True)
-            (previous / "daemon.pid").write_text("123", encoding="ascii")
-            with patch.object(launcher, "current_commit", return_value="newcommit"), \
-                 patch.object(launcher.subprocess, "run", return_value=subprocess.CompletedProcess([], 0)) as run, \
-                 contextlib.redirect_stderr(io.StringIO()):
-                self.assertFalse(launcher.web_runtime_is_available(root, candidate, []))
-            self.assertEqual(run.call_args.args[0][-1], f"--run-dir={previous}")
+        for base in ("dev-run", "dev_run"):
+            for identity in ("work-tree-oldcommit", "work_tree_oldcommit"):
+                with self.subTest(base=base, identity=identity), tempfile.TemporaryDirectory() as directory:
+                    root = Path(directory).resolve() / "work-tree"
+                    root.mkdir()
+                    candidate = self.make_candidate(root)
+                    # Both generations can coexist after an upgrade; an empty legacy
+                    # root must not hide a worker using the underscore naming scheme.
+                    for name in ("dev-run", "dev_run"):
+                        (root / ".acecode" / name).mkdir(parents=True)
+                    previous = root / ".acecode" / base / identity
+                    previous.mkdir()
+                    (previous / "daemon.pid").write_text("123", encoding="ascii")
+                    with patch.object(launcher, "current_commit", return_value="newcommit"), \
+                         patch.object(launcher.subprocess, "run", return_value=subprocess.CompletedProcess([], 0)) as run, \
+                         contextlib.redirect_stderr(io.StringIO()):
+                        self.assertFalse(launcher.web_runtime_is_available(root, candidate, []))
+                    self.assertEqual(run.call_args.args[0][-1], f"--run-dir={previous}")
+                    self.assertEqual(run.call_args.args[0][1:3], ["daemon", "status"])
+                    self.assertEqual((previous / "daemon.pid").read_text(encoding="ascii"), "123")
 
     def test_explicit_runtime_does_not_inspect_other_launcher_daemons(self):
         with tempfile.TemporaryDirectory() as directory:
diff --git a/tests/scripts/dev_environment_test.py b/tests/scripts/dev_environment_test.py
index f4f51ee2f..0f9b78f5f 100644
--- a/tests/scripts/dev_environment_test.py
+++ b/tests/scripts/dev_environment_test.py
@@ -139,12 +139,26 @@ def test_runtime_directory_is_scoped_to_worktree(self):
         root = Path("C:/worktrees/my project")
         with patch.object(dev_environment, "current_commit", return_value="abcdef1234567890"):
             runtime = dev_environment.worktree_runtime_dir(root)
-        self.assertEqual(runtime, root / ".acecode/dev-run/my-project-abcdef123456")
+        self.assertEqual(runtime, root / ".acecode/dev_run/my_project_abcdef123456")
 
     def test_noninteractive_target_selection_fails(self):
         with patch.object(dev_environment.sys, "stdin", None):
             self.assertIsNone(dev_environment.choose_target(None))
 
+    def test_existing_legacy_runtime_and_logs_remain_discoverable(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary) / "old-project"
+            legacy = root / ".acecode/dev-run/old-project-abcdef123456"
+            legacy.mkdir(parents=True)
+            (legacy / "daemon-worker.log").write_text("old worker", encoding="utf-8")
+            (legacy / "daemon-startup.log").write_text("old startup", encoding="utf-8")
+            with patch.object(dev_environment, "current_commit", return_value="abcdef1234567890"):
+                self.assertEqual(dev_environment.worktree_runtime_dir(root), legacy)
+            self.assertFalse((root / ".acecode/dev_run").exists())
+            detail = dev_environment.worker_failure_detail(legacy, "failed")
+            self.assertIn(str(legacy / "daemon-worker.log"), detail)
+            self.assertIn(str(legacy / "daemon-startup.log"), detail)
+
     def test_sccache_discovery_prefers_usable_path_and_has_install_hint(self):
         completed = subprocess.CompletedProcess([], 0, stdout="sccache 1.0")
         with patch.object(dev_environment.shutil, "which", return_value="C:/tools/sccache.exe"), \
@@ -521,12 +535,12 @@ def test_worker_log_header_and_rotation(self):
             run_dir = Path(directory)
             command = ["C:/build/acecode.exe", "daemon", "--foreground"]
             dev_environment.open_worker_log(run_dir, command).close()
-            log = run_dir / "daemon-worker.log"
+            log = run_dir / "daemon_worker.log"
             self.assertIn("spawn: C:/build/acecode.exe daemon --foreground", log.read_text(encoding="utf-8"))
             log.write_text("x" * (dev_environment.WORKER_LOG_MAX_BYTES + 1), encoding="utf-8")
             dev_environment.open_worker_log(run_dir, command).close()
             self.assertLess(log.stat().st_size, dev_environment.WORKER_LOG_MAX_BYTES)
-            self.assertTrue((run_dir / "daemon-worker.log.1").exists())
+            self.assertTrue((run_dir / "daemon_worker.log.1").exists())
 
     def test_spawn_redirects_worker_output_into_the_runtime_log(self):
         with tempfile.TemporaryDirectory() as directory:
@@ -539,8 +553,8 @@ def test_spawn_redirects_worker_output_into_the_runtime_log(self):
             options = popen.call_args.kwargs
             self.assertEqual(popen.call_args.args[0], command)
             self.assertEqual(options["stderr"], subprocess.STDOUT)
-            self.assertEqual(Path(options["stdout"].name), run_dir / "daemon-worker.log")
-            self.assertTrue((run_dir / "daemon-worker.log").is_file())
+            self.assertEqual(Path(options["stdout"].name), run_dir / "daemon_worker.log")
+            self.assertTrue((run_dir / "daemon_worker.log").is_file())
 
     def test_worker_exit_fails_before_the_health_timeout(self):
         root = Path("C:/work")
@@ -560,8 +574,8 @@ def test_start_failure_points_at_both_logs(self):
              patch.object(dev_environment, "daemon_port", return_value=28080):
             with contextlib.redirect_stderr(io.StringIO()) as output:
                 self.assertIsNone(dev_environment.start_quick_web_daemon(root, candidate, run_dir, 28080))
-        self.assertIn("daemon-worker.log", output.getvalue())
-        self.assertIn("daemon-startup.log", output.getvalue())
+        self.assertIn("daemon_worker.log", output.getvalue())
+        self.assertIn("daemon_startup.log", output.getvalue())
 
     def test_pid_is_alive_reads_the_process_table(self):
         self.assertTrue(dev_environment.pid_is_alive(os.getpid()))
diff --git a/tests/scripts/runtime_log_append_test.py b/tests/scripts/runtime_log_append_test.py
index 4135bb84b..5057d61b7 100644
--- a/tests/scripts/runtime_log_append_test.py
+++ b/tests/scripts/runtime_log_append_test.py
@@ -35,8 +35,8 @@ def test_missing_unicode_directory_and_separate_trace(self):
         self.invoke("logger", target, 0, 1)
         self.invoke("trace", target, 0, 1)
         self.assertTrue(target.is_dir())
-        primary = list(target.glob("tui-????-??-??.log"))
-        trace = list(target.glob("tui-input-trace-????-??-??.log"))
+        primary = list(target.glob("tui_????_??_??.log"))
+        trace = list(target.glob("tui_input_trace_????_??_??.log"))
         self.assertEqual(len(primary), 1)
         self.assertEqual(len(trace), 1)
         self.assert_records(primary[0].read_text(), 1, 1)
@@ -67,7 +67,7 @@ def test_processes_preserve_every_complete_record(self):
     def test_trace_uses_local_date_across_midnight(self):
         result = self.invoke("trace-path", self.root)
         self.assertEqual(result.stdout.splitlines(), [
-            "tui-input-trace-2026-09-20.log", "tui-input-trace-2026-09-21.log"])
+            "tui_input_trace_2026_09_20.log", "tui_input_trace_2026_09_21.log"])
 
     def test_trace_refuses_unconfigured_relative_and_unopenable_paths(self):
         blocked = self.root / "regular-file"
diff --git a/tests/session/session_data_diagnostics_test.cpp b/tests/session/session_data_diagnostics_test.cpp
index ab08c0f3b..c0b577105 100644
--- a/tests/session/session_data_diagnostics_test.cpp
+++ b/tests/session/session_data_diagnostics_test.cpp
@@ -21,7 +21,7 @@ TEST(SessionDataDiagnostics, SamplesOnlyFiveLargestInRegisteredWorkspaceWithoutC
     const std::string hash = "0123456789abcdef";
     const std::string secret = "private-message-body-and-path";
     for (int i = 0; i < 7; ++i) {
-        fixture.write(hash, "20260101-000000-000" + std::to_string(i),
+        fixture.write(hash, std::string(i % 2 ? "20260101_000000_000" : "20260101-000000-000") + std::to_string(i),
                       "{\"role\":\"user\",\"content\":\"" + secret + std::string(i, 'x') + "\"}\n");
     }
     fixture.write("fedcba9876543210", "20260101-000000-0000", "unregistered");
diff --git a/tests/session/session_markdown_export_test.cpp b/tests/session/session_markdown_export_test.cpp
index 9f23afb8e..c9b3e33da 100644
--- a/tests/session/session_markdown_export_test.cpp
+++ b/tests/session/session_markdown_export_test.cpp
@@ -48,11 +48,11 @@ TEST(SessionMarkdownExportTest, BuildsMetadataRolesToolCallsAndStructuredContent
 
 TEST(SessionMarkdownExportTest, BuildsSafeSuggestedMarkdownFilename) {
     EXPECT_EQ(session_export::sanitize_filename_stem("CON: invalid? ", "fallback"), "CON_ invalid_");
-    EXPECT_EQ(session_export::sanitize_filename_stem("...", "session-1"), "session-1");
+    EXPECT_EQ(session_export::sanitize_filename_stem("...", "session-1"), "session_1");
     EXPECT_EQ(session_export::suggested_markdown_filename("会话标题", "sid"),
               "会话标题.md");
     EXPECT_EQ(session_export::suggested_markdown_filename("...", "session-1"),
-              "session-1.md");
+              "session_1.md");
 }
 
 TEST(SessionMarkdownExportTest, KeepsVisibleSystemAndErrorRoles) {
diff --git a/tests/session/session_storage_pid_suffix_test.cpp b/tests/session/session_storage_pid_suffix_test.cpp
index 6146c31ee..e66ef9edf 100644
--- a/tests/session/session_storage_pid_suffix_test.cpp
+++ b/tests/session/session_storage_pid_suffix_test.cpp
@@ -38,6 +38,15 @@ void write_meta(const fs::path& path, const std::string& id,
 } // namespace
 
 // 场景:默认 session_path/meta_path 必须写 canonical 文件名,不再带本进程 PID。
+TEST(SessionStoragePidSuffix, UnderscorePidDataIsExcludedAlongsideLegacyFiles) {
+    const auto dir = make_unique_tmp_dir("underscore_pid");
+    const std::string id = "20261016_100000_abcd";
+    write_meta((dir / (id + "_123.meta.json")), id, "2026-10-16T10:00:00Z");
+    std::ofstream(dir / (id + "_123.jsonl")) << "{}\n";
+    EXPECT_TRUE(SessionStorage::list_sessions(dir.u8string()).empty());
+    EXPECT_TRUE(SessionStorage::has_incompatible_pid_session_files(dir.u8string(), id));
+}
+
 TEST(SessionStoragePidSuffix, DefaultPathsAreCanonical) {
     auto dir = make_unique_tmp_dir("default_canonical");
     const std::string id = "20260426-100000-abcd";
diff --git a/tests/session/session_storage_test.cpp b/tests/session/session_storage_test.cpp
index 92107f96b..53a138b80 100644
--- a/tests/session/session_storage_test.cpp
+++ b/tests/session/session_storage_test.cpp
@@ -14,6 +14,7 @@
 #include <filesystem>
 #include <fstream>
 #include <iterator>
+#include <regex>
 #include <string>
 #include <vector>
 
@@ -37,6 +38,38 @@ fs::path make_unique_tmp_dir(const std::string& hint) {
 
 // 场景:写一个字段齐全(含 title)的 SessionMeta 到磁盘,再读回,
 // 所有字段必须逐一一致——这是 write_meta / read_meta 的核心契约。
+TEST(SessionStorage, GeneratedIdsUseUnderscores) {
+    EXPECT_TRUE(std::regex_match(SessionStorage::generate_session_id(),
+        std::regex(R"(^[0-9]{8}_[0-9]{6}_[0-9a-f]{4}$)")));
+}
+
+TEST(SessionStorage, MixedSessionNamesKeepTheirIdentityAndHistory) {
+    const auto dir = make_unique_tmp_dir("mixed_naming");
+    const std::vector<std::string> ids = {"20261016-100000-abcd", "20261016_100001_abcd"};
+    for (const auto& id : ids) {
+        SessionMeta meta;
+        meta.id = id;
+        meta.updated_at = "2026-10-16T10:00:00Z";
+        meta.message_count = 1;
+        meta.turn_count = 1;
+        meta.summary = id;
+        SessionStorage::write_meta(SessionStorage::meta_path(dir.u8string(), id), meta);
+        acecode::ChatMessage message;
+        message.role = "user";
+        message.content = id;
+        ASSERT_TRUE(SessionStorage::append_message(SessionStorage::session_path(dir.u8string(), id), message));
+    }
+    const auto sessions = SessionStorage::list_sessions(dir.u8string());
+    ASSERT_EQ(sessions.size(), 2u);
+    for (const auto& id : ids) {
+        const auto messages = SessionStorage::load_messages(SessionStorage::session_path(dir.u8string(), id));
+        ASSERT_EQ(messages.size(), 1u);
+        EXPECT_EQ(messages.front().content, id);
+        EXPECT_EQ(SessionStorage::find_session_files(dir.u8string(), id).size(), 1u);
+    }
+    EXPECT_FALSE(fs::exists(dir / "20261016_100000_abcd.jsonl"));
+}
+
 TEST(SessionStorage, MetaRoundtrip) {
     auto dir = make_unique_tmp_dir("roundtrip");
     auto meta_path = (dir / "20260419-120000-abcd.meta.json").string();
diff --git a/tests/session_host/session_registry_test.cpp b/tests/session_host/session_registry_test.cpp
index 53db2558e..076bbc5df 100644
--- a/tests/session_host/session_registry_test.cpp
+++ b/tests/session_host/session_registry_test.cpp
@@ -1564,7 +1564,7 @@ TEST(SessionRegistry, CreateNoWorkspaceKeepsWorkspaceHashEmpty) {
     EXPECT_TRUE(entry->workspace_hash.empty());
     EXPECT_TRUE(entry->no_workspace);
     EXPECT_TRUE(std::filesystem::is_directory(expected_cwd));
-    EXPECT_EQ(std::filesystem::path(expected_cwd).parent_path().filename().string(), "no-workspace");
+    EXPECT_EQ(std::filesystem::path(expected_cwd).parent_path().filename().string(), "no_workspace");
     ASSERT_NE(entry->loop, nullptr);
     EXPECT_EQ(entry->loop->cwd(), expected_cwd);
 
diff --git a/tests/session_host/spawn_subagent_tool_test.cpp b/tests/session_host/spawn_subagent_tool_test.cpp
index 9a6b7625e..49c250728 100644
--- a/tests/session_host/spawn_subagent_tool_test.cpp
+++ b/tests/session_host/spawn_subagent_tool_test.cpp
@@ -18,6 +18,9 @@
 #include "session_host/session_registry.hpp"
 #include "session/session_storage.hpp"
 #include "session_host/tools/spawn_subagent_tool.hpp"
+#include "session_host/tools/mesh_agent_tools.hpp"
+#include "session_host/mesh/mesh_agent_service.hpp"
+#include "provider/openai_provider.hpp"
 #include "tool/tool_executor.hpp"
 #include "utils/utf8_path.hpp"
 #include "worktree/worktree_manager.hpp"
@@ -197,6 +200,165 @@ struct SubagentFixture {
 
 // 场景: deps 未回填(TUI / registry 尚未构造)→ 报"仅 daemon 可用"而不是
 // 解引用空指针崩溃。
+TEST(AgentSampling, SpawnOverridesPersistAndSurviveReloadAndResume) {
+    SubagentFixture fx(true);
+    fx.configure_models();
+    fx.config.saved_models[0].sampling.temperature = 1;
+    fx.config.saved_models[0].sampling.top_p = 0.9;
+    RecordingSessionClient recording;
+    fx.deps->client = &recording;
+    acecode::SessionOptions opts;
+    opts.cwd = fx.cwd.string();
+    opts.swarm_mode = "star";
+    const auto parent_id = fx.registry.create(opts);
+    const auto result = fx.tools.execute("spawn_subagent",
+        R"({"prompt":"sample","wait":false,"sampling":{"temperature":0,"min_p":0}})", fx.ctx_for(parent_id));
+    ASSERT_TRUE(result.success) << result.output;
+    const auto child_id = result.metadata["subagent_session_id"].get<std::string>();
+    auto read_sampling = [&](const std::string& id) {
+        auto provider = std::dynamic_pointer_cast<acecode::OpenAiCompatProvider>(
+            fx.registry.acquire(id)->model_binding->provider_snapshot());
+        EXPECT_NE(provider, nullptr);
+        return provider ? provider->request_options().sampling : acecode::ModelSamplingOptions{};
+    };
+    EXPECT_EQ(read_sampling(child_id).temperature, 0);
+    EXPECT_EQ(read_sampling(child_id).min_p, 0);
+    EXPECT_EQ(read_sampling(child_id).top_p, 0.9);
+    EXPECT_EQ(read_sampling(parent_id).temperature, 1);
+    EXPECT_EQ(fx.config.saved_models[0].sampling.temperature, 1);
+    const auto meta = acecode::SessionStorage::read_meta(acecode::SessionStorage::meta_path(
+        acecode::SessionStorage::get_project_dir(opts.cwd), child_id));
+    EXPECT_EQ(meta.sampling.temperature, 0);
+    EXPECT_FALSE(meta.sampling.top_p);
+    fx.config.saved_models[0].sampling.top_p = 0.7;
+    const auto reloaded = fx.registry.reload_model_profile(child_id, true);
+    ASSERT_TRUE(reloaded && reloaded->ok);
+    EXPECT_EQ(read_sampling(child_id).top_p, 0.7);
+    EXPECT_EQ(read_sampling(child_id).temperature, 0);
+    fx.registry.destroy(child_id);
+    ASSERT_TRUE(fx.registry.resume(child_id, opts));
+    EXPECT_EQ(read_sampling(child_id).temperature, 0);
+    EXPECT_EQ(read_sampling(child_id).min_p, 0);
+    EXPECT_EQ(read_sampling(child_id).top_p, 0.7);
+    EXPECT_EQ(fx.registry.acquire(child_id)->sm->current_sampling_overrides().temperature, 0);
+    fx.registry.shutdown_all();
+}
+
+TEST(AgentSampling, ExpertsAndTaskOverridesMergeAndInvalidSwitchesKeepProvider) {
+    SubagentFixture fx(true);
+    fx.configure_models();
+    fx.config.saved_models[0].sampling.top_p = 0.9;
+    acecode::ExpertDraft expert;
+    expert.id = "sampling-reviewer";
+    expert.display_name = "Reviewer";
+    expert.lead = {"lead", "Reviewer", "Review", "Review carefully"};
+    expert.sampling.temperature = 0.4;
+    expert.sampling.top_k = 20;
+    std::string error;
+    ASSERT_TRUE(fx.experts.create_global(expert, &error)) << error;
+    acecode::SessionOptions opts;
+    opts.cwd = fx.cwd.string();
+    opts.expert_id = expert.id;
+    opts.sampling = acecode::ModelSamplingOptions{};
+    opts.sampling->temperature = 0.8;
+    const auto id = fx.registry.create(opts);
+    const auto child = fx.registry.acquire(id);
+    auto get_provider = [&] {
+        return std::dynamic_pointer_cast<acecode::OpenAiCompatProvider>(child->model_binding->provider_snapshot());
+    };
+    ASSERT_NE(get_provider(), nullptr);
+    EXPECT_EQ(get_provider()->request_options().sampling.temperature, 0.8);
+    EXPECT_EQ(get_provider()->request_options().sampling.top_k, 20);
+    EXPECT_EQ(get_provider()->request_options().sampling.top_p, 0.9);
+
+    expert.id = "sampling-writer";
+    expert.sampling.top_k = 40;
+    ASSERT_TRUE(fx.experts.create_global(expert, &error)) << error;
+    const auto switched = fx.registry.switch_expert(id, expert.id);
+    ASSERT_EQ(switched.status, acecode::ExpertSwitchStatus::Accepted);
+    ASSERT_TRUE(switched.applied);
+    EXPECT_EQ(get_provider()->request_options().sampling.top_k, 40);
+    EXPECT_EQ(get_provider()->request_options().sampling.temperature, 0.8);
+    const auto previous = get_provider();
+    fx.config.saved_models[1].api_protocol = "responses";
+    EXPECT_FALSE(fx.registry.switch_model(id, fx.config.saved_models[1], nullptr, &error));
+    EXPECT_NE(error.find("top_k"), std::string::npos);
+    EXPECT_EQ(get_provider(), previous);
+    auto plain_opts = opts;
+    plain_opts.expert_id.clear();
+    plain_opts.sampling.reset();
+    plain_opts.model_name = "parent-current";
+    const auto plain_id = fx.registry.create(plain_opts);
+    const auto invalid = fx.registry.switch_expert(plain_id, expert.id);
+    EXPECT_EQ(invalid.status, acecode::ExpertSwitchStatus::Failed);
+    EXPECT_NE(invalid.error.find("top_k"), std::string::npos);
+    EXPECT_TRUE(fx.registry.acquire(plain_id)->sm->current_expert_id().empty());
+    fx.registry.shutdown_all();
+}
+
+TEST(AgentSampling, InvalidStoredSamplingCannotResumeWithoutItsExpertBinding) {
+    SubagentFixture fx;
+    const auto path = fx.cwd / "invalid.meta.json";
+    { std::ofstream out(path); out << R"({"id":"invalid","sampling":{"top_p":0},"expert_id":"restricted"})"; }
+    EXPECT_TRUE(acecode::SessionStorage::read_meta(path.string()).id.empty());
+}
+
+TEST(AgentSampling, InvalidSpawnSamplingNeverStartsTask) {
+    SubagentFixture fx(true);
+    fx.configure_models();
+    fx.config.saved_models[0].api_protocol = "responses";
+    RecordingSessionClient recording;
+    fx.deps->client = &recording;
+    for (const auto& sampling : {R"({"top_k":20})", R"({"temperature":"1"})", R"({"top_p":0})", R"({"unknown":1})"}) {
+        const auto args = nlohmann::json{{"prompt", "invalid"}, {"wait", false},
+            {"sampling", nlohmann::json::parse(sampling)}};
+        const auto result = fx.tools.execute("spawn_subagent", args.dump(), fx.ctx_for(""));
+        EXPECT_FALSE(result.success) << sampling;
+        EXPECT_NE(result.output.find("sampling"), std::string::npos) << result.output;
+        EXPECT_EQ(fx.registry.size(), 0u);
+        EXPECT_TRUE(recording.sent_session_id.empty());
+    }
+}
+
+TEST(AgentSampling, MeshToolExposesSamplingAndPassesItToChildProvider) {
+    SubagentFixture fx(true);
+    fx.configure_models();
+    fx.config.swarm.mesh.expose_model_overrides = false;
+    acecode::mesh::MeshAgentService::Deps deps;
+    deps.registry = &fx.registry;
+    deps.config = &fx.config;
+    deps.experts = &fx.experts;
+    auto service = std::make_shared<acecode::mesh::MeshAgentService>(deps);
+    service->attach();
+    acecode::register_mesh_agent_tools(fx.tools, service, fx.config);
+    acecode::ModelSamplingOptions observed;
+    service->set_on_agent_loaded([&](const std::string& child_id, const std::string&) {
+        const auto child = fx.registry.acquire(child_id);
+        auto provider = std::dynamic_pointer_cast<acecode::OpenAiCompatProvider>(child->model_binding->provider_snapshot());
+        ASSERT_NE(provider, nullptr);
+        observed = provider->request_options().sampling;
+        // Exercise real construction, then keep the submitted turn offline.
+        child->model_binding->install_runtime_snapshot(std::make_shared<EchoStreamProvider>(),
+            child->model_binding->state_snapshot(), child->model_binding->applied_revision());
+    });
+    acecode::SessionOptions opts;
+    opts.cwd = fx.cwd.string();
+    opts.swarm_mode = "mesh";
+    const auto id = fx.registry.create(opts);
+    const auto result = fx.tools.execute("agent_spawn",
+        R"({"task_name":"worker","message":"go","fork_turns":"none","sampling":{"temperature":0,"top_k":20}})", fx.ctx_for(id));
+    ASSERT_TRUE(result.success) << result.output;
+    EXPECT_EQ(observed.temperature, 0);
+    EXPECT_EQ(observed.top_k, 20);
+    const auto size = fx.registry.size();
+    const auto invalid = fx.tools.execute("agent_spawn",
+        R"({"task_name":"bad","message":"go","sampling":{"min_p":2}})", fx.ctx_for(id));
+    EXPECT_FALSE(invalid.success);
+    EXPECT_EQ(fx.registry.size(), size);
+    service->shutdown();
+    fx.registry.shutdown_all();
+}
+
 TEST(SpawnSubagentTool, RejectsWhenDepsMissing) {
     auto empty = std::make_shared<acecode::SubagentToolDeps>();
     auto tool = acecode::create_spawn_subagent_tool(empty);
diff --git a/tests/skills/expert_manager_sampling_test.py b/tests/skills/expert_manager_sampling_test.py
new file mode 100644
index 000000000..22120a909
--- /dev/null
+++ b/tests/skills/expert_manager_sampling_test.py
@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT / "assets/seed/skills/expert-management/expert-manager/scripts"))
+
+from batch_create import create_one
+from validate_expert import ValidationResult, validate_sampling
+
+
+class ExpertManagerSamplingTests(unittest.TestCase):
+    def test_batch_preserves_sampling_in_installed_manifest(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary) / "experts"
+            sampling = {"temperature": 0, "top_p": 0.95, "top_k": 20, "min_p": 0}
+            item = {
+                "name": "sampling-expert", "type": "agent", "displayName": "Sampler",
+                "profession": "Reviewer", "displayDescription": "Reviews code",
+                "instructions": "Review carefully", "quickPrompts": ["Review this"],
+                "sampling": sampling,
+            }
+            ok, message = create_one(item, root)
+            self.assertTrue(ok, message)
+            manifest = json.loads((root / item["name"] / "expert.json").read_text(encoding="utf-8"))
+            self.assertEqual(manifest["sampling"], sampling)
+            item["name"] = "invalid-expert"
+            item["sampling"] = {"top_k": 1.5}
+            ok, message = create_one(item, root)
+            self.assertFalse(ok)
+            self.assertIn("sampling.top_k", message)
+            self.assertFalse((root / item["name"]).exists())
+
+    def test_validator_accepts_inheritance_and_rejects_bad_fields(self) -> None:
+        for value in [None, {}, {"temperature": 0, "top_p": None, "min_p": 0}]:
+            result = ValidationResult()
+            validate_sampling(value, result)
+            self.assertTrue(result.is_valid, result.summary())
+        for value in [[], {"temperature": True}, {"temperature": "1"}, {"top_p": 0},
+                      {"top_k": 1.5}, {"top_k": 10 ** 400}, {"min_p": 2}, {"typo": 1}]:
+            result = ValidationResult()
+            validate_sampling(value, result)
+            self.assertFalse(result.is_valid, str(value))
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/tool/ios_simulator/xcode_locator_test.cpp b/tests/tool/ios_simulator/xcode_locator_test.cpp
index c9a85fb21..d0d132237 100644
--- a/tests/tool/ios_simulator/xcode_locator_test.cpp
+++ b/tests/tool/ios_simulator/xcode_locator_test.cpp
@@ -72,7 +72,7 @@ TEST_F(XcodeLocatorTest, InspectsGreenInstallsAndRejectsIncompleteCopies) {
     EXPECT_EQ(install->version, "26.6");
     EXPECT_EQ(install->build, "17F113");
     EXPECT_TRUE(install->simulator_kit);
-    EXPECT_TRUE(inspect_xcode((app / "Contents/Developer").string()).has_value());
+    EXPECT_TRUE(inspect_xcode((app / "Contents/Developer").generic_string()).has_value());
 
     fs::create_directories(root / "Broken.app/Contents");
     std::string why;
diff --git a/tests/upgrade/upgrade_apply_test.cpp b/tests/upgrade/upgrade_apply_test.cpp
index 4ed536831..69d603e1f 100644
--- a/tests/upgrade/upgrade_apply_test.cpp
+++ b/tests/upgrade/upgrade_apply_test.cpp
@@ -165,11 +165,11 @@ TEST(UpgradeApply, BuildsAndParsesRunnerArguments) {
               "\"C:/Program Files/ACECode/acecode.exe\"");
 
     auto runner = make_runner_path(1234, "C:/Program Files/ACECode");
-    EXPECT_EQ(runner.parent_path().filename(), ".acecode-update-runner");
+    EXPECT_EQ(runner.parent_path().filename(), ".acecode_update_runner");
 #ifdef _WIN32
-    EXPECT_EQ(runner.filename(), "acecode-update-runner-1234.exe");
+    EXPECT_EQ(runner.filename(), "acecode_update_runner_1234.exe");
 #else
-    EXPECT_EQ(runner.filename(), "acecode-update-runner-1234");
+    EXPECT_EQ(runner.filename(), "acecode_update_runner_1234");
 #endif
 }
 
diff --git a/tests/upgrade/upgrade_diagnostics_test.cpp b/tests/upgrade/upgrade_diagnostics_test.cpp
index 03e69fb88..d602c359b 100644
--- a/tests/upgrade/upgrade_diagnostics_test.cpp
+++ b/tests/upgrade/upgrade_diagnostics_test.cpp
@@ -82,6 +82,7 @@ TEST_F(UpgradeDiagnostics, RecordsAreFlushedBeforeDestructionAndAppendAcrossAtte
 //      长字符串截到 8192 字节再加 "...[truncated]" 标记,所以断言 < 8300。
 TEST_F(UpgradeDiagnostics, RedactsNestedUrlsAndBoundsErrorStrings) {
     DiagnosticLog log("upgrade", root);
+    EXPECT_EQ(fs::path(log.path()).filename().string().find('-'), std::string::npos);
     log.record("failure", {{"error", "GET HTTPS://user:password@host/pkg?token=secret#fragment failed"},
                            {"urls", {"http://name@host/x?auth=hidden", "https://[::1]/pkg?token=ipv6secret"}},
                            {"long_error", std::string(9000, 'a')}});
diff --git a/tests/utils/generated_file_names_test.cpp b/tests/utils/generated_file_names_test.cpp
new file mode 100644
index 000000000..11b01e0a9
--- /dev/null
+++ b/tests/utils/generated_file_names_test.cpp
@@ -0,0 +1,36 @@
+#include <gtest/gtest.h>
+
+#include "utils/generated_file_names.hpp"
+#include "utils/uuid.hpp"
+
+#include <filesystem>
+#include <fstream>
+
+namespace {
+
+TEST(GeneratedFileNames, NewPathsUseUnderscoresWithoutChangingParent) {
+    const auto root = std::filesystem::temp_directory_path() / "acecode_naming_parent-with-hyphen";
+    EXPECT_EQ(acecode::generated_file_name("upgrade-2026-10-16-123.log"),
+              "upgrade_2026_10_16_123.log");
+    EXPECT_EQ(acecode::compatible_generated_path(root, "new-data.json"),
+              root / "new_data.json");
+}
+
+TEST(GeneratedFileNames, LegacyStoreWinsWithoutCreatingAnEmptyReplacement) {
+    const auto root = std::filesystem::temp_directory_path() /
+        ("acecode_naming_" + acecode::generated_file_name(acecode::generate_uuid()));
+    std::filesystem::create_directories(root);
+    const auto old_path = root / "scheduled-loops.sqlite3";
+    const auto new_path = root / "scheduled_loops.sqlite3";
+    { std::ofstream out(old_path); out << "existing data"; }
+    EXPECT_EQ(acecode::compatible_generated_path(root, "scheduled-loops.sqlite3"), old_path);
+    EXPECT_FALSE(std::filesystem::exists(new_path));
+    { std::ofstream out(new_path); out << "separate data"; }
+    EXPECT_EQ(acecode::compatible_generated_path(root, "scheduled-loops.sqlite3"), old_path);
+    std::filesystem::remove(old_path);
+    EXPECT_EQ(acecode::compatible_generated_path(root, "scheduled-loops.sqlite3"), new_path);
+    std::filesystem::remove(new_path);
+    std::filesystem::remove(root);
+}
+
+} // namespace
diff --git a/tests/utils/logger_test.cpp b/tests/utils/logger_test.cpp
index 674147ece..00c74bff8 100644
--- a/tests/utils/logger_test.cpp
+++ b/tests/utils/logger_test.cpp
@@ -117,7 +117,7 @@ TEST_F(LoggerRotationTest, InitWithRotationCreatesDirAndInitialFile) {
     int matched = 0;
     for (auto& e : fs::directory_iterator(logs_dir)) {
         auto fn = e.path().filename().string();
-        if (fn.rfind("daemon-", 0) == 0 &&
+        if (fn.rfind("daemon_", 0) == 0 &&
             fn.size() > 14 /* daemon-YYYY-MM-DD.log */) {
             matched++;
             auto body = read_file(e.path());
@@ -142,7 +142,7 @@ TEST_F(LoggerRotationTest, TuiRotationUsesTuiDatePrefixWithoutStderrMirror) {
     int matched = 0;
     for (const auto& entry : fs::directory_iterator(logs_dir)) {
         const auto filename = entry.path().filename().string();
-        if (filename.rfind("tui-", 0) == 0 &&
+        if (filename.rfind("tui_", 0) == 0 &&
             filename.size() > 11 /* tui-YYYY-MM-DD.log */) {
             ++matched;
             EXPECT_NE(read_file(entry.path()).find("tui-centralized-line"),
@@ -208,7 +208,7 @@ TEST_F(LoggerRotationTest, ConditionalRotationInitializesOnlyWhenDisabled) {
 }
 
 // 场景: 跨日滚动 — 用 set_clock_for_test 强制把"今天"推到 2099-01-02,
-// 下一条 LOG 应该落在 daemon-2099-01-02.log,前一条仍留在原文件。
+// 下一条 LOG 应该落在 daemon_2099_01_02.log,前一条仍留在原文件。
 // 这是 spec Section 12.2 的核心断言。
 TEST_F(LoggerRotationTest, RotationCreatesNewFileWhenDateAdvances) {
     auto logs_dir = tmp_dir_ / "logs";
@@ -223,8 +223,8 @@ TEST_F(LoggerRotationTest, RotationCreatesNewFileWhenDateAdvances) {
     acecode::Logger::instance().set_clock_for_test([] { return std::string("2099-01-02"); });
     LOG_INFO("today-line");
 
-    auto yesterday_path = logs_dir / "daemon-2099-01-01.log";
-    auto today_path     = logs_dir / "daemon-2099-01-02.log";
+    auto yesterday_path = logs_dir / "daemon_2099_01_01.log";
+    auto today_path     = logs_dir / "daemon_2099_01_02.log";
 
     ASSERT_TRUE(fs::exists(yesterday_path)) << "昨天的文件应该存在";
     ASSERT_TRUE(fs::exists(today_path))     << "今天的文件应该存在";
@@ -278,7 +278,7 @@ TEST_F(LoggerRotationTest, SingleFileModeIgnoresClockOverride) {
     // 不应在 tmp_dir_ 下出现 daemon-*.log 这种产物
     for (auto& e : fs::directory_iterator(tmp_dir_)) {
         auto fn = e.path().filename().string();
-        EXPECT_EQ(fn.rfind("daemon-", 0), std::string::npos)
+        EXPECT_EQ(fn.rfind("daemon_", 0), std::string::npos)
             << "单文件模式不应被 clock 注入误产 daemon-*.log: " << fn;
     }
 }
diff --git a/tests/utils/paths_test.cpp b/tests/utils/paths_test.cpp
index 1154c286e..98f332915 100644
--- a/tests/utils/paths_test.cpp
+++ b/tests/utils/paths_test.cpp
@@ -337,7 +337,7 @@ TEST_F(DataDirRedirectTest, CorruptPointerIsIgnored) {
     auto warning = acecode::take_data_dir_resolution_warning();
     ASSERT_TRUE(warning.has_value());
     EXPECT_NE(warning->find("invalid"), std::string::npos) << *warning;
-    EXPECT_NE(warning->find(acecode::kDataDirRedirectFileName), std::string::npos)
+    EXPECT_NE(warning->find(acecode::data_dir_redirect_path(default_dir())), std::string::npos)
         << "告警应带上指针文件路径,便于定位: " << *warning;
 }
 
diff --git a/tests/web/security_handler_test.cpp b/tests/web/security_handler_test.cpp
index 74ebc90d0..079e8f5c0 100644
--- a/tests/web/security_handler_test.cpp
+++ b/tests/web/security_handler_test.cpp
@@ -219,7 +219,7 @@ TEST(SecurityHandler, SerializesAuditPageAndSummary) {
     EXPECT_EQ(s["blocked_paths"][0]["path"], "C:/secret");
     EXPECT_EQ(s["blocked_paths"][0]["count"], 1);
 
-    EXPECT_EQ(audit_export_filename("csv", 0).substr(0, 14), "acecode-audit-");
+    EXPECT_EQ(audit_export_filename("csv", 0).substr(0, 14), "acecode_audit_");
     EXPECT_NE(audit_export_filename("csv", 0).find(".csv"), std::string::npos);
     EXPECT_NE(audit_export_filename("jsonl", 0).find(".jsonl"), std::string::npos);
 }
diff --git a/tests/web/web_server_smoke_test.cpp b/tests/web/web_server_smoke_test.cpp
index a5119918a..20b6a0e00 100644
--- a/tests/web/web_server_smoke_test.cpp
+++ b/tests/web/web_server_smoke_test.cpp
@@ -9224,7 +9224,7 @@ TEST(WebServerHttp, CustomThemeExportProtectsBuiltinsAndDownloadsAuthenticatedZi
     ASSERT_EQ(downloaded.status_code, 200) << downloaded.text;
     EXPECT_EQ(response_header(downloaded, "Content-Type"), "application/zip");
     EXPECT_EQ(response_header(downloaded, "X-Content-Type-Options"), "nosniff");
-    EXPECT_NE(response_header(downloaded, "Content-Disposition").find("filename*=UTF-8''ACECode-"), std::string::npos);
+    EXPECT_NE(response_header(downloaded, "Content-Disposition").find("filename*=UTF-8''ACECode_"), std::string::npos);
     EXPECT_NE(response_header(downloaded, "Cache-Control").find("no-store"), std::string::npos);
     EXPECT_EQ(downloaded.text.substr(0, 2), "PK");
     EXPECT_EQ(cpr::Get(cpr::Url{fx.url("/api/themes/exports/missing")}).status_code, 404);
@@ -9588,7 +9588,7 @@ TEST(WebServerHttp, DesktopFeedbackUploadsSelectedSessionOnly) {
     ASSERT_EQ(r.status_code, 200) << r.text;
     auto body = json::parse(r.text);
     EXPECT_EQ(body["selected_session_id"], sid);
-    EXPECT_EQ(read_zip_entry(received_zip, "session/" + sid + ".jsonl"),
+    EXPECT_EQ(read_zip_entry(received_zip, "session/20260618_030000_abcf.jsonl"),
               "{\"role\":\"user\",\"content\":\"selected\"}\n");
     EXPECT_FALSE(zip_entry_exists(received_zip, "session/other.jsonl"));
     auto metadata = json::parse(read_zip_entry(received_zip, "feedback.json"));
@@ -9637,8 +9637,8 @@ TEST(WebServerHttp, DesktopFeedbackMaterializesEmptySelectedSession) {
     auto body = json::parse(r.text);
     EXPECT_EQ(body["selected_session_id"], sid);
     EXPECT_TRUE(std::filesystem::is_regular_file(session_jsonl));
-    EXPECT_TRUE(zip_entry_exists(received_zip, "session/" + sid + ".jsonl"));
-    EXPECT_TRUE(read_zip_entry(received_zip, "session/" + sid + ".jsonl").empty());
+    EXPECT_TRUE(zip_entry_exists(received_zip, "session/20260618_031500_abc0.jsonl"));
+    EXPECT_TRUE(read_zip_entry(received_zip, "session/20260618_031500_abc0.jsonl").empty());
 
     std::error_code ec;
     std::filesystem::remove(received_zip, ec);
@@ -9708,7 +9708,7 @@ TEST(WebServerHttp, DesktopFeedbackUploadsNoWorkspaceSessionTranscript) {
     auto body = json::parse(r.text);
     EXPECT_EQ(body["selected_session_id"], sid);
     EXPECT_EQ(body["workspace_hash"], "");
-    EXPECT_EQ(read_zip_entry(received_zip, "session/" + sid + ".jsonl"),
+    EXPECT_EQ(read_zip_entry(received_zip, "session/20260923_170433_bd13.jsonl"),
               "{\"role\":\"user\",\"content\":\"no workspace\"}\n");
     auto metadata = json::parse(read_zip_entry(received_zip, "feedback.json"));
     EXPECT_EQ(metadata["selected_session_id"], sid);
@@ -11904,7 +11904,7 @@ TEST(WebServerHttp, ToolRewritesRoundTripPersistsJsonAndAppliesToProcess) {
     EXPECT_EQ(json::parse(enable.text)["rewrites"]["file_read"], "peek");
     EXPECT_EQ(acecode::model_tool_name_for_native("file_read"), "peek");
     {
-        std::ifstream ifs(fx.tmp_dir / acecode::tool_rewrites::kSettingsFileName);
+        std::ifstream ifs(fx.tmp_dir / "tool_rewrites.json");
         ASSERT_TRUE(ifs.is_open());
         auto saved = json::parse(ifs);
         EXPECT_EQ(saved["enabled"], true);
@@ -13213,7 +13213,7 @@ TEST(SecurityCenterSmoke, AuditRoutesListSummarizeExportAndClear) {
     auto csv = cpr::Get(cpr::Url{fx.url("/api/security/audit/export?format=csv")});
     ASSERT_EQ(csv.status_code, 200) << csv.text;
     EXPECT_NE(csv.header["Content-Type"].find("text/csv"), std::string::npos);
-    EXPECT_NE(csv.header["Content-Disposition"].find("attachment; filename=\"acecode-audit-"), std::string::npos);
+    EXPECT_NE(csv.header["Content-Disposition"].find("attachment; filename=\"acecode_audit_"), std::string::npos);
     EXPECT_EQ(csv.text.rfind("id,ts_ms,category,", 0), 0u);
     EXPECT_NE(csv.text.find("git status"), std::string::npos);
     auto jsonl = cpr::Get(cpr::Url{fx.url("/api/security/audit/export")});
diff --git a/web/scripts/i18n-en-overrides.mjs b/web/scripts/i18n-en-overrides.mjs
index 00ffa7aed..63cf4699b 100644
--- a/web/scripts/i18n-en-overrides.mjs
+++ b/web/scripts/i18n-en-overrides.mjs
@@ -1,6 +1,14 @@
 // Human-reviewed product terminology and phrases where generic machine
 // translation is ambiguous without ACECode context.
 export const ENGLISH_SOURCE_OVERRIDES = Object.freeze({
+  '采样参数（可选）': 'Sampling parameters (optional)',
+  '作为团队默认值；成员自己的采样设置优先，留空的参数继承模型设置。': 'Team defaults. Each member’s own sampling settings take priority. Blank fields inherit model settings.',
+  '留空的参数继承模型设置；发起子任务时可单独覆盖。': 'Blank fields inherit model settings. Each subtask can override them when started.',
+  '参数需受所用模型支持。': 'The selected model must support these parameters.',
+  '继承模型': 'Inherit model',
+  '大于 0，最多 1': 'Greater than 0, at most 1',
+  '正整数': 'A positive integer',
+  '{{p0}}：请输入{{p1}}的数值，或留空继承': '{{p0}}: enter a value in the range {{p1}}, or leave blank to inherit',
   '侧边聊天存续时间': 'Side chat retention time',
   'side chat retention lifetime minutes ttl 侧聊 保留 过期 分钟': 'side chat retention lifetime minutes ttl',
   '从最后一次侧聊结束开始计时，到期后切回该会话时清空；正在查看时不会自动消失。': 'Starts when the last side chat ends. After this time, returning to the session clears it. It stays visible while you are viewing it.',
diff --git a/web/scripts/test-classic-desktop-pets.mjs b/web/scripts/test-classic-desktop-pets.mjs
index 8c686941e..1fb290161 100644
--- a/web/scripts/test-classic-desktop-pets.mjs
+++ b/web/scripts/test-classic-desktop-pets.mjs
@@ -30,17 +30,22 @@ const EXPECT = {
     fidgets: ['IdleAtom', 'IdleEyeBrowRaise', 'IdleFingerTap', 'IdleHeadScratch', 'IdleRopePile', 'IdleSideToSide',
       'LookUp', 'LookDown', 'LookLeft', 'LookRight', 'LookUpLeft', 'LookUpRight', 'GetArtsy', 'GetWizardy', 'Hearing_1'],
     jumping: 'GetAttention', click: 'Wave', drag: 'Idle1_1', left: ['LookLeft', false], right: ['LookRight', false],
-    sleep: 'IdleSnooze', wake: 'IdleEyeBrowRaise', maxStillMs: 2500 },
+    sleep: 'IdleSnooze', wake: 'IdleEyeBrowRaise', maxStillMs: 2500, peekHeight: [104, 118] },
   rover: { greet: 'Show', think: ['Thinking'], work: ['Searching', 'ImageSearching', 'Books'],
     attention: 'GetAttention', waiting: 'GetAttentionMinor', failed: 'Embarrassed', review: 'Congratulate', idle: 'Idle',
     fidgets: ['Sports', 'Cooking', 'Shopping', 'Books', 'Money', 'Celebrity', 'Travel', 'LookUp', 'LookUpLeft', 'Acknowledge'],
     jumping: 'Pleased', click: 'ClickedOn', drag: 'Surprised', left: ['GestureLeft', false], right: ['GestureLeft', true],
-    sleep: null, maxStillMs: 2500 },
+    sleep: null, maxStillMs: 2500, peekHeight: [90, 106] },
   whale: { greet: 'welcome', think: ['think'], work: ['working'], attention: 'welcome', waiting: 'wait', failed: 'error',
     review: 'celebrate', idle: 'idle', fidgets: ['play', 'eat', 'welcome', 'joy'], jumping: 'joy', click: 'welcome',
-    drag: 'drag', left: ['drag', false], right: ['drag', false], sleep: 'sleep', wake: 'wake', maxStillMs: 1500 },   // breathing slows at each breath's turn
+    drag: 'drag', left: ['drag', false], right: ['drag', false], sleep: 'sleep', wake: 'wake', maxStillMs: 1500,   // breathing slows at each breath's turn
+    peekHeight: [80, 100] },
 };
 const mac = process.env.ACE_OFFICE_HOST === 'mac';
+const folder = kind => (kind === 'whale' ? 'whale' : `classic/${kind}`);
+const dataUri = file => 'data:image/png;base64,' + fs.readFileSync(path.join(assets, file)).toString('base64');
+// What the native host sends for each pet (desktop_pet_character): sprite sheet + edge-peek sheet.
+const character = kind => ({ type: 'pet-character', kind, sprite: dataUri(`${folder(kind)}/map.png`), peek: dataUri(`${folder(kind)}/peek.png`) });
 const browser = await chromium.launch({ channel: process.env.ACE_BROWSER_CHANNEL || 'msedge', headless: true });
 const errors = [], external = [], checked = [];
 try {
@@ -79,9 +84,7 @@ try {
     await away();
     assert.ok(await page.evaluate(() => actions.includes('ready')));
     await send(snapshot());
-    const map = path.join(assets, kind === 'whale' ? 'whale' : `classic/${kind}`, 'map.png');
-    const peekSheet = kind === 'whale' ? 'data:image/png;base64,' + fs.readFileSync(path.join(assets, 'whale/peek.png')).toString('base64') : undefined;
-    await send({ type: 'pet-character', kind, sprite: 'data:image/png;base64,' + fs.readFileSync(map).toString('base64'), peek: peekSheet });
+    await send(character(kind));
     await page.waitForFunction(value => ClassicPet.kind === value, kind);
     // Codex greets with a wave when the pet appears; a greeting card also explains how to open ACECode.
     assert.equal((await pet()).animation, expect.greet, `${kind} greets first`);
@@ -168,7 +171,14 @@ try {
     await page.mouse.move(215, 240);
     await page.waitForFunction(() => ClassicPet.hovered);
     assert.equal((await pet()).animation, expect.jumping, `${kind} jumps on hover`);
-    assert.equal((await overlay()).bubbles.length, 2, 'hovered pet keeps its whole box hit-testable');
+    // 场景:鼠标停在宠物身上(openspec tighten-companion-pet-hit-area)。旧行为:悬停时整张精灵框都拦截点击,
+    // 宠物四周的透明部分也挡住后面的窗口。期望:悬停时仍按轮廓横条上报,只在鼠标下多一个 6×6 画布像素的
+    // 锚点(动作跳开时悬停不闪断);缩放三角形不混在轮廓里,单独作为 grip 上报。
+    const hoverRegion = await overlay(), anchor = hoverRegion.bubbles.at(-1);
+    assert.ok(hoverRegion.bubbles.length > 2, 'hovered pet still reports its silhouette bands, not one sprite box');
+    assert.ok(Math.abs((anchor[2] - anchor[0]) * 344 - 6) < 0.01 && Math.abs((anchor[3] - anchor[1]) * 252 - 6) < 0.01, 'hover anchor is a small square');
+    assert.ok(anchor[0] <= 215 / 430 && anchor[2] >= 215 / 430 && anchor[1] <= 240 / 315 && anchor[3] >= 240 / 315, 'hover anchor sits under the pointer');
+    assert.ok(Array.isArray(hoverRegion.grip), 'the resize grip is reported on its own');
     await page.mouse.click(215, 240);
     assert.equal((await pet()).animation, expect.click, `${kind} reacts to a click`);
     await page.waitForTimeout(500);
@@ -235,52 +245,52 @@ try {
     assert.deepEqual(await cardFont(), ['15px', '24px', '15px'], 'malformed font values are ignored');
     await send(cards([], { transcriptFont: { size: '14px' } }));
 
-    // Docking: only Whale Girl has edge-peek art. Docked she peeks in from that edge, blinks,
-    // squints happily when hovered, and picking her up restores the full figure.
+    // Docking: every companion pet has edge-peek art. Docked it peeks in from that edge, blinks,
+    // squints happily when hovered, and picking it up restores the full figure.
     const alphaAt = (x0, x1) => page.evaluate(([a, b]) => {
       const d = document.getElementById('cv').getContext('2d').getImageData(a, 150, b - a, 90).data;
       let n = 0; for (let i = 3; i < d.length; i += 4) if (d[i] > 32) n++; return n;
     }, [x0, x1]);
     await send({ type: 'pet-dock', side: 'right' });
-    if (kind !== 'whale') {
-      assert.equal(await page.evaluate(() => ClassicPet.docked), '', `${kind} has no edge-peek art`);
-    } else {
-      assert.equal(await page.evaluate(() => ClassicPet.docked), 'right');
-      assert.equal((await pet()).animation, 'peek');
-      assert.ok(await alphaAt(300, 344) > 500 && await alphaAt(0, 120) === 0, 'peeks in from the right edge');
-      // 场景:贴右边换成偷看图。bug 表现:曾固定画成 170 像素高,头比站着时大将近一倍。
-      // 期望:按常规帧缩放 ÷ 1.8(偷看原画比精灵帧大 1.8 倍)画,300 像素高的原画约 91 像素。
-      const peekHeight = await page.evaluate(() => {
-        const d = document.getElementById('cv').getContext('2d').getImageData(0, 0, 344, 252).data;
-        let top = 252, bottom = -1;
-        for (let y = 0; y < 252; y++) for (let x = 0; x < 344; x++) if (d[(y * 344 + x) * 4 + 3] > 32) { top = Math.min(top, y); bottom = y; break; }
-        return bottom - top + 1;
-      });
-      assert.ok(peekHeight >= 80 && peekHeight <= 100, `peek head matches the standing pose (${peekHeight}px tall)`);
-      await page.waitForFunction(() => ClassicPet.peekEyes === 1, null, { timeout: 12000 });
-      await page.waitForFunction(() => ClassicPet.peekEyes === 0, null, { timeout: 2000 });
-      assert.ok(await longestStill(1500) < 1500, 'docked whale keeps swaying');
-      const region = await overlay();
-      assert.ok(region.bubbles.length > 2 && region.bubbles.every(b => b[2] > 0.6 || b[0] < 0.1), 'hit region follows the peeking head');
-      await page.screenshot({ path: path.join(output, 'whale-docked-right.png'), omitBackground: true });
-      await page.mouse.move(400, 230);
-      await page.waitForFunction(() => ClassicPet.hovered);
-      assert.equal((await pet()).animation, 'peek-happy', 'hover gets a happy squint');
-      await away();
-      await send(cards([card('peek', 'running', 'work', { turn: '7' })]));
-      await send(cards([card('peek', 'review', 'sleep', { turn: '7' })]));
-      assert.equal((await pet()).animation, 'peek-happy', 'a finished session gets a happy squint while docked');
-      await send({ type: 'pet-dock', side: 'left' });
-      await page.waitForTimeout(100);
-      assert.ok(await alphaAt(0, 44) > 500 && await alphaAt(220, 344) === 0, 'mirrored for the left edge');
-      await page.screenshot({ path: path.join(output, 'whale-docked-left.png'), omitBackground: true });
-      await page.waitForTimeout(350);
-      await send({ type: 'pet-drag', phase: 'start' });
-      assert.equal(await page.evaluate(() => ClassicPet.docked), '', 'picking her up leaves the edge');
-      assert.equal((await pet()).animation, 'drag');
-      await send({ type: 'pet-drag', phase: 'end' });
-      await send(cards([]));
-    }
+    assert.equal(await page.evaluate(() => ClassicPet.docked), 'right');
+    assert.equal((await pet()).animation, 'peek');
+    assert.ok(await alphaAt(300, 344) > 500 && await alphaAt(0, 120) === 0, `${kind} peeks in from the right edge`);
+    // 场景:贴右边换成偷看图。bug 表现:鲸鱼娘曾固定画成 170 像素高,头比站着时大将近一倍。
+    // 期望:偷看图按常规帧缩放 ÷ 原画倍数画,头和其它姿势一样大 —— 鲸鱼娘原画大 1.8 倍,
+    // 300 像素高约 91 像素;回形针 / Rover 的原画就是精灵分辨率,75 / 56 行按 1.48 / 1.75 倍约 111 / 98 像素。
+    const peekHeight = await page.evaluate(() => {
+      const d = document.getElementById('cv').getContext('2d').getImageData(0, 0, 344, 252).data;
+      let top = 252, bottom = -1;
+      for (let y = 0; y < 252; y++) for (let x = 0; x < 344; x++) if (d[(y * 344 + x) * 4 + 3] > 32) { top = Math.min(top, y); bottom = y; break; }
+      return bottom - top + 1;
+    });
+    const [minPeek, maxPeek] = expect.peekHeight;
+    assert.ok(peekHeight >= minPeek && peekHeight <= maxPeek, `${kind} peek head matches the standing pose (${peekHeight}px tall)`);
+    await page.waitForFunction(() => ClassicPet.peekEyes === 1, null, { timeout: 12000 });
+    await page.waitForFunction(() => ClassicPet.peekEyes === 0, null, { timeout: 2000 });
+    // 场景:像素宠物藏在屏幕外的只有 4 像素。bug 表现:摇摆幅度固定 0~6 像素时,超过 4 的那段被截住,
+    // 每个周期有约 4.7 秒一动不动。期望:幅度随藏边距离缩放,贴边时一直在轻轻晃。
+    assert.ok(await longestStill(1500) < 1500, `docked ${kind} keeps swaying`);
+    const region = await overlay();
+    assert.ok(region.bubbles.length > 2 && region.bubbles.every(b => b[2] > 0.6 || b[0] < 0.1), 'hit region follows the peeking head');
+    await page.screenshot({ path: path.join(output, `${kind}-docked-right.png`), omitBackground: true });
+    await page.mouse.move(400, 230);
+    await page.waitForFunction(() => ClassicPet.hovered);
+    assert.equal((await pet()).animation, 'peek-happy', 'hover gets a happy squint');
+    await away();
+    await send(cards([card('peek', 'running', 'work', { turn: '7' })]));
+    await send(cards([card('peek', 'review', 'sleep', { turn: '7' })]));
+    assert.equal((await pet()).animation, 'peek-happy', 'a finished session gets a happy squint while docked');
+    await send({ type: 'pet-dock', side: 'left' });
+    await page.waitForTimeout(100);
+    assert.ok(await alphaAt(0, 44) > 500 && await alphaAt(220, 344) === 0, 'mirrored for the left edge');
+    await page.screenshot({ path: path.join(output, `${kind}-docked-left.png`), omitBackground: true });
+    await page.waitForTimeout(350);
+    await send({ type: 'pet-drag', phase: 'start' });
+    assert.equal(await page.evaluate(() => ClassicPet.docked), '', 'picking it up leaves the edge');
+    assert.equal((await pet()).animation, expect.drag);
+    await send({ type: 'pet-drag', phase: 'end' });
+    await send(cards([]));
 
     if (kind === 'whale') {
       const states = Object.keys(JSON.parse(fs.readFileSync(path.join(assets, 'whale/manifest.json'), 'utf8')).characters['whale-girl'].states);
@@ -302,7 +312,26 @@ try {
     assert.ok(reducedStill <= expect.maxStillMs, `${kind} froze for ${Math.round(reducedStill)}ms under reduce motion`);
     await page.mouse.move(215, 240);
     await page.waitForFunction(() => ClassicPet.hovered);
+    // 场景:鼠标停在宠物身上 / 刚点过会话卡片。bug 表现:左上角的缩放三角形跟着整个场景的悬停和焦点
+    // 一起出现,看起来一直挂在那里(用户反馈)。期望:只有鼠标移到三角形上才显示,移开就隐藏,
+    // 隐藏时仍在命中区域里,照样能拖。
+    const gripOpacity = () => page.locator('#grip').evaluate(node => Number(getComputedStyle(node).opacity));
+    await page.waitForTimeout(200);
+    assert.equal(await gripOpacity(), 0, 'resize handle hidden while hovering the pet');
+    // 三角形跟着动画轮廓的左上角走,量完位置再移过去时它可能已经挪开,所以对准几次;
+    // 一旦鼠标停在上面它就不再移动(bug 表现:三角形一直跟着动作跑,悬停和按住都抓不住)。
+    const onGrip = () => page.evaluate(() => document.getElementById('grip').matches(':hover'));
+    for (let attempt = 0; attempt < 20 && !(await onGrip()); attempt++) {
+      const gripBox = await page.locator('#grip').boundingBox();
+      await page.mouse.move(gripBox.x + 8, gripBox.y + 8);
+    }
+    assert.ok(await onGrip(), 'pointer reaches the resize handle');
+    await page.waitForFunction(() => Number(getComputedStyle(document.getElementById('grip')).opacity) === 1);
+    await page.waitForTimeout(1200);
+    assert.ok(await onGrip(), 'the resize handle holds still under the pointer while the pet keeps moving');
     await away();
+    await page.waitForTimeout(200);
+    assert.equal(await gripOpacity(), 0, 'resize handle hides again once the pointer leaves');
     await page.emulateMedia({ reducedMotion: 'no-preference' });
 
     // Right-click is the only menu (native: switch pet, keep on top, hide).
@@ -313,17 +342,56 @@ try {
     await send(cards([card('x', 'running', 'work')], { connected: false }));
     assert.deepEqual((await page.evaluate(() => ClassicPet.cards)).map(c => c.key), ['offline']);
 
-    await send(snapshot('work'));
+    // A long title and body: they must end in an ellipsis instead of running under the stop button.
+    await send(cards([card('live', 'running', 'work', { title: '探寻 ACECode 宠物贴边与缩小显示的问题',
+      body: '有人从爱号连接里过来了，正在逐个排查卡片在小窗口里被切掉的原因' })]));
     for (const width of [172, 430, 860]) {
       await page.setViewportSize({ width, height: Math.round(width * 252 / 344) });
       await page.mouse.move(-10, -10); await page.waitForTimeout(1100);
       assert.equal(await page.evaluate(() => document.documentElement.scrollWidth), width);
+      // 场景:用滚轮 / 把手把宠物缩小。bug 表现:卡片保持对话正文字号,宠物却跟着窗口缩小,
+      // 窗口宽度低于约 280 时卡片顶端跑出窗口被切掉;正文又是行内元素,长句压到停止按钮下面
+      // (用户反馈「缩小到一定程度会显示不全」)。期望:卡片整张留在窗口里,放不下时按需缩小
+      // (不小于 9px),默认大小及以上保持原字号;正文在停止按钮前省略。
+      const fitted = await page.evaluate(() => {
+        const stackBox = document.getElementById('stack').getBoundingClientRect(), card = document.querySelector('.card');
+        const body = card.querySelector('.body').getBoundingClientRect(), stop = card.querySelector('.stop').getBoundingClientRect();
+        return { top: card.getBoundingClientRect().top, stackTop: stackBox.top, font: parseFloat(getComputedStyle(card).fontSize),
+          bodyRight: body.right, stopLeft: stop.left };
+      });
+      assert.ok(fitted.top >= 0 && fitted.stackTop >= -0.5, `cards stay inside a ${width}px window (${JSON.stringify(fitted)})`);
+      assert.ok(width < 430 ? fitted.font >= 9 && fitted.font < 14 : fitted.font === 14, `card text size at ${width}px: ${fitted.font}`);
+      assert.ok(fitted.bodyRight <= fitted.stopLeft, 'card body ends before the stop button');
       await page.screenshot({ path: path.join(output, `${kind}-${width}.png`), omitBackground: true });
     }
     await page.setViewportSize({ width: 430, height: 315 });
     checked.push(kind);
   }
+
+  // 场景:窗口贴着屏幕边时换宠物,或者页面刚打开、素材还在解码时宿主就发来了贴边消息。
+  // bug 表现:页面加载角色时把贴边状态清空,窗口还在屏幕边上,宠物却站着露出半个身子。
+  // 期望:页面记住窗口所在的边,新宠物素材一到就接着从同一条边偷看;拿起来之后再换宠物就不再贴边。
+  await page.goto('about:blank');
+  await page.setContent(html);
+  await away();
+  await send(snapshot());
+  await send({ type: 'pet-dock', side: 'right' });
+  await send(character('clippy'));
+  await page.waitForFunction(() => ClassicPet.kind === 'clippy');
+  assert.equal(await page.evaluate(() => ClassicPet.docked), 'right', 'dock request that arrived before the sprites still applies');
+  assert.equal((await pet()).animation, 'peek');
+  await send(character('rover'));
+  await page.waitForFunction(() => ClassicPet.kind === 'rover');
+  assert.equal(await page.evaluate(() => ClassicPet.docked), 'right', 'a pet switched in while docked keeps peeking');
+  assert.equal((await pet()).animation, 'peek');
+  await page.waitForTimeout(350);   // a drag start right after a pet loads is ignored as a stray echo
+  await send({ type: 'pet-drag', phase: 'start' });
+  assert.equal(await page.evaluate(() => ClassicPet.docked), '', 'picking it up leaves the edge');
+  await send({ type: 'pet-drag', phase: 'end' });
+  await send(character('whale'));
+  await page.waitForFunction(() => ClassicPet.kind === 'whale');
+  assert.equal(await page.evaluate(() => ClassicPet.docked), '', 'after being picked up a new pet stands normally');
   assert.deepEqual(errors, []); assert.deepEqual(external, []);
   console.log(JSON.stringify({ ok: true, host: mac ? 'mac-shim' : 'windows', checked,
-    coverage: 'offline decoding, greeting, all 15 whale states, running/waiting/failed/success states, idle never still, random preset actions, session card deck (collapse/expand/open/stop/dismiss, nothing when idle), transcript font, whale edge docking (peek, blink, hover, left/right, pick up), hover jump, click reaction, double-click activate, drag directions, sleep/wake, keeps moving under reduce motion, silhouette, right-click menu, three sizes', output }));
+    coverage: 'offline decoding, greeting, all 15 whale states, running/waiting/failed/success states, idle never still, random preset actions, session card deck (collapse/expand/open/stop/dismiss, nothing when idle), transcript font, edge docking for all three pets (peek, blink, hover, left/right, pick up, switch while docked), hover jump, click reaction, double-click activate, drag directions, sleep/wake, keeps moving under reduce motion, silhouette, right-click menu, three sizes', output }));
 } finally { await browser.close(); }
diff --git a/web/scripts/test-desktop-office.mjs b/web/scripts/test-desktop-office.mjs
index c05f22b0b..7c2a3a27a 100644
--- a/web/scripts/test-desktop-office.mjs
+++ b/web/scripts/test-desktop-office.mjs
@@ -58,6 +58,17 @@ try {
   await page.screenshot({path:path.join(output,'office-controls-hidden.png')});
   await page.mouse.move(344,280);
   assert.equal(await controlsVisible(),true,'hover reveals the menu');
+  // 场景:鼠标停在房间里。bug 表现:左上角的缩放三角形跟着整个场景悬停一起出现,看起来一直挂着(用户反馈)。
+  // 期望:只有鼠标移到三角形上才显示,移开就隐藏;隐藏时仍可拖动缩放。
+  const gripOpacity=()=>page.locator('#grip').evaluate(node=>Number(getComputedStyle(node).opacity));
+  await page.waitForTimeout(200);
+  assert.equal(await gripOpacity(),0,'resize handle hidden while hovering the room');
+  const gripBox=await page.locator('#grip').boundingBox();
+  await page.mouse.move(gripBox.x+8,gripBox.y+8);
+  await page.waitForFunction(()=>Number(getComputedStyle(document.getElementById('grip')).opacity)>0.9);
+  await page.mouse.move(344,280);
+  await page.waitForTimeout(200);
+  assert.equal(await gripOpacity(),0,'resize handle hides again once the pointer leaves it');
   assert.ok(Array.isArray((await lastOverlay()).controls),'visible menu supplies a native hit region');
   await page.mouse.move(-10,-10);
   await page.waitForTimeout(550);
diff --git a/web/scripts/test-expert-sampling.mjs b/web/scripts/test-expert-sampling.mjs
new file mode 100644
index 000000000..fad9d8c12
--- /dev/null
+++ b/web/scripts/test-expert-sampling.mjs
@@ -0,0 +1,87 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createServer } from 'vite';
+
+const web = fileURLToPath(new URL('../', import.meta.url));
+const modulePath = process.env.ACE_PLAYWRIGHT_MODULE;
+const { chromium } = await import(modulePath ? pathToFileURL(path.resolve(modulePath)).href : 'playwright');
+const output = await fs.mkdtemp(path.join(os.tmpdir(), 'ace-expert-sampling-'));
+const fixture = `
+import React, { useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { ExpertEditor } from '/src/components/ExpertEditor.jsx';
+import { emptyExpertForm, expertFormFromDetail } from '/src/lib/expertComponents.js';
+import { api } from '/src/lib/api.js';
+import '/src/styles/globals.css';
+api.listExpertCapabilities = async () => ({});
+api.updateExpert = async (id, payload) => {
+  window.saved = payload;
+  window.saveCount = (window.saveCount || 0) + 1;
+  return { ...payload, agents: [payload.lead], lead_agent_id: 'lead' };
+};
+function Fixture() {
+  const [version, setVersion] = useState(0);
+  const [initial, setInitial] = useState(() => ({ ...emptyExpertForm(),
+    displayName: '代码审查专家', instructions: '检查实现并说明验证结果' }));
+  return <ExpertEditor key={version} editing initial={initial} onClose={() => {}}
+    onSaved={detail => { setInitial(expertFormFromDetail(detail)); setVersion(v => v + 1); }} />;
+}
+createRoot(document.getElementById('root')).render(<Fixture />);
+`;
+const virtual = path.join(web, '__expert-sampling-fixture.jsx').replaceAll('\\', '/');
+const server = await createServer({ root: web,
+  server: { host: '127.0.0.1', port: 0, open: false, hmr: false },
+  plugins: [{ name: 'expert-sampling-fixture', enforce: 'pre',
+    resolveId(id) { return id === '/__expert-sampling-fixture.jsx' ? virtual : undefined; },
+    load(id) { return id.replaceAll('\\', '/') === virtual ? fixture : undefined; },
+    configureServer(vite) { vite.middlewares.use(async (req, res, next) => {
+      if (req.url !== '/sampling-fixture') return next();
+      res.setHeader('Content-Type', 'text/html');
+      res.end(await vite.transformIndexHtml('/sampling-fixture', '<!doctype html><html data-theme="light"><meta name="viewport" content="width=device-width, initial-scale=1"><body><div id="root"></div><script type="module" src="/__expert-sampling-fixture.jsx"></script></body></html>'));
+    }); },
+  }],
+});
+let browser;
+const errors = [];
+try {
+  await server.listen();
+  browser = await chromium.launch({ channel: 'msedge', headless: true });
+  const page = await browser.newPage({ viewport: { width: 1100, height: 900 } });
+  page.on('pageerror', error => errors.push(error.message));
+  await page.goto(`http://127.0.0.1:${server.httpServer.address().port}/sampling-fixture`);
+  const fields = ['Temperature', 'Top P', 'Top K', 'Min P'];
+  const input = label => page.getByRole('spinbutton', { name: new RegExp(`^${label}`) });
+  for (const [i, value] of ['0', '0.95', '20', '0'].entries()) await input(fields[i]).fill(value);
+  await page.getByRole('button', { name: '保存专家', exact: true }).click();
+  await page.waitForFunction(() => window.saveCount === 1);
+  assert.deepEqual(await page.evaluate(() => window.saved.sampling), { temperature: 0, top_p: 0.95, top_k: 20, min_p: 0 });
+  for (const [i, value] of ['0', '0.95', '20', '0'].entries()) assert.equal(await input(fields[i]).inputValue(), value);
+  await page.locator('[data-expert-sampling]').scrollIntoViewIfNeeded();
+  await page.screenshot({ path: path.join(output, 'desktop-light.png') });
+  await input('Top K').fill('1.5');
+  await page.getByRole('button', { name: '保存专家', exact: true }).click();
+  assert.equal(await input('Top K').getAttribute('aria-invalid'), 'true');
+  assert.equal(await page.evaluate(() => window.saveCount), 1);
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.evaluate(() => document.documentElement.dataset.theme = 'dark');
+  await page.locator('[data-expert-sampling]').scrollIntoViewIfNeeded();
+  assert.equal(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth), true);
+  for (const label of fields) {
+    const box = await input(label).boundingBox();
+    assert.ok(box.x >= 0 && box.x + box.width <= 390, `${label} stays inside narrow viewport`);
+  }
+  await page.screenshot({ path: path.join(output, 'narrow-dark-validation.png') });
+  for (const label of fields) await input(label).fill('');
+  await page.getByRole('button', { name: '保存专家', exact: true }).click();
+  await page.waitForFunction(() => window.saveCount === 2);
+  assert.deepEqual(await page.evaluate(() => window.saved.sampling), {});
+  for (const label of fields) assert.equal(await input(label).inputValue(), '');
+  assert.deepEqual(errors, []);
+  console.log(JSON.stringify({ ok: true, output, cases: ['save', 'zero', 'reopen', 'invalid', 'clear', 'narrow-dark'] }));
+} finally {
+  await browser?.close();
+  await server.close();
+}
diff --git a/web/src/components/ExpertEditor.jsx b/web/src/components/ExpertEditor.jsx
index acd1e740f..1e3bd60c4 100644
--- a/web/src/components/ExpertEditor.jsx
+++ b/web/src/components/ExpertEditor.jsx
@@ -3,6 +3,7 @@ import { api } from '../lib/api.js';
 import {
   CAPABILITY_KINDS,
   EXPERT_AVATAR_STATES,
+  EXPERT_SAMPLING_INPUTS,
   capabilityOptionsWithSaved,
   collectExpertTags,
   expertPayloadFromForm,
@@ -171,6 +172,35 @@ function BasicEditor({ form, errors, tagSuggestions, update }) {
           />
         </Field>
       )}
+      <fieldset data-expert-sampling="true" className="min-w-0 border-t border-border pt-4 lg:col-span-2">
+        <legend className="px-1 text-[14px] font-semibold text-fg">采样参数（可选）</legend>
+        <p className="mb-3 text-[12px] leading-5 text-fg-mute">
+          {isTeam
+            ? '作为团队默认值；成员自己的采样设置优先，留空的参数继承模型设置。'
+            : '留空的参数继承模型设置；发起子任务时可单独覆盖。'}
+          参数需受所用模型支持。
+        </p>
+        <div className="grid grid-cols-2 gap-3 lg:grid-cols-4">
+          {EXPERT_SAMPLING_INPUTS.map(({ field, label, range, ...constraints }) => (
+            <label key={field} className="block min-w-0 text-[12px] font-normal text-fg-2">
+              <span>{label}</span>
+              <input
+                type="number"
+                {...constraints}
+                value={form.sampling?.[field] ?? ''}
+                onChange={(event) => update('sampling', { ...form.sampling, [field]: event.target.value })}
+                placeholder="继承模型"
+                aria-invalid={!!errors.sampling?.[field]}
+                aria-describedby={`expert-sampling-${field}-hint`}
+                className={clsx(inputClass, 'mt-1.5')}
+              />
+              <span id={`expert-sampling-${field}-hint`} className={clsx('mt-1 block text-[11px]', errors.sampling?.[field] ? 'text-danger' : 'text-fg-mute')}>
+                {errors.sampling?.[field] || range}
+              </span>
+            </label>
+          ))}
+        </div>
+      </fieldset>
       <section
         data-expert-state-avatars="true"
         className="rounded-lg border border-border bg-surface p-3.5 lg:col-span-2"
diff --git a/web/src/i18n/sourceCatalog.generated.js b/web/src/i18n/sourceCatalog.generated.js
index 5dd9d84fd..cee881ca7 100644
--- a/web/src/i18n/sourceCatalog.generated.js
+++ b/web/src/i18n/sourceCatalog.generated.js
@@ -231,6 +231,7 @@ export const sourceCatalogs = {
     "s_13e0991638226a6d": "开启后，Agent 可查看窗口并操作鼠标、键盘和应用控件",
     "s_13f6a415ac664be2": "从当前 Provider 探测真实模型列表",
     "s_140b07fe3f9f7d48": "需要下载",
+    "s_1414769bed7c6551": "采样参数（可选）",
     "s_1417bae3d17d6405": "收起图像",
     "s_142cf02f83d4e7ab": "撰写回复",
     "s_14357c0d6ca270df": "请检查地址是否正确，然后重试。",
@@ -513,6 +514,7 @@ export const sourceCatalogs = {
     "s_2d1d8c1e38956bea": "后退",
     "s_2d5492fa38ef2f75": "正在建立连接",
     "s_2d55d67a4923e9fa": "不支持的目标操作",
+    "s_2d8ff2bb909846ec": "继承模型",
     "s_2da0b2a8111d771b": "打开会话",
     "s_2dd59fd0593a8e93": "路径选择器不可用",
     "s_2de0f5a9afd47152": "烧瓶",
@@ -520,6 +522,7 @@ export const sourceCatalogs = {
     "s_2df73bf9535cb691": "派遣到当前对话；开场白只会填入输入框，不会自动发送。",
     "s_2df7697dbb612878": "智能体",
     "s_2e2fc2c95a2a682c": "无匹配命令",
+    "s_2e55fd2728f3d723": "{{p0}}：请输入{{p1}}的数值，或留空继承",
     "s_2e659c0c617332d7": "读隔离生效",
     "s_2e6bfec616ad6945": "团队成员",
     "s_2e7e1c747a435c14": "（多选）",
@@ -648,6 +651,7 @@ export const sourceCatalogs = {
     "s_3a68c45441b531e0": "已归档的会话不会出现在侧栏,可随时取消归档恢复",
     "s_3a765e0fef6131d5": "模拟器控制组件缺失，请重新安装完整的 ACECode 安装包",
     "s_3a7c10115641eb4c": "在服务端文件系统里选择一个文件。",
+    "s_3ac23fa27c7b0894": "留空的参数继承模型设置；发起子任务时可单独覆盖。",
     "s_3ae030dd220465c9": "工作区用量",
     "s_3afa87e94673b0d1": "派遣失败：{{p0}}",
     "s_3b6fefc50febace4": "小时",
@@ -1080,6 +1084,7 @@ export const sourceCatalogs = {
     "s_622de9749cb55343": "加载开发者配置失败",
     "s_624b5799ebd036b0": "无工作区",
     "s_6258a2c6f9c89143": "复制全文",
+    "s_62711127c9ee73df": "大于 0，最多 1",
     "s_62731d95bc805803": "正在导出…",
     "s_6278c2f645ab3982": "公网地址",
     "s_629bb52ce0e5270f": "已将 {{p0}} 添加到聊天",
@@ -1537,6 +1542,7 @@ export const sourceCatalogs = {
     "s_89ce481a4b23d2a4": "键盘快捷键",
     "s_89d3e8892ae8fd51": "更多专家",
     "s_89db648162e7cea1": "连接中断,正在自动重试…",
+    "s_89e028004391a408": "正整数",
     "s_89e0ebd9d750f2c1": "当前后台服务不支持图像生成，请更新 ACECode 并重启后重试",
     "s_8a32f1c8f96d5905": "沙箱后端不可用:{{p0}}",
     "s_8a687fb42860ccd0": "思考深度：{{p0}}",
@@ -2293,6 +2299,7 @@ export const sourceCatalogs = {
     "s_d0ca08d604551151": "队列已暂停",
     "s_d0f680208ed8796c": "git 超时,点击重试",
     "s_d0fb5bbca8184bdd": "跳转到当前问题:{{p0}}",
+    "s_d12291a6d3a755a0": "作为团队默认值；成员自己的采样设置优先，留空的参数继承模型设置。",
     "s_d1aeba9123ecd734": "工作区目录",
     "s_d1cd931be84cce03": "信任",
     "s_d1d044826a45ef65": "加载失败",
@@ -2711,6 +2718,7 @@ export const sourceCatalogs = {
     "s_f60f6f444d92e1b1": "用法：/turn <插话内容>",
     "s_f627a3a526dc9da0": "在当前分支开始",
     "s_f628f6c3e43734b2": "清除筛选后查看全部可用组件。",
+    "s_f630012cea065bd1": "参数需受所用模型支持。",
     "s_f69273dbbebfb3a1": "格式化",
     "s_f699d16db6c37a35": "当前平台不能真正断网:关闭网络访问时只注入离线环境(代理指向无效端口、ssh 桩),不走代理的程序仍能联网。",
     "s_f6b3aadcf1df1ad2": "允许 AI 控制 {{p0}}",
@@ -3062,6 +3070,7 @@ export const sourceCatalogs = {
     "s_13e0991638226a6d": "Allow the agent to view windows and use the mouse, keyboard, and app controls",
     "s_13f6a415ac664be2": "Detect the actual model list from this provider",
     "s_140b07fe3f9f7d48": "Download size:",
+    "s_1414769bed7c6551": "Sampling parameters (optional)",
     "s_1417bae3d17d6405": "Collapse images",
     "s_142cf02f83d4e7ab": "Writing reply",
     "s_14357c0d6ca270df": "Check that the address is correct, then try again.",
@@ -3344,6 +3353,7 @@ export const sourceCatalogs = {
     "s_2d1d8c1e38956bea": "Back",
     "s_2d5492fa38ef2f75": "Establishing connection",
     "s_2d55d67a4923e9fa": "Unsupported goal action",
+    "s_2d8ff2bb909846ec": "Inherit model",
     "s_2da0b2a8111d771b": "Open session",
     "s_2dd59fd0593a8e93": "The path picker is unavailable",
     "s_2de0f5a9afd47152": "Flask",
@@ -3351,6 +3361,7 @@ export const sourceCatalogs = {
     "s_2df73bf9535cb691": "Dispatched to the current conversation; the opening line will only fill in the input box and will not be sent automatically.",
     "s_2df7697dbb612878": "agent",
     "s_2e2fc2c95a2a682c": "No matching command",
+    "s_2e55fd2728f3d723": "{{p0}}: enter a value in the range {{p1}}, or leave blank to inherit",
     "s_2e659c0c617332d7": "read isolation active",
     "s_2e6bfec616ad6945": "Team members",
     "s_2e7e1c747a435c14": "(Multi)",
@@ -3479,6 +3490,7 @@ export const sourceCatalogs = {
     "s_3a68c45441b531e0": "Archived conversations will not appear in the sidebar, and archive recovery can be canceled at any time.",
     "s_3a765e0fef6131d5": "The simulator control component is missing. Reinstall the full ACECode package.",
     "s_3a7c10115641eb4c": "Choose a file on the server filesystem.",
+    "s_3ac23fa27c7b0894": "Blank fields inherit model settings. Each subtask can override them when started.",
     "s_3ae030dd220465c9": "Work area usage",
     "s_3afa87e94673b0d1": "Dispatch failed: {{p0}}",
     "s_3b6fefc50febace4": "Hour",
@@ -3911,6 +3923,7 @@ export const sourceCatalogs = {
     "s_622de9749cb55343": "Could not load developer settings",
     "s_624b5799ebd036b0": "No workspace",
     "s_6258a2c6f9c89143": "Copy all",
+    "s_62711127c9ee73df": "Greater than 0, at most 1",
     "s_62731d95bc805803": "Exporting…",
     "s_6278c2f645ab3982": "Public address",
     "s_629bb52ce0e5270f": "Added {{p0}} to chat",
@@ -4368,6 +4381,7 @@ export const sourceCatalogs = {
     "s_89ce481a4b23d2a4": "Keyboard shortcuts",
     "s_89d3e8892ae8fd51": "More experts",
     "s_89db648162e7cea1": "Connection lost, retrying automatically…",
+    "s_89e028004391a408": "A positive integer",
     "s_89e0ebd9d750f2c1": "The current backend does not support image generation. Update ACECode, restart, and try again.",
     "s_8a32f1c8f96d5905": "Sandbox backend unavailable: {{p0}}",
     "s_8a687fb42860ccd0": "Reasoning depth: {{p0}}",
@@ -5124,6 +5138,7 @@ export const sourceCatalogs = {
     "s_d0ca08d604551151": "Queue paused",
     "s_d0f680208ed8796c": "git times out, click to try again",
     "s_d0fb5bbca8184bdd": "Jump to current question:{{p0}}",
+    "s_d12291a6d3a755a0": "Team defaults. Each member’s own sampling settings take priority. Blank fields inherit model settings.",
     "s_d1aeba9123ecd734": "Workspaces folder",
     "s_d1cd931be84cce03": "trust",
     "s_d1d044826a45ef65": "Loading failed",
@@ -5542,6 +5557,7 @@ export const sourceCatalogs = {
     "s_f60f6f444d92e1b1": "Usage: /turn <interjection>",
     "s_f627a3a526dc9da0": "Start on current branch",
     "s_f628f6c3e43734b2": "Clear filters to view all available components.",
+    "s_f630012cea065bd1": "The selected model must support these parameters.",
     "s_f69273dbbebfb3a1": "format",
     "s_f699d16db6c37a35": "This platform cannot fully cut the network: turning network access off only injects an offline environment (proxy pointed at a dead port, ssh stubs); programs that ignore the proxy can still connect.",
     "s_f6b3aadcf1df1ad2": "Allow AI control of {{p0}}",
diff --git a/web/src/lib/composerFileIntake.js b/web/src/lib/composerFileIntake.js
index 42a37d5ce..1ffdee171 100644
--- a/web/src/lib/composerFileIntake.js
+++ b/web/src/lib/composerFileIntake.js
@@ -25,7 +25,7 @@ async function storeLocalFiles(files, win) {
     for (let offset = 0; offset < bytes.length; offset += 8192) {
       binary += String.fromCharCode(...bytes.subarray(offset, offset + 8192));
     }
-    payload.push({ name: file.name || 'clipboard-file', data_base64: btoa(binary) });
+    payload.push({ name: file.name || 'clipboard_file', data_base64: btoa(binary) });
   }
   return parseNativeFilesystemItemsResult(await win.aceDesktop_storeContextFiles(payload));
 }
diff --git a/web/src/lib/composerFileTransfer.js b/web/src/lib/composerFileTransfer.js
index 3a2ec30b2..56e2e2948 100644
--- a/web/src/lib/composerFileTransfer.js
+++ b/web/src/lib/composerFileTransfer.js
@@ -1,11 +1,11 @@
 const PASTE_IMAGE_NAMES = {
-  'image/png': 'pasted-image.png',
-  'image/jpeg': 'pasted-image.jpg',
-  'image/jpg': 'pasted-image.jpg',
-  'image/webp': 'pasted-image.webp',
-  'image/gif': 'pasted-image.gif',
-  'image/bmp': 'pasted-image.bmp',
-  'image/tiff': 'pasted-image.tiff',
+  'image/png': 'pasted_image.png',
+  'image/jpeg': 'pasted_image.jpg',
+  'image/jpg': 'pasted_image.jpg',
+  'image/webp': 'pasted_image.webp',
+  'image/gif': 'pasted_image.gif',
+  'image/bmp': 'pasted_image.bmp',
+  'image/tiff': 'pasted_image.tiff',
 };
 
 const DESKTOP_SOURCE_PATH = Symbol.for('acecode.desktopSourcePath');
@@ -110,8 +110,8 @@ function listToArray(list) {
 function fallbackPasteName(file, index) {
   const type = String(file?.type || '').toLowerCase();
   if (PASTE_IMAGE_NAMES[type]) return PASTE_IMAGE_NAMES[type];
-  const suffix = index > 0 ? `-${index + 1}` : '';
-  return `pasted-attachment${suffix}`;
+  const suffix = index > 0 ? `_${index + 1}` : '';
+  return `pasted_attachment${suffix}`;
 }
 
 function ensurePasteFileName(file, index) {
diff --git a/web/src/lib/composerFileTransfer.test.js b/web/src/lib/composerFileTransfer.test.js
index 69db0e7f0..3f0def33c 100644
--- a/web/src/lib/composerFileTransfer.test.js
+++ b/web/src/lib/composerFileTransfer.test.js
@@ -81,7 +81,7 @@ run('unnamed pasted images get a stable filename when File is available', () =>
 
   const files = filesFromClipboardEvent(event);
   assert.equal(files.length, 1);
-  assert.equal(files[0].name, 'pasted-image.png');
+  assert.equal(files[0].name, 'pasted_image.png');
   assert.equal(files[0].type, 'image/png');
 });
 
@@ -154,7 +154,7 @@ const imageClipboard = await readComposerClipboardData({ read: async () => [clip
 })] });
 assert.equal(imageClipboard.files.length, 1);
 assert.equal(imageClipboard.files[0].type, 'image/png');
-assert.equal(imageClipboard.files[0].name, 'pasted-image.png');
+assert.equal(imageClipboard.files[0].name, 'pasted_image.png');
 assert.equal(await imageClipboard.files[0].text(), 'png');
 assert.equal(imageClipboard.getData('text/html'), '');
 console.log('[pass] context clipboard chooses one image representation without duplicate HTML');
diff --git a/web/src/lib/expertComponents.js b/web/src/lib/expertComponents.js
index d3bdfbb6d..22e14429b 100644
--- a/web/src/lib/expertComponents.js
+++ b/web/src/lib/expertComponents.js
@@ -1,3 +1,12 @@
+import { MODEL_SAMPLING_FIELDS, normalizeSampling, samplingDraftFields, samplingFieldValid } from './modelSettings.js';
+
+export const EXPERT_SAMPLING_INPUTS = [
+  { field: 'temperature', label: 'Temperature', range: '0–2', min: 0, max: 2, step: '0.01' },
+  { field: 'top_p', label: 'Top P', range: '大于 0，最多 1', min: 0, max: 1, step: '0.01' },
+  { field: 'top_k', label: 'Top K', range: '正整数', min: 1, max: 2147483647, step: '1' },
+  { field: 'min_p', label: 'Min P', range: '0–1', min: 0, max: 1, step: '0.01' },
+];
+
 export const EXPERT_PRIMARY_TABS = Object.freeze([
   Object.freeze({ id: 'agent', label: '专家' }),
   Object.freeze({ id: 'team', label: '专家团' }),
@@ -190,6 +199,7 @@ export function normalizeExperts(value) {
       created_at: String(item.created_at || ''),
       updated_at: String(item.updated_at || ''),
       capabilities: normalizeExpertCapabilities(item.capabilities),
+      sampling: normalizeSampling(item.sampling, 'expert.sampling'),
       agents: Array.isArray(item.agents) ? item.agents.map(normalizeAgent).filter(Boolean) : [],
       references_existing_experts: item.references_existing_experts === true,
       lead_expert_id: String(item.lead_expert_id || item.lead_agent_id || ''),
@@ -283,6 +293,7 @@ export function emptyExpertForm(type = 'agent', initialExpertId = '') {
     instructions: '',
     quickPromptsText: '',
     capabilities: {},
+    sampling: samplingDraftFields(),
     stateAvatars: {},
     stateAvatarUrls: {},
     selectedExpertIds,
@@ -311,6 +322,7 @@ export function expertFormFromDetail(expert) {
     instructions: normalized.type === 'agent' ? String(lead.instructions || '') : '',
     quickPromptsText: (normalized.quick_prompts || []).join('\n'),
     capabilities: normalizeExpertCapabilities(normalized.capabilities),
+    sampling: samplingDraftFields(normalized.sampling),
     stateAvatars: normalizeExpertStateAvatars(normalized.state_avatars),
     stateAvatarUrls: normalizeExpertStateAvatarUrls(normalized.state_avatar_urls),
     selectedExpertIds,
@@ -320,6 +332,14 @@ export function expertFormFromDetail(expert) {
 
 export function validateExpertFormFields(form, selectableExperts) {
   const errors = {};
+  const samplingErrors = {};
+  for (const { field, label, range } of EXPERT_SAMPLING_INPUTS) {
+    const raw = String(form?.sampling?.[field] ?? '').trim();
+    if (raw && !samplingFieldValid(field, Number(raw))) {
+      samplingErrors[field] = `${label}：请输入${range}的数值，或留空继承`;
+    }
+  }
+  if (Object.keys(samplingErrors).length) errors.sampling = samplingErrors;
   if (!/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(String(form?.id || ''))) {
     errors.id = '无法保存，请重新打开后再试';
   }
@@ -355,7 +375,8 @@ export function validateExpertFormFields(form, selectableExperts) {
 }
 
 export function validateExpertForm(form) {
-  return Object.values(validateExpertFormFields(form))[0] || '';
+  const first = Object.values(validateExpertFormFields(form))[0];
+  return typeof first === 'object' ? (Object.values(first)[0] || '') : (first || '');
 }
 
 function capabilitiesPayload(form) {
@@ -374,6 +395,12 @@ export function expertPayloadFromForm(form) {
     tags: normalizeStringList(form.tags),
     expertise: parseLineList(form.expertiseText),
     quick_prompts: parseLineList(form.quickPromptsText),
+    ...(Object.prototype.hasOwnProperty.call(form, 'sampling') ? {
+      sampling: Object.fromEntries(MODEL_SAMPLING_FIELDS.flatMap((field) => {
+        const raw = String(form.sampling?.[field] ?? '').trim();
+        return raw ? [[field, Number(raw)]] : [];
+      })),
+    } : {}),
     ...(stateAvatarsPresent
       ? { state_avatars: normalizeExpertStateAvatars(form.stateAvatars) }
       : {}),
diff --git a/web/src/lib/expertComponents.test.js b/web/src/lib/expertComponents.test.js
index b66141306..2c44447eb 100644
--- a/web/src/lib/expertComponents.test.js
+++ b/web/src/lib/expertComponents.test.js
@@ -33,6 +33,34 @@ import {
   validateExpertFormFields,
 } from './expertComponents.js';
 
+test('专家采样参数保存与回填保留零值，清空后明确恢复继承', () => {
+  const form = emptyExpertForm();
+  form.displayName = '采样专家';
+  form.instructions = '认真分析任务';
+  form.sampling = { temperature: '0', top_p: '0.95', top_k: '20', min_p: '0' };
+  assert.deepEqual(validateExpertFormFields(form), {});
+  const payload = expertPayloadFromForm(form);
+  assert.deepEqual(payload.sampling, { temperature: 0, top_p: 0.95, top_k: 20, min_p: 0 });
+  const loaded = expertFormFromDetail({ ...payload, agents: [payload.lead], lead_agent_id: 'lead' });
+  assert.deepEqual(loaded.sampling, form.sampling);
+  loaded.sampling = { temperature: '', top_p: ' ', top_k: '', min_p: '' };
+  assert.deepEqual(expertPayloadFromForm(loaded).sampling, {});
+});
+
+test('专家采样字段校验拒绝越界、小数 Top K 和非数字', () => {
+  const valid = { ...emptyExpertForm(), displayName: '专家', instructions: '分析' };
+  for (const [field, value] of [
+    ['temperature', '2.1'], ['temperature', 'NaN'], ['temperature', '-1'],
+    ['top_p', '0'], ['top_p', '1.1'], ['top_k', '1.5'],
+    ['top_k', '2147483648'], ['min_p', '-0.1'],
+  ]) {
+    const errors = validateExpertFormFields({ ...valid, sampling: { [field]: value } });
+    assert.ok(errors.sampling?.[field], `${field}=${value}`);
+  }
+  const team = { ...emptyExpertForm('team'), sampling: { temperature: '0.5' } };
+  assert.deepEqual(expertPayloadFromForm(team).sampling, { temperature: 0.5 });
+});
+
 function test(name, fn) {
   try {
     fn();
@@ -181,6 +209,7 @@ test('expert payload keeps Tags, expertise, prompts and optional scopes separate
     tags: ['开发', 'OPC-一人公司'],
     expertise: ['架构设计', '代码质量'],
     quick_prompts: ['审查当前改动', '给出重构建议'],
+    sampling: {},
     state_avatars: {},
     capabilities: {
       skills: ['code-review'],
@@ -366,6 +395,7 @@ test('expert team payload references selected existing experts and one lead', ()
     tags: ['项目质量'],
     expertise: ['需求拆解', '体验验收'],
     quick_prompts: ['推进这个需求'],
+    sampling: {},
     state_avatars: {},
     lead_expert_id: 'reviewer',
     member_expert_ids: ['tester'],
diff --git a/web/src/lib/iosSimulator.js b/web/src/lib/iosSimulator.js
index 3f045db59..4774aaabf 100644
--- a/web/src/lib/iosSimulator.js
+++ b/web/src/lib/iosSimulator.js
@@ -438,11 +438,11 @@ export function simulatorNeedsSettings({ status = null, message = '' } = {}) {
 }
 
 export function simulatorScreenshotFilename(name = '', date = new Date()) {
-  const safe = String(name || 'simulator').replace(/[\\/:*?"<>|\s]+/g, '-').replace(/^-+|-+$/g, '') || 'simulator';
+  const safe = String(name || 'simulator').replace(/[-\\/:*?"<>|\s]+/g, '_').replace(/^_+|_+$/g, '') || 'simulator';
   const pad = (value) => String(value).padStart(2, '0');
   const stamp = `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}`
-    + `-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
-  return `${safe}-${stamp}.png`;
+    + `_${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+  return `${safe}_${stamp}.png`;
 }
 
 export function downloadSimulatorBlob(blob, filename, {
diff --git a/web/src/lib/iosSimulator.test.js b/web/src/lib/iosSimulator.test.js
index fe8be3ea8..ea81021f6 100644
--- a/web/src/lib/iosSimulator.test.js
+++ b/web/src/lib/iosSimulator.test.js
@@ -336,9 +336,9 @@ run('panel copy helpers', () => {
   assert.equal(simulatorNeedsSettings({ message: 'device is not booted' }), false);
   assert.equal(
     simulatorScreenshotFilename('iPhone 17 Pro', new Date(2026, 9, 16, 8, 5, 9)),
-    'iPhone-17-Pro-20261016-080509.png',
+    'iPhone_17_Pro_20261016_080509.png',
   );
-  assert.equal(simulatorScreenshotFilename('', new Date(2026, 0, 2, 3, 4, 5)), 'simulator-20260102-030405.png');
+  assert.equal(simulatorScreenshotFilename('', new Date(2026, 0, 2, 3, 4, 5)), 'simulator_20260102_030405.png');
 });
 
 run('screenshot downloads go through a temporary object URL', () => {
diff --git a/web/src/lib/mermaidExport.js b/web/src/lib/mermaidExport.js
index ab3a28883..a1754b169 100644
--- a/web/src/lib/mermaidExport.js
+++ b/web/src/lib/mermaidExport.js
@@ -97,7 +97,7 @@ export function mermaidFamilyFromSource(source) {
 export function mermaidExportFilename(detail, format) {
   const family = mermaidFamilyFromSource(detail?.source);
   const extension = format === 'source' ? 'mmd' : String(format || '').toLowerCase();
-  return `mermaid-${family}.${extension || 'txt'}`;
+  return `mermaid_${family.replace(/-/g, '_')}.${extension || 'txt'}`;
 }
 
 export function mermaidPngDimensions(width, height, {
diff --git a/web/src/lib/mermaidExport.test.js b/web/src/lib/mermaidExport.test.js
index 2929edfd6..d0cebbd3c 100644
--- a/web/src/lib/mermaidExport.test.js
+++ b/web/src/lib/mermaidExport.test.js
@@ -113,9 +113,9 @@ await test('Mermaid families produce deterministic export filenames', () => {
   ];
   for (const [source, family] of cases) {
     assert.equal(mermaidFamilyFromSource(source), family);
-    assert.equal(mermaidExportFilename({ source }, 'svg'), `mermaid-${family}.svg`);
+    assert.equal(mermaidExportFilename({ source }, 'svg'), `mermaid_${family}.svg`);
   }
-  assert.equal(mermaidExportFilename(detail, 'source'), 'mermaid-flowchart.mmd');
+  assert.equal(mermaidExportFilename(detail, 'source'), 'mermaid_flowchart.mmd');
 });
 
 await test('PNG dimensions prefer 2x but obey dimension and pixel caps', () => {
@@ -131,14 +131,14 @@ await test('PNG dimensions prefer 2x but obey dimension and pixel caps', () => {
 await test('SVG and source export download exact retained artifacts and revoke URLs', async () => {
   const svgHarness = downloadHarness();
   const svgResult = exportMermaidSvg(detail, { BlobType: Blob, ...svgHarness.options });
-  assert.deepEqual(svgResult, { ok: true, filename: 'mermaid-flowchart.svg' });
-  assert.equal(svgHarness.anchors[0].download, 'mermaid-flowchart.svg');
+  assert.deepEqual(svgResult, { ok: true, filename: 'mermaid_flowchart.svg' });
+  assert.equal(svgHarness.anchors[0].download, 'mermaid_flowchart.svg');
   assert.equal(await svgHarness.blobs.get(svgHarness.anchors[0].href).text(), detail.svg);
   assert.deepEqual(svgHarness.revoked, [svgHarness.anchors[0].href]);
 
   const sourceHarness = downloadHarness();
   const sourceResult = exportMermaidSource(detail, { BlobType: Blob, ...sourceHarness.options });
-  assert.deepEqual(sourceResult, { ok: true, filename: 'mermaid-flowchart.mmd' });
+  assert.deepEqual(sourceResult, { ok: true, filename: 'mermaid_flowchart.mmd' });
   assert.equal(await sourceHarness.blobs.get(sourceHarness.anchors[0].href).text(), detail.source);
   assert.deepEqual(sourceHarness.revoked, [sourceHarness.anchors[0].href]);
 });
@@ -198,7 +198,7 @@ await test('PNG export paints the theme, downloads 2x output, and cleans both UR
     ImageType: FakeImage,
     ...harness.options,
   });
-  assert.deepEqual(result, { ok: true, filename: 'mermaid-flowchart.png' });
+  assert.deepEqual(result, { ok: true, filename: 'mermaid_flowchart.png' });
   assert.equal(canvas.width, 320);
   assert.equal(canvas.height, 160);
   assert.deepEqual(drawCalls[0], ['fill', '#333333', 0, 0, 320, 160]);
diff --git a/web/src/lib/modelSettings.js b/web/src/lib/modelSettings.js
index 29b1e14d6..51c7b453e 100644
--- a/web/src/lib/modelSettings.js
+++ b/web/src/lib/modelSettings.js
@@ -398,7 +398,7 @@ export function normalizeProviderModelQuery(payload, expectedProviderId = '') {
   };
 }
 
-function normalizeSampling(value, label) {
+export function normalizeSampling(value, label) {
   if (value === undefined || value === null) return {};
   const object = requireObject(value, label);
   const output = {};
@@ -415,7 +415,7 @@ function normalizeSampling(value, label) {
   return output;
 }
 
-function samplingDraftFields(sampling = {}) {
+export function samplingDraftFields(sampling = {}) {
   return Object.fromEntries(MODEL_SAMPLING_FIELDS.map((field) => [
     field,
     typeof sampling?.[field] === 'number' ? String(sampling[field]) : '',
@@ -914,7 +914,7 @@ export function modelSamplingFieldSupport(draft, provider) {
   return { temperature: true, top_p: true, top_k: true, min_p: true };
 }
 
-function samplingFieldValid(field, value, provider) {
+export function samplingFieldValid(field, value, provider) {
   if (!Number.isFinite(value)) return false;
   switch (field) {
     case 'temperature':
diff --git a/web/src/lib/pastedText.js b/web/src/lib/pastedText.js
index ad2a9445a..08434e49a 100644
--- a/web/src/lib/pastedText.js
+++ b/web/src/lib/pastedText.js
@@ -468,14 +468,14 @@ let lastFileStamp = '';
 let fileStampSerial = 0;
 const pad = (value, width = 2) => String(value).padStart(width, '0');
 
-// pasted-text-YYYYMMDD-HHMMSS[_s][-k].txt:ASCII、同一页面内唯一。
+// pasted_text_YYYYMMDD_HHMMSS[_s][_k].txt:ASCII、同一页面内唯一。
 // 同一秒内的第二次粘贴加 _2、_3…(否则 composerFileIdentity 会把两次相同粘贴去重);
 // 多段时 index 为 1..n 的段号,单段传 0。一次粘贴的各段须传同一个 now,且从
 // index 0 或 1 开始按顺序调用(index <= 1 视为新的一次粘贴)。
 export function pastedTextFileName(now = new Date(), index = 0) {
   const date = now instanceof Date ? now : new Date(now);
   const stamp = `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}`
-    + `-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+    + `_${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
   if (index <= 1) {
     if (stamp === lastFileStamp) fileStampSerial += 1;
     else {
@@ -484,8 +484,8 @@ export function pastedTextFileName(now = new Date(), index = 0) {
     }
   }
   const serial = fileStampSerial > 1 ? `_${fileStampSerial}` : '';
-  const chunk = index > 0 ? `-${index}` : '';
-  return `pasted-text-${stamp}${serial}${chunk}.txt`;
+  const chunk = index > 0 ? `_${index}` : '';
+  return `pasted_text_${stamp}${serial}${chunk}.txt`;
 }
 
 // 上传请求体里的来源描述,服务端存进附件记录 metadata(origin / pasted_text)。
diff --git a/web/src/lib/pastedText.test.js b/web/src/lib/pastedText.test.js
index 193a9cc7d..527c0bd3b 100644
--- a/web/src/lib/pastedText.test.js
+++ b/web/src/lib/pastedText.test.js
@@ -124,11 +124,11 @@ run('pasted file names are ASCII and unique', () => {
   const now = new Date(2026, 8, 24, 10, 15, 0);
   const first = pastedTextFileName(now, 0);
   const second = pastedTextFileName(now, 0);
-  assert.equal(first, 'pasted-text-20260924-101500.txt');
+  assert.equal(first, 'pasted_text_20260924_101500.txt');
   assert.notEqual(first, second);
   const chunk1 = pastedTextFileName(now, 1);
   const chunk2 = pastedTextFileName(now, 2);
-  assert.ok(chunk1.endsWith('-1.txt') && chunk2.endsWith('-2.txt'));
+  assert.ok(chunk1.endsWith('_1.txt') && chunk2.endsWith('_2.txt'));
   assert.equal(chunk1.slice(0, -6), chunk2.slice(0, -6));
   assert.ok(new Set([first, second, chunk1, chunk2]).size === 4);
   for (const name of [first, second, chunk1, chunk2]) assert.match(name, /^[\x20-\x7e]+$/);
diff --git a/web/src/lib/securityCenter.js b/web/src/lib/securityCenter.js
index a65a393df..d95089cbe 100644
--- a/web/src/lib/securityCenter.js
+++ b/web/src/lib/securityCenter.js
@@ -462,8 +462,8 @@ export function auditSummaryCounts(summary) {
 // 导出文件名跟着后端的 Content-Disposition 走,拿不到就自己拼一个。
 export function auditExportFilename(format, now = new Date()) {
   const pad = (value) => String(value).padStart(2, '0');
-  const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
-  return `acecode-audit-${stamp}.${format === 'csv' ? 'csv' : 'jsonl'}`;
+  const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}_${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+  return `acecode_audit_${stamp}.${format === 'csv' ? 'csv' : 'jsonl'}`;
 }
 
 // ---------------------------------------------------------------------------
diff --git a/web/src/lib/securityCenter.test.js b/web/src/lib/securityCenter.test.js
index 7b41b7f8d..cde74fe9e 100644
--- a/web/src/lib/securityCenter.test.js
+++ b/web/src/lib/securityCenter.test.js
@@ -194,8 +194,8 @@ import {
   assert.deepEqual(auditSummaryCounts({ total: 9, by_decision: { allow: 4, allow_session: 1, deny: 2, forbidden: 1, blocked: 1 } }),
     { total: 9, allowed: 5, denied: 3, blocked: 1 });
   assert.deepEqual(auditSummaryCounts(null), { total: 0, allowed: 0, denied: 0, blocked: 0 });
-  assert.equal(auditExportFilename('csv', new Date(2026, 8, 17, 9, 5, 3)), 'acecode-audit-20260917-090503.csv');
-  assert.equal(auditExportFilename('jsonl', new Date(2026, 0, 1, 0, 0, 0)), 'acecode-audit-20260101-000000.jsonl');
+  assert.equal(auditExportFilename('csv', new Date(2026, 8, 17, 9, 5, 3)), 'acecode_audit_20260917_090503.csv');
+  assert.equal(auditExportFilename('jsonl', new Date(2026, 0, 1, 0, 0, 0)), 'acecode_audit_20260101_000000.jsonl');
 }
 
 // 场景:错误码归一。期望:404 → 不支持,401 → 认证,503+AUDIT_UNAVAILABLE 保留,