fix: resolve workspace lint and regression test failures

Share provider DNS policy across WebSocket and connection probes, handle bracketed IPv6 literals, and preserve bounded address sets for outbound clients.

Bound SMTP DNS and TCP setup with multi-address fallback. Add opt-in trusted proxy DNS for tunnel upstreams while retaining default IP ACLs and origin isolation.

Document DNS policy boundaries and verify 809 gateway, tunnel, and HTTP regression tests.

.dockerignore

@@ -1,23 +1,18 @@
-# Python
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-env/
-venv/
-ENV/
-.venv
-.uv/
-*.egg-info/
-dist/
+# Build artifacts
 build/
+target/
+*.so
 *.egg
+*.egg-info/
 
 # Frontend
 frontend/node_modules/
+frontend/dist/
 frontend/.vite/
-# frontend/dist/ - 注释掉，因为我们需要预构建的dist文件
+aether-vscodex/web/node_modules/
+aether-vscodex/web/dist/
+aether-vscodex/vscode-extension/node_modules/
+aether-vscodex/vscode-extension/dist/
 
 # Development
 .git/
@@ -59,4 +54,4 @@ Dockerfile.*
 
 # Deployment
 deploy/
-scripts/
+scripts/

.env.example

@@ -1,19 +1,52 @@
 # ==================== 必须配置（启动前） ====================
 # 以下配置项必须在项目启动前设置
 
-# 数据库配置
+# 应用端口（默认 8084）
+APP_PORT=8084
+
+# 对外访问地址，用于一键安装、CC Switch 导入、支付回调等需要生成公网 URL 的场景。
+# 生产环境建议显式配置为不带内部端口的公网域名，例如 https://aether.example.com
+# AETHER_PUBLIC_BASE_URL=https://aether.example.com
+
+# Docker Compose 镜像（默认正式版 latest；提前测试可改 rc/beta；也可固定具体版本）
+# 示例:
+# APP_IMAGE=ghcr.io/fawney19/aether:latest
+# APP_IMAGE=ghcr.io/fawney19/aether:rc
+# APP_IMAGE=ghcr.io/fawney19/aether:beta
+# APP_IMAGE=ghcr.io/fawney19/aether:0.7.0-rc.1
+
+# API Key 前缀（默认 sk）
+API_KEY_PREFIX=sk
+
+# Rust 日志过滤（默认 aether_gateway=info）
+# 示例: aether_gateway=debug,sqlx=warn
+RUST_LOG=aether_gateway=info
+
+# CORS 配置（跨域带 Cookie 时不要写 *，必须显式列出前端源）
+# 示例: http://localhost:5173,https://app.example.com
+# CORS_ORIGINS=http://localhost:5173
+# CORS_ALLOW_CREDENTIALS=true
+# 登录刷新 Cookie 对同源浏览器请求和可信反代自动适配 HTTP/HTTPS。
+# HTTP 自动使用兼容的 SameSite=Lax（显式 Strict 保留）；HTTPS 保留原有 SameSite 配置。
+# 无法确认访问协议时保留安全默认值；HTTPS 反代请正确传递 X-Forwarded-Proto。
+# AUTH_REFRESH_COOKIE_SECURE 可显式覆盖自动判断，公网部署仍建议使用 HTTPS。
+# 如果前后端跨站并依赖登录刷新 Cookie，必须使用 HTTPS，并配合：
+# AUTH_REFRESH_COOKIE_SAMESITE=None
+# AUTH_REFRESH_COOKIE_SECURE=true
+
+# 数据库配置（仅支持 PostgreSQL）
 DB_HOST=localhost
 DB_PORT=5432
 DB_USER=postgres
 DB_NAME=aether
-DB_PASSWORD=your_secure_password_here
+DB_PASSWORD=
 
 # Redis 配置
 REDIS_HOST=localhost
 REDIS_PORT=6379
-REDIS_PASSWORD=your_redis_password_here
+REDIS_PASSWORD=
 
-# JWT密钥（使用 python generate_keys.py 生成）
+# JWT密钥（使用 ./generate_keys.sh 生成）
 # 用于用户登录 token 签名，更换后所有用户需重新登录
 JWT_SECRET_KEY=change-this-to-a-secure-random-string
 
@@ -21,47 +54,80 @@ JWT_SECRET_KEY=change-this-to-a-secure-random-string
 # 注意：更换此密钥后需要在管理面板重新配置所有 Provider API Key
 ENCRYPTION_KEY=change-this-to-another-secure-random-string
 
-# 代理节点 HMAC 密钥（用于 aether-proxy 认证）
-# 可选：不设置时会从 ENCRYPTION_KEY 自动派生
-# 显式设置时，aether-proxy.toml 的 hmac_key 配置相同值即可
-# 可通过 python generate_keys.py 生成
-# PROXY_HMAC_KEY=change-this-to-a-proxy-hmac-key
+# S3 备份的独立加密密钥（推荐）。未配置时为兼容旧部署，会回退到 ENCRYPTION_KEY。
+# 密钥轮换前必须保留旧值，离线恢复工具需要它解密历史备份。
+# AETHER_BACKUP_ENCRYPTION_KEY=change-this-to-a-dedicated-secure-random-string
 
-# 管理员账号（仅首次初始化时使用, 创建完成后可在系统内修改密码）
+# 启动自举管理员（仅在当前库里还没有活动管理员时生效）
+# 首次启动前必须设置 ADMIN_PASSWORD；install.sh 首次生成配置时会提示输入。
 ADMIN_EMAIL=[email protected]
-ADMIN_USERNAME=admin
-ADMIN_PASSWORD=admin123456
+ADMIN_USERNAME=admin123456
+# ADMIN_PASSWORD=
 
 # ==================== 可选配置（有默认值） ====================
-# 以下配置项有合理的默认值，可按需调整
 
-# 应用端口（默认 8084）
-# APP_PORT=8084
+# 可信反向代理 IP/CIDR，只有这些来源发送的 X-Real-IP / X-Forwarded-For 会被采用。
+# 默认仅信任本机回环代理：127.0.0.0/8,::1/128。
+# Docker/Nginx 位于独立容器时，请按实际容器网络设置，例如：172.16.0.0/12。
+# AETHER_TRUSTED_PROXY_CIDRS=127.0.0.0/8,::1/128,172.16.0.0/12
 
-# Gunicorn Worker 数量（默认 4）
-# 建议最小设置为 2
-# GUNICORN_WORKERS=4
+# VS Code Codex 云端协同（仅在叠加 aether-vscodex/docker-compose.aether.yml 时需要）
+# 内部 token 至少 24 字节，建议使用：openssl rand -base64 32
+# AETHER_VSCODEX_INTERNAL_TOKEN=replace-with-a-long-random-secret
+# AETHER_VSCODEX_PUBLIC_WS_URL=wss://aether.example.com/api/vscodex/ws
+# AETHER_VSCODEX_ALLOWED_ORIGINS=https://aether.example.com
 
-# Gunicorn Max Requests（默认 4000）
-# Worker 处理指定数量请求后自动重启，防止内存泄漏
-# max-requests-jitter 会自动设置为 MAX_REQUESTS/20 (5%)
-# MAX_REQUESTS=4000
+# 启动时的数据库准备策略：auto（默认）或 verify-only
+# AETHER_GATEWAY_DATABASE_MODE=auto
 
-# API Key 前缀（默认 sk）
-# API_KEY_PREFIX=sk
+# PostgreSQL 连接池配置（默认每核 4 条、总池至少 32 条且最多 100 条；多实例部署应显式分配每实例预算）
+# AETHER_GATEWAY_DATA_POSTGRES_MIN_CONNECTIONS=12
+# AETHER_GATEWAY_DATA_POSTGRES_MAX_CONNECTIONS=80
+# AETHER_GATEWAY_MAX_IN_FLIGHT_REQUESTS=2048
+# AETHER_GATEWAY_REQUEST_BODY_BUFFER_BUDGET_MB=256
+# 请求体完整读取总超时默认关闭；确需限制时配置 1000-600000 毫秒的非零值。
+# AETHER_GATEWAY_REQUEST_BODY_READ_TIMEOUT_MS=0
+# 单请求解压后 Payload 上限（MiB），默认 256；显式设为 0 才表示不限制。
+# AETHER_MAX_REQUEST_BODY_MB=256
+# AETHER_GATEWAY_SECURITY_CACHE_TTL_MS=1000
+# AETHER_MAX_REDACTED_SYNC_RESPONSE_BODY_MB=64
+# AETHER_MAX_INTERNAL_BUFFERED_BODY_MB=64
+# AETHER_TUNNEL_NODE_STATUS_QUEUE_CAPACITY=1024
+# Tunnel relay 使用的独立 HMAC 密钥。启用 HTTP tunnel relay 或多网关 owner 转发时必须配置，
+# 所有网关实例必须使用同一个至少 32 字节的随机值；不要复用 JWT 或数据加密密钥。
+# AETHER_TUNNEL_RELAY_AUTH_SECRET=
+# 旧版 /api/internal/gateway/* 控制面默认关闭。确需独立服务调用时，配置至少 32 字节的
+# 独立 HMAC 密钥；不要复用 JWT、数据加密或 tunnel relay 密钥。多节点必须使用相同值和共享 Redis。
+# AETHER_INTERNAL_GATEWAY_AUTH_SECRET=
+# 远程 relay 地址必须使用 HTTPS；HTTP 仅允许 localhost 或回环 IP。
+# AETHER_TUNNEL_RELAY_BASE_URL=https://gateway-a.example.com
+# 跨网关 relay 解析到受控私有地址时才显式开启；默认关闭以防止被篡改的 attachment
+# 记录诱导网关向内网转发 relay 凭据。该开关不放宽普通 provider 的目标地址策略。
+# AETHER_TUNNEL_RELAY_ALLOW_PRIVATE_TARGETS=false
+# 更推荐按 relay 主机名精确放行私网部署（逗号分隔，大小写不敏感）；不支持通配符/后缀。
+# AETHER_TUNNEL_RELAY_PRIVATE_HOST_ALLOWLIST=gateway-a.internal,gateway-b.internal
+# Bark 自建服务默认仅允许公网 HTTPS。确需明文 HTTP 或内网目标时分别显式开启：
+# AETHER_BARK_ALLOW_HTTP=false
+# AETHER_BARK_ALLOW_PRIVATE_TARGETS=false
 
-# 日志级别（默认 INFO，可选：DEBUG, INFO, WARNING, ERROR）
-# LOG_LEVEL=INFO
+# 普通 Provider 反代（包括 Provider OAuth）不按 DNS 地址过滤上游，兼容任意
+# Fake-IP 域名及内网 DNS。仅信任管理员配置的上游；没有严格 DNS 过滤开关。
+# URL 协议、字面 IP、TLS 证书，以及隧道中继和登录 OAuth 的校验仍保留。
 
-# CORS 配置（允许跨域的源，多个源用逗号分隔）
-# 示例: http://localhost:3000,https://example.com
-# 默认: * (允许所有源)
-# CORS_ORIGINS=*
+# 可选 Provider OAuth 客户端。Gemini CLI 和 Antigravity 默认使用内置 native-app
+# 客户端凭据；自定义 client ID 时必须同时配置对应的 client secret。
+# 显式配置的 client secret 优先于默认值。
+# AETHER_GEMINI_CLI_OAUTH_CLIENT_ID=
+# AETHER_GEMINI_CLI_OAUTH_CLIENT_SECRET=
+# AETHER_ANTIGRAVITY_OAUTH_CLIENT_ID=
+# AETHER_ANTIGRAVITY_OAUTH_CLIENT_SECRET=
 
-# ==================== 计费系统（可选） ====================
-# Video/Image/Audio 缺失 billing_rule 时是否拒绝请求（默认 false：允许请求但 cost=0 并告警）
-# BILLING_REQUIRE_RULE=false
-#
-# required 维度缺失时是否拒绝请求/标记任务失败（默认 false：cost=0 + 标记 incomplete）
-# BILLING_STRICT_MODE=false
-#
+# PostgreSQL 容器调优：docker-compose.yml 已内置通用默认值，通常不用配置。
+# 只有在 Postgres 独占大内存、或压测显示 DB 缓存/排序/维护任务成为瓶颈时再覆盖。
+# 内置默认：shared_buffers=1GB, effective_cache_size=3GB, shm_size=512mb,
+# work_mem=16MB, maintenance_work_mem=256MB。
+# POSTGRES_SHARED_BUFFERS=8GB
+# POSTGRES_EFFECTIVE_CACHE_SIZE=24GB
+# POSTGRES_SHM_SIZE=2gb
+# POSTGRES_WORK_MEM=16MB
+# POSTGRES_MAINTENANCE_WORK_MEM=1GB

.github/workflows/build-proxy.yml

@@ -1,227 +0,0 @@
-name: Build aether-proxy
-
-on:
-  push:
-    tags: ['proxy-v*']
-  workflow_dispatch:
-
-permissions:
-  contents: write
-  packages: write
-
-env:
-  REGISTRY: ghcr.io
-  GHCR_IMAGE: fawney19/aether-proxy
-  DOCKERHUB_IMAGE: fawney19/aether-proxy
-
-jobs:
-  build:
-    name: ${{ matrix.name }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - name: linux-amd64
-            target: x86_64-unknown-linux-gnu
-            os: ubuntu-latest
-            use_cross: true
-          - name: linux-arm64
-            target: aarch64-unknown-linux-gnu
-            os: ubuntu-latest
-            use_cross: true
-          - name: macos-amd64
-            target: x86_64-apple-darwin
-            os: macos-latest
-            use_cross: false
-          - name: macos-arm64
-            target: aarch64-apple-darwin
-            os: macos-latest
-            use_cross: false
-          - name: windows-amd64
-            target: x86_64-pc-windows-msvc
-            os: windows-latest
-            use_cross: false
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@stable
-        with:
-          targets: ${{ matrix.target }}
-
-      - name: Rust cache
-        uses: Swatinem/rust-cache@v2
-        with:
-          workspaces: aether-proxy -> target
-          key: ${{ matrix.target }}
-
-      - name: Install cross
-        if: matrix.use_cross
-        uses: taiki-e/install-action@cross
-
-      - name: Build
-        working-directory: aether-proxy
-        shell: bash
-        run: |
-          if [ "${{ matrix.use_cross }}" = "true" ]; then
-            cross build --release --target ${{ matrix.target }}
-          else
-            cargo build --release --target ${{ matrix.target }}
-          fi
-
-      - name: Package (Unix)
-        if: runner.os != 'Windows'
-        shell: bash
-        run: |
-          cd aether-proxy/target/${{ matrix.target }}/release
-          chmod +x aether-proxy
-          tar czf ../../../../aether-proxy-${{ matrix.name }}.tar.gz aether-proxy
-
-      - name: Package (Windows)
-        if: runner.os == 'Windows'
-        shell: bash
-        run: |
-          cd aether-proxy/target/${{ matrix.target }}/release
-          7z a ../../../../aether-proxy-${{ matrix.name }}.zip aether-proxy.exe
-
-      - name: Upload artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: aether-proxy-${{ matrix.name }}
-          path: |
-            aether-proxy-*.tar.gz
-            aether-proxy-*.zip
-          if-no-files-found: error
-
-  release:
-    needs: build
-    runs-on: ubuntu-latest
-    if: startsWith(github.ref, 'refs/tags/')
-    steps:
-      - name: Download all artifacts
-        uses: actions/download-artifact@v4
-        with:
-          merge-multiple: true
-          path: artifacts
-
-      - name: Generate checksums
-        working-directory: artifacts
-        run: sha256sum aether-proxy-* > SHA256SUMS.txt
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
-        with:
-          name: "aether-proxy ${{ github.ref_name }}"
-          generate_release_notes: true
-          files: |
-            artifacts/aether-proxy-*
-            artifacts/SHA256SUMS.txt
-          fail_on_unmatched_files: true
-
-  docker:
-    needs: build
-    runs-on: ubuntu-latest
-    if: startsWith(github.ref, 'refs/tags/')
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Download Linux artifacts
-        uses: actions/download-artifact@v4
-        with:
-          pattern: aether-proxy-linux-*
-          merge-multiple: true
-          path: artifacts
-
-      - name: Prepare binaries
-        run: |
-          mkdir -p aether-proxy/build/linux-amd64 aether-proxy/build/linux-arm64
-          tar xzf artifacts/aether-proxy-linux-amd64.tar.gz -C aether-proxy/build/linux-amd64
-          tar xzf artifacts/aether-proxy-linux-arm64.tar.gz -C aether-proxy/build/linux-arm64
-
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Log in to GHCR
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: |
-            ${{ env.REGISTRY }}/${{ env.GHCR_IMAGE }}
-            docker.io/${{ env.DOCKERHUB_IMAGE }}
-          tags: |
-            type=match,pattern=proxy-v(.*),group=1
-            type=match,pattern=proxy-v(\d+\.\d+),group=1
-            type=sha,prefix=
-          flavor: |
-            latest=auto
-
-      - name: Build and push
-        uses: docker/build-push-action@v5
-        with:
-          context: ./aether-proxy
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          platforms: linux/amd64,linux/arm64
-
-  update-readme:
-    needs: release
-    runs-on: ubuntu-latest
-    if: startsWith(github.ref, 'refs/tags/')
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          ref: master
-
-      - name: Update README download links
-        env:
-          TAG: ${{ github.ref_name }}
-        run: |
-          VERSION="${TAG#proxy-v}"
-          BASE="https://github.com/fawney19/Aether/releases/download/${TAG}"
-          cd aether-proxy
-
-          TABLE="| Platform | Download |\n|----------|----------|\n"
-          TABLE+="| Linux x86_64 | [aether-proxy-linux-amd64.tar.gz](${BASE}/aether-proxy-linux-amd64.tar.gz) |\n"
-          TABLE+="| Linux ARM64 | [aether-proxy-linux-arm64.tar.gz](${BASE}/aether-proxy-linux-arm64.tar.gz) |\n"
-          TABLE+="| macOS x86_64 | [aether-proxy-macos-amd64.tar.gz](${BASE}/aether-proxy-macos-amd64.tar.gz) |\n"
-          TABLE+="| macOS ARM64 | [aether-proxy-macos-arm64.tar.gz](${BASE}/aether-proxy-macos-arm64.tar.gz) |\n"
-          TABLE+="| Windows x86_64 | [aether-proxy-windows-amd64.zip](${BASE}/aether-proxy-windows-amd64.zip) |"
-
-          # Replace content between markers
-          if grep -q '<!-- DOWNLOAD_TABLE_START -->' README.md; then
-            awk -v table="$TABLE" '
-              /<!-- DOWNLOAD_TABLE_START -->/ { print; printf "%s\n", table; skip=1; next }
-              /<!-- DOWNLOAD_TABLE_END -->/ { skip=0 }
-              !skip { print }
-            ' README.md > README.tmp && mv README.tmp README.md
-          fi
-
-      - name: Commit and push
-        run: |
-          cd aether-proxy
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add README.md
-          git diff --cached --quiet && exit 0
-          TAG="${GITHUB_REF#refs/tags/}"
-          git commit -m "chore(proxy): update download links for ${TAG}"
-          git push

.github/workflows/build-tunnel.yml

@@ -0,0 +1,263 @@
+name: Build aether-tunnel
+
+on:
+  push:
+    tags: ['tunnel-v*']
+  workflow_dispatch:
+
+permissions:
+  actions: read
+  contents: read
+
+concurrency:
+  group: build-tunnel-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Ensure tunnel tag matches Cargo version
+        shell: bash
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          EXPECTED="${TAG#tunnel-v}"
+          ACTUAL="$(cargo metadata --manifest-path apps/aether-tunnel/Cargo.toml --locked --no-deps --format-version 1 | jq -r '.packages[] | select(.name == "aether-tunnel") | .version')"
+
+          echo "tag version:   ${EXPECTED}"
+          echo "cargo version: ${ACTUAL}"
+
+          if [ -z "${ACTUAL}" ]; then
+            echo "Could not resolve aether-tunnel package version" >&2
+            exit 1
+          fi
+
+          if [ "${EXPECTED}" != "${ACTUAL}" ]; then
+            echo "tunnel tag ${TAG} does not match apps/aether-tunnel/Cargo.toml version ${ACTUAL}" >&2
+            exit 1
+          fi
+
+  build:
+    needs: preflight
+    if: always() && (needs.preflight.result == 'success' || needs.preflight.result == 'skipped')
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: linux-amd64
+            target: x86_64-unknown-linux-gnu
+            os: ubuntu-latest
+            use_cross: true
+          - name: linux-arm64
+            target: aarch64-unknown-linux-gnu
+            os: ubuntu-latest
+            use_cross: true
+          - name: linux-musl-amd64
+            target: x86_64-unknown-linux-musl
+            os: ubuntu-latest
+            use_cross: true
+          - name: linux-musl-arm64
+            target: aarch64-unknown-linux-musl
+            os: ubuntu-latest
+            use_cross: true
+          - name: macos-amd64
+            target: x86_64-apple-darwin
+            os: macos-15-intel
+            use_cross: false
+          - name: macos-arm64
+            target: aarch64-apple-darwin
+            os: macos-15
+            use_cross: false
+          - name: windows-amd64
+            target: x86_64-pc-windows-msvc
+            os: windows-latest
+            use_cross: false
+
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Ensure Rust target is installed
+        run: rustup target add ${{ matrix.target }}
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@49a0bdc70d2e1b713ca9e2869b211fcce03d3c1c # v2
+        with:
+          workspaces: apps/aether-tunnel -> target
+          key: ${{ matrix.target }}
+
+      - name: Install cross
+        if: matrix.use_cross
+        uses: taiki-e/install-action@1ae7257be536a92d9218a6b343dc6e6ba650f7e1 # cross
+
+      - name: Build
+        working-directory: apps/aether-tunnel
+        shell: bash
+        run: |
+          if [ "${{ matrix.use_cross }}" = "true" ]; then
+            cross build --release --locked --target ${{ matrix.target }}
+          else
+            cargo build --release --locked --target ${{ matrix.target }}
+          fi
+
+      - name: Package (Unix)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          cd target/${{ matrix.target }}/release
+          chmod +x aether-tunnel
+          tar czf ../../../aether-tunnel-${{ matrix.name }}.tar.gz aether-tunnel
+
+      - name: Package (Windows)
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          cd target/${{ matrix.target }}/release
+          7z a ../../../aether-tunnel-${{ matrix.name }}.zip aether-tunnel.exe
+          tar czf ../../../aether-tunnel-${{ matrix.name }}.tar.gz aether-tunnel.exe
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: aether-tunnel-${{ matrix.name }}
+          path: |
+            aether-tunnel-*.tar.gz
+            aether-tunnel-*.zip
+          if-no-files-found: error
+          retention-days: 1
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      actions: read
+      attestations: write
+      contents: write
+      id-token: write
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          merge-multiple: true
+          path: artifacts
+
+      - name: Generate checksums
+        working-directory: artifacts
+        run: sha256sum aether-tunnel-* > SHA256SUMS.txt
+
+      - name: Attest tunnel release provenance
+        id: attest-release
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
+        with:
+          subject-path: |
+            artifacts/aether-tunnel-*.tar.gz
+            artifacts/aether-tunnel-*.zip
+            artifacts/SHA256SUMS.txt
+
+      - name: Bundle tunnel release provenance
+        env:
+          ATTESTATION_BUNDLE: ${{ steps.attest-release.outputs.bundle-path }}
+        run: install -m 0644 "${ATTESTATION_BUNDLE}" artifacts/AETHER_TUNNEL_RELEASE_PROVENANCE.sigstore.json
+
+      - name: Delete stale draft releases for tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+          REPOSITORY: ${{ github.repository }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          draft_ids="$(gh api "repos/${REPOSITORY}/releases" --paginate --jq '.[] | select(.tag_name == env.RELEASE_TAG and .draft == true) | .id')"
+
+          if [[ -z "${draft_ids}" ]]; then
+            echo "No stale draft releases for ${RELEASE_TAG}"
+            exit 0
+          fi
+
+          while IFS= read -r release_id; do
+            [[ -z "${release_id}" ]] && continue
+            echo "Deleting stale draft release ${release_id} for ${RELEASE_TAG}"
+            gh api -X DELETE "repos/${REPOSITORY}/releases/${release_id}"
+          done <<< "${draft_ids}"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
+        with:
+          name: "${{ github.ref_name }}"
+          generate_release_notes: true
+          files: |
+            artifacts/aether-tunnel-*
+            artifacts/AETHER_TUNNEL_RELEASE_PROVENANCE.sigstore.json
+            artifacts/SHA256SUMS.txt
+          fail_on_unmatched_files: true
+
+  update-readme:
+    needs: release
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          ref: main
+
+      - name: Update README download links
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          VERSION="${TAG#tunnel-v}"
+          BASE="https://github.com/fawney19/Aether/releases/download/${TAG}"
+
+          if [ -d apps/aether-tunnel ]; then
+            TUNNEL_DIR="apps/aether-tunnel"
+          else
+            TUNNEL_DIR="aether-tunnel"
+          fi
+
+          cd "$TUNNEL_DIR"
+
+          TABLE="| Platform | Download |\n|----------|----------|\n"
+          TABLE+="| Linux x86_64 (GNU) | [aether-tunnel-linux-amd64.tar.gz](${BASE}/aether-tunnel-linux-amd64.tar.gz) |\n"
+          TABLE+="| Linux ARM64 (GNU) | [aether-tunnel-linux-arm64.tar.gz](${BASE}/aether-tunnel-linux-arm64.tar.gz) |\n"
+          TABLE+="| Linux x86_64 (musl) | [aether-tunnel-linux-musl-amd64.tar.gz](${BASE}/aether-tunnel-linux-musl-amd64.tar.gz) |\n"
+          TABLE+="| Linux ARM64 (musl) | [aether-tunnel-linux-musl-arm64.tar.gz](${BASE}/aether-tunnel-linux-musl-arm64.tar.gz) |\n"
+          TABLE+="| macOS x86_64 | [aether-tunnel-macos-amd64.tar.gz](${BASE}/aether-tunnel-macos-amd64.tar.gz) |\n"
+          TABLE+="| macOS ARM64 | [aether-tunnel-macos-arm64.tar.gz](${BASE}/aether-tunnel-macos-arm64.tar.gz) |\n"
+          TABLE+="| Windows x86_64 | [aether-tunnel-windows-amd64.zip](${BASE}/aether-tunnel-windows-amd64.zip) |"
+
+          # Replace content between markers
+          if grep -q '<!-- DOWNLOAD_TABLE_START -->' README.md; then
+            awk -v table="$TABLE" '
+              /<!-- DOWNLOAD_TABLE_START -->/ { print; printf "%s\n", table; skip=1; next }
+              /<!-- DOWNLOAD_TABLE_END -->/ { skip=0 }
+              !skip { print }
+            ' README.md > README.tmp && mv README.tmp README.md
+          fi
+
+      - name: Commit and push
+        run: |
+          if [ -d apps/aether-tunnel ]; then
+            TUNNEL_DIR="apps/aether-tunnel"
+          else
+            TUNNEL_DIR="aether-tunnel"
+          fi
+
+          cd "$TUNNEL_DIR"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add README.md
+          git diff --cached --quiet && exit 0
+          TAG="${GITHUB_REF#refs/tags/}"
+          git commit -m "chore(tunnel): update download links for ${TAG}"
+          git push

.github/workflows/deploy-pages.yml

@@ -7,25 +7,59 @@ on:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 concurrency:
   group: pages
   cancel-in-progress: false
 
 jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    outputs:
+      deploy_pages: ${{ steps.classify.outputs.deploy_pages }}
+    steps:
+      - name: Ensure stable Pages release tag
+        id: classify
+        shell: bash
+        run: |
+          set -euo pipefail
+          echo "deploy_pages=false" >> "${GITHUB_OUTPUT}"
+
+          if [[ "${GITHUB_REF_TYPE}" != "tag" ]]; then
+            echo "Manual Pages deployment."
+            echo "deploy_pages=true" >> "${GITHUB_OUTPUT}"
+            exit 0
+          fi
+
+          tag="${GITHUB_REF_NAME}"
+          if [[ ! "${tag}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Skipping Pages deploy for non-stable release tag: ${tag}"
+            exit 0
+          fi
+
+          echo "deploy_pages=true" >> "${GITHUB_OUTPUT}"
+
   build:
+    needs: preflight
+    if: needs.preflight.outputs.deploy_pages == 'true'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'npm'
-          cache-dependency-path: frontend/package-lock.json
+          cache-dependency-path: |
+            frontend/package-lock.json
+            aether-vscodex/web/package-lock.json
+
+      - name: Build aether-vscodex web
+        working-directory: aether-vscodex/web
+        run: |
+          npm ci
+          npm run build
 
       - name: Install dependencies
         working-directory: frontend
@@ -41,10 +75,10 @@ jobs:
         run: cp frontend/dist/index.html frontend/dist/404.html
 
       - name: Setup Pages
-        uses: actions/configure-pages@v4
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
         with:
           path: frontend/dist
 
@@ -54,7 +88,10 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     needs: build
+    permissions:
+      id-token: write
+      pages: write
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

.github/workflows/docker-publish.yml

@@ -1,257 +0,0 @@
-name: Build and Publish Docker Image
-
-on:
-  push:
-    tags: ['v*']
-  workflow_dispatch:
-    inputs:
-      build_base:
-        description: 'Rebuild base image'
-        required: false
-        default: false
-        type: boolean
-
-env:
-  REGISTRY: ghcr.io
-  BASE_IMAGE_NAME: fawney19/aether-base
-  APP_IMAGE_NAME: fawney19/aether
-  # Base image hash inputs:
-  # - Dockerfile.base
-  # - pyproject.toml (dependency fingerprint only; ignores tool/optional deps)
-  # - frontend/package-lock.json
-
-jobs:
-  check-base-changes:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: read
-    outputs:
-      base_changed: ${{ steps.check.outputs.base_changed }}
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Log in to Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Check if base image needs rebuild
-        id: check
-        run: |
-          if [ "${{ github.event.inputs.build_base }}" == "true" ]; then
-            echo "base_changed=true" >> $GITHUB_OUTPUT
-            exit 0
-          fi
-
-          # Calculate current hash of base-related inputs (dependency-only fingerprint)
-          PY_FINGERPRINT=$(python3 - <<'PY'
-          import json
-          import pathlib
-          import tomllib
-          
-          data = tomllib.loads(pathlib.Path("pyproject.toml").read_text("utf-8"))
-          project = data.get("project") or {}
-          build = data.get("build-system") or {}
-          
-          fingerprint = {
-              "requires-python": project.get("requires-python"),
-              "dependencies": sorted(project.get("dependencies") or []),
-              "build-backend": build.get("build-backend"),
-              "build-requires": sorted(build.get("requires") or []),
-          }
-          
-          print(json.dumps(fingerprint, sort_keys=True, separators=(",", ":")))
-          PY
-          )
-          
-          CURRENT_HASH=$(
-            (
-              cat Dockerfile.base
-              printf '%s\n' "$PY_FINGERPRINT"
-              cat frontend/package-lock.json
-            ) | sha256sum | cut -d' ' -f1
-          )
-          echo "Current base hash: $CURRENT_HASH"
-
-          # Try to get hash label from remote image config
-          # Pull the image config and extract labels
-          REMOTE_HASH=""
-          if docker pull ${{ env.REGISTRY }}/${{ env.BASE_IMAGE_NAME }}:latest; then
-            REMOTE_HASH=$(docker inspect ${{ env.REGISTRY }}/${{ env.BASE_IMAGE_NAME }}:latest --format '{{ index .Config.Labels "org.opencontainers.image.base.hash" }}' 2>/dev/null) || true
-          else
-            echo "WARN: failed to pull remote base image; forcing base rebuild."
-            echo "base_changed=true" >> $GITHUB_OUTPUT
-            exit 0
-          fi
-
-          if [ -z "$REMOTE_HASH" ] || [ "$REMOTE_HASH" == "<no value>" ]; then
-            # No remote image or no hash label, need to rebuild
-            echo "No remote base image or hash label found, need rebuild"
-            echo "base_changed=true" >> $GITHUB_OUTPUT
-          elif [ "$CURRENT_HASH" != "$REMOTE_HASH" ]; then
-            echo "Hash mismatch: remote=$REMOTE_HASH, current=$CURRENT_HASH"
-            echo "base_changed=true" >> $GITHUB_OUTPUT
-          else
-            echo "Hash matches, no rebuild needed"
-            echo "base_changed=false" >> $GITHUB_OUTPUT
-          fi
-
-  build-base:
-    needs: check-base-changes
-    if: needs.check-base-changes.outputs.base_changed == 'true'
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Log in to Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Calculate base files hash
-        id: hash
-        run: |
-          PY_FINGERPRINT=$(python3 - <<'PY'
-          import json
-          import pathlib
-          import tomllib
-          
-          data = tomllib.loads(pathlib.Path("pyproject.toml").read_text("utf-8"))
-          project = data.get("project") or {}
-          build = data.get("build-system") or {}
-          
-          fingerprint = {
-              "requires-python": project.get("requires-python"),
-              "dependencies": sorted(project.get("dependencies") or []),
-              "build-backend": build.get("build-backend"),
-              "build-requires": sorted(build.get("requires") or []),
-          }
-          
-          print(json.dumps(fingerprint, sort_keys=True, separators=(",", ":")))
-          PY
-          )
-          
-          HASH=$(
-            (
-              cat Dockerfile.base
-              printf '%s\n' "$PY_FINGERPRINT"
-              cat frontend/package-lock.json
-            ) | sha256sum | cut -d' ' -f1
-          )
-          echo "hash=$HASH" >> $GITHUB_OUTPUT
-
-      - name: Extract metadata for base image
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.BASE_IMAGE_NAME }}
-          tags: |
-            type=raw,value=latest
-            type=sha,prefix=
-          labels: |
-            org.opencontainers.image.base.hash=${{ steps.hash.outputs.hash }}
-
-      - name: Build and push base image
-        uses: docker/build-push-action@v5
-        with:
-          context: .
-          file: ./Dockerfile.base
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha,scope=base
-          cache-to: type=gha,mode=max,scope=base
-          platforms: linux/amd64,linux/arm64
-
-  build-app:
-    needs: [check-base-changes, build-base]
-    if: always() && (needs.build-base.result == 'success' || needs.build-base.result == 'skipped')
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Log in to Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Extract metadata for app image
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: |
-            ${{ env.REGISTRY }}/${{ env.APP_IMAGE_NAME }}
-            docker.io/fawney19/aether
-          tags: |
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=raw,value=pre,enable=${{ contains(github.ref, '-') }}
-            type=raw,value=fix,enable=${{ contains(github.ref, '-fix') }}
-            type=sha,prefix=
-          flavor: |
-            latest=auto
-
-      - name: Extract version from tag
-        id: version
-        run: |
-          # 从 tag 提取版本号，如 v0.2.5 -> 0.2.5
-          VERSION="${GITHUB_REF#refs/tags/v}"
-          if [ "$VERSION" = "$GITHUB_REF" ]; then
-            # 不是 tag 触发，使用 git describe
-            VERSION=$(git describe --tags --always | sed 's/^v//')
-          fi
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
-          echo "Extracted version: $VERSION"
-
-      - name: Update Dockerfile.app to use registry base image
-        run: |
-          sed -i "s|FROM aether-base:latest AS builder|FROM ${{ env.REGISTRY }}/${{ env.BASE_IMAGE_NAME }}:latest AS builder|g" Dockerfile.app
-
-      - name: Generate version file
-        run: |
-          # 生成 _version.py 文件
-          cat > src/_version.py << EOF
-          # Auto-generated by CI
-          __version__ = '${{ steps.version.outputs.version }}'
-          __version_tuple__ = tuple(int(x) for x in '${{ steps.version.outputs.version }}'.split('.') if x.isdigit())
-          version = __version__
-          version_tuple = __version_tuple__
-          EOF
-
-      - name: Build and push app image
-        uses: docker/build-push-action@v5
-        with:
-          context: .
-          file: ./Dockerfile.app
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          no-cache-filters: builder
-          cache-from: type=gha,scope=app
-          cache-to: type=gha,mode=min,scope=app
-          platforms: linux/amd64,linux/arm64

.github/workflows/nightly.yml

@@ -0,0 +1,620 @@
+name: Nightly Release
+
+on:
+  # 02:17 Asia/Shanghai (18:17 UTC) every day.
+  schedule:
+    - cron: '17 18 * * *'
+  workflow_dispatch:
+
+# Checks and builds only need read access. Publishing jobs opt into write access
+# below so a failed build cannot modify the existing nightly release.
+permissions:
+  actions: read
+  contents: read
+
+# A rolling tag and image are shared by scheduled and manually retried runs.
+# Keep GitHub Release immutability disabled for this repository: the tag and
+# assets intentionally move after each successful daily build.
+concurrency:
+  group: nightly-main
+  cancel-in-progress: false
+
+env:
+  CARGO_INCREMENTAL: '0'
+  CARGO_PROFILE_DEV_DEBUG: '0'
+  CARGO_PROFILE_TEST_DEBUG: '0'
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: '1'
+
+jobs:
+  source:
+    name: Resolve main snapshot
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      sha: ${{ steps.snapshot.outputs.sha }}
+      short_sha: ${{ steps.snapshot.outputs.short_sha }}
+      date: ${{ steps.snapshot.outputs.date }}
+      ghcr_image: ${{ steps.snapshot.outputs.ghcr_image }}
+    steps:
+      - name: Require main branch
+        id: snapshot
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [[ "${GITHUB_REF}" != "refs/heads/main" ]]; then
+            echo "Nightly releases must run from refs/heads/main (got ${GITHUB_REF})." >&2
+            exit 1
+          fi
+
+          sha="${GITHUB_SHA}"
+          # Docker 镜像仓库名必须全小写；GitHub owner 可能保留大写，先统一规范化。
+          repository_owner="${GITHUB_REPOSITORY%%/*}"
+          repository_owner="${repository_owner,,}"
+          echo "sha=${sha}" >> "${GITHUB_OUTPUT}"
+          echo "short_sha=${sha:0:7}" >> "${GITHUB_OUTPUT}"
+          echo "date=$(date -u +'%Y-%m-%d')" >> "${GITHUB_OUTPUT}"
+          echo "ghcr_image=ghcr.io/${repository_owner}/aether" >> "${GITHUB_OUTPUT}"
+          echo "Building main at ${sha}."
+
+  # Keep the scheduled backend coverage in one place so it cannot drift from PR CI.
+  rust_ci:
+    name: Rust CI
+    needs: source
+    uses: ./.github/workflows/rust-ci.yml
+
+  rust_extended:
+    name: Rust extended checks
+    needs: source
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          ref: ${{ needs.source.outputs.sha }}
+
+      - name: Install pinned Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+        with:
+          toolchain: 1.95.0
+
+      - name: Show Rust toolchain
+        run: rustc -Vv
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@49a0bdc70d2e1b713ca9e2869b211fcce03d3c1c # v2
+        with:
+          shared-key: nightly-rust-1.95-${{ runner.os }}
+          workspaces: . -> target
+
+      - name: Setup sccache
+        uses: mozilla-actions/sccache-action@7d986dd989559c6ecdb630a3fd2557667be217ad # v0.0.9
+
+      - name: Check all workspace targets
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: 'true'
+        run: cargo check --workspace --all-targets --all-features --locked
+
+      - name: Run workspace doctests
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: 'true'
+        run: cargo test --workspace --all-features --doc --locked
+
+      - name: Show sccache stats
+        if: always()
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: 'true'
+        run: sccache --show-stats
+
+  frontend:
+    name: Frontend checks and build
+    needs: source
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          ref: ${{ needs.source.outputs.sha }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: |
+            frontend/package-lock.json
+            aether-vscodex/web/package-lock.json
+
+      # The frontend prebuild synchronizes the embedded VSCodex UI by running
+      # its build from a separate package. Install that package explicitly so
+      # vue-tsc can resolve vite/client, vitest/globals, and node types in a
+      # clean runner.
+      - name: Install VSCodex web dependencies
+        working-directory: aether-vscodex/web
+        run: npm ci
+
+      - name: Install dependencies
+        working-directory: frontend
+        run: npm ci
+
+      - name: Lint
+        working-directory: frontend
+        run: npx --no-install eslint .
+
+      - name: Type-check
+        working-directory: frontend
+        run: npm run type-check
+
+      - name: Run unit tests
+        working-directory: frontend
+        run: npm run test:run
+
+      - name: Build nightly frontend
+        working-directory: frontend
+        env:
+          AETHER_BUILD_VERSION: nightly-${{ needs.source.outputs.short_sha }}
+          AETHER_VERSION: nightly
+        run: npm run build
+
+      - name: Upload frontend artifact
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: nightly-frontend-dist
+          path: frontend/dist/
+          if-no-files-found: error
+          overwrite: true
+          retention-days: 7
+
+  repository_health:
+    name: Repository health checks
+    needs: source
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          ref: ${{ needs.source.outputs.sha }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: '22'
+
+      - name: Check generated format coverage matrix
+        run: python3 docs/api/generate_format_field_coverage.py --check
+
+      - name: Test pressure report checker
+        run: node --test tools/pressure/check_gateway_stage_report.test.js
+
+  checks:
+    name: Nightly check gate
+    runs-on: ubuntu-latest
+    if: ${{ always() }}
+    needs:
+      - source
+      - rust_ci
+      - rust_extended
+      - frontend
+      - repository_health
+    steps:
+      - name: Verify check jobs
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          failed=0
+          echo "source=${{ needs.source.result }}"
+          echo "rust_ci=${{ needs.rust_ci.result }}"
+          echo "rust_extended=${{ needs.rust_extended.result }}"
+          echo "frontend=${{ needs.frontend.result }}"
+          echo "repository_health=${{ needs.repository_health.result }}"
+
+          for result in \
+            "${{ needs.source.result }}" \
+            "${{ needs.rust_ci.result }}" \
+            "${{ needs.rust_extended.result }}" \
+            "${{ needs.frontend.result }}" \
+            "${{ needs.repository_health.result }}"; do
+            if [[ "${result}" != "success" ]]; then
+              failed=1
+            fi
+          done
+
+          if [[ "${failed}" -ne 0 ]]; then
+            echo 'One or more nightly checks failed or were cancelled.' >&2
+            exit 1
+          fi
+
+  build:
+    name: Build ${{ matrix.name }}
+    needs: [source, checks]
+    if: ${{ needs.checks.result == 'success' }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 120
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: linux-amd64
+            target: x86_64-unknown-linux-musl
+            platform: linux
+            arch: amd64
+            os: ubuntu-latest
+            use_cross: true
+          - name: linux-arm64
+            target: aarch64-unknown-linux-musl
+            platform: linux
+            arch: arm64
+            os: ubuntu-latest
+            use_cross: true
+          - name: macos-amd64
+            target: x86_64-apple-darwin
+            platform: macos
+            arch: amd64
+            os: macos-15-intel
+            use_cross: false
+          - name: macos-arm64
+            target: aarch64-apple-darwin
+            platform: macos
+            arch: arm64
+            os: macos-15
+            use_cross: false
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          ref: ${{ needs.source.outputs.sha }}
+
+      - name: Install pinned Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+        with:
+          toolchain: 1.95.0
+          targets: ${{ matrix.target }}
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@49a0bdc70d2e1b713ca9e2869b211fcce03d3c1c # v2
+        with:
+          shared-key: nightly-release-${{ matrix.target }}
+          workspaces: . -> target
+
+      - name: Install cross
+        if: matrix.use_cross
+        uses: taiki-e/install-action@1ae7257be536a92d9218a6b343dc6e6ba650f7e1 # cross
+
+      - name: Build release binary
+        env:
+          AETHER_BUILD_VERSION: nightly-${{ needs.source.outputs.short_sha }}
+          AETHER_VERSION: nightly
+          AETHER_BUILD_TYPE: release
+          CARGO_TERM_COLOR: always
+        shell: bash
+        run: |
+          if [[ "${{ matrix.use_cross }}" == "true" ]]; then
+            cross build --release --locked -p aether-gateway --target "${{ matrix.target }}"
+          else
+            cargo build --release --locked -p aether-gateway --target "${{ matrix.target }}"
+          fi
+
+      - name: Upload binary artifact
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: nightly-gateway-${{ matrix.platform }}-${{ matrix.arch }}
+          path: target/${{ matrix.target }}/release/aether-gateway
+          if-no-files-found: error
+          overwrite: true
+          retention-days: 7
+
+  docker:
+    name: Publish nightly GHCR image
+    needs: [source, checks, build]
+    if: ${{ needs.checks.result == 'success' && needs.build.result == 'success' }}
+    runs-on: ubuntu-latest
+    env:
+      GHCR_IMAGE: ${{ needs.source.outputs.ghcr_image }}
+    permissions:
+      actions: read
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          ref: ${{ needs.source.outputs.sha }}
+
+      - name: Download Linux binaries and frontend
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          pattern: nightly-*
+          path: artifacts
+          merge-multiple: false
+
+      - name: Prepare Docker build context
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p dist/frontend
+          cp artifacts/nightly-gateway-linux-amd64/aether-gateway dist/aether-gateway-amd64
+          cp artifacts/nightly-gateway-linux-arm64/aether-gateway dist/aether-gateway-arm64
+          chmod 0755 dist/aether-gateway-amd64 dist/aether-gateway-arm64
+          cp -R artifacts/nightly-frontend-dist/. dist/frontend/
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6 # v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push nightly image
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
+        with:
+          context: .
+          file: ./Dockerfile.app
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: |
+            ${{ env.GHCR_IMAGE }}:nightly
+            ${{ env.GHCR_IMAGE }}:nightly-${{ needs.source.outputs.sha }}
+          labels: |
+            org.opencontainers.image.title=Aether
+            org.opencontainers.image.version=nightly
+            org.opencontainers.image.revision=${{ needs.source.outputs.sha }}
+            org.opencontainers.image.source=https://github.com/${{ github.repository }}
+
+  package:
+    name: Package nightly archives
+    needs: [source, checks, build]
+    if: ${{ needs.checks.result == 'success' && needs.build.result == 'success' }}
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          ref: ${{ needs.source.outputs.sha }}
+
+      - name: Download nightly artifacts
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          pattern: nightly-*
+          path: artifacts
+          merge-multiple: false
+
+      - name: Build nightly release packages
+        shell: bash
+        env:
+          SOURCE_REF: ${{ needs.source.outputs.sha }}
+        run: |
+          set -euo pipefail
+          VERSION="nightly"
+
+          mkdir -p package release-assets
+          for platform in linux macos; do
+            for arch in amd64 arm64; do
+              bundle="aether-${VERSION}-${platform}-${arch}"
+              root="package/${bundle}"
+              mkdir -p "${root}/bin" "${root}/frontend"
+
+              install -m 0755 \
+                "artifacts/nightly-gateway-${platform}-${arch}/aether-gateway" \
+                "${root}/bin/aether-gateway"
+              cp -R artifacts/nightly-frontend-dist/. "${root}/frontend/"
+              sed \
+                -e "s/^SOURCE_REF=\"\${AETHER_SOURCE_REF:-main}\"/SOURCE_REF=\"\${AETHER_SOURCE_REF:-${SOURCE_REF}}\"/" \
+                -e "s/^VERSION=\"\${AETHER_VERSION:-}\"/VERSION=\"\${AETHER_VERSION:-${VERSION}}\"/" \
+                install.sh > "${root}/install.sh"
+              chmod 0755 "${root}/install.sh"
+              install -m 0755 update.sh "${root}/update.sh"
+              install -m 0644 docker-compose.yml "${root}/docker-compose.yml"
+              install -m 0644 docker-compose.single-node.yml "${root}/docker-compose.single-node.yml"
+              install -m 0644 .env.example "${root}/.env.example"
+              install -m 0755 generate_keys.sh "${root}/generate_keys.sh"
+              install -m 0644 README.md "${root}/README.md"
+              install -m 0644 LICENSE "${root}/LICENSE"
+
+              tar -C package -czf "release-assets/${bundle}.tar.gz" "${bundle}"
+            done
+          done
+
+          sed \
+            -e "s/^SOURCE_REF=\"\${AETHER_SOURCE_REF:-main}\"/SOURCE_REF=\"\${AETHER_SOURCE_REF:-${SOURCE_REF}}\"/" \
+            -e "s/^VERSION=\"\${AETHER_VERSION:-}\"/VERSION=\"\${AETHER_VERSION:-${VERSION}}\"/" \
+            install.sh > release-assets/install.sh
+          chmod 0755 release-assets/install.sh
+          (cd release-assets && sha256sum *.tar.gz > SHA256SUMS)
+
+          test "$(find release-assets -maxdepth 1 -name '*.tar.gz' | wc -l)" -eq 4
+          test "$(wc -l < release-assets/SHA256SUMS)" -eq 4
+          (cd release-assets && sha256sum -c SHA256SUMS)
+          for archive in release-assets/*.tar.gz; do
+            tar -tzf "${archive}" >/dev/null
+          done
+
+      - name: Upload nightly package artifact
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: nightly-release-assets
+          path: release-assets/*
+          if-no-files-found: error
+          overwrite: true
+          retention-days: 7
+
+  github_release:
+    name: Publish nightly GitHub Release
+    needs: [source, checks, docker, package]
+    if: ${{ needs.checks.result == 'success' && needs.docker.result == 'success' && needs.package.result == 'success' }}
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: write
+    steps:
+      - name: Download nightly package artifact
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          name: nightly-release-assets
+          path: release-assets
+
+      - name: Update rolling nightly release
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPOSITORY: ${{ github.repository }}
+          RELEASE_TAG: nightly
+          SOURCE_SHA: ${{ needs.source.outputs.sha }}
+          SOURCE_SHORT_SHA: ${{ needs.source.outputs.short_sha }}
+          RELEASE_DATE: ${{ needs.source.outputs.date }}
+          GHCR_IMAGE: ${{ needs.source.outputs.ghcr_image }}
+        run: |
+          set -euo pipefail
+
+          release_title="Aether Nightly ${RELEASE_DATE} (${SOURCE_SHORT_SHA})"
+          notes_file="${RUNNER_TEMP}/nightly-release-notes.md"
+          cat > "${notes_file}" <<EOF
+          ## Aether nightly
+
+          This rolling prerelease was built from [main commit ${SOURCE_SHORT_SHA}](https://github.com/${REPOSITORY}/commit/${SOURCE_SHA}).
+
+          - Source branch: main
+          - Source commit: ${SOURCE_SHA}
+          - Build date (UTC): ${RELEASE_DATE}
+          - Container image: ${GHCR_IMAGE}:nightly
+          - Commit image: ${GHCR_IMAGE}:nightly-${SOURCE_SHA}
+
+          The nightly tag and assets are replaced by the next successful daily build.
+          EOF
+
+          # Create a draft on the first run. Later runs repair the same rolling
+          # release on retry if any upload or metadata update is interrupted.
+          if ! gh release view "${RELEASE_TAG}" --repo "${REPOSITORY}" >/dev/null 2>&1; then
+            gh release create "${RELEASE_TAG}" \
+              --repo "${REPOSITORY}" \
+              --draft \
+              --prerelease \
+              --latest=false \
+              --target "${SOURCE_SHA}" \
+              --title "${release_title}" \
+              --notes-file "${notes_file}"
+          fi
+
+          # Upload archives first, then the checksum/installer metadata. This
+          # keeps a failed upload from leaving a checksum that describes files
+          # which have not reached the Release yet.
+          gh release upload "${RELEASE_TAG}" release-assets/*.tar.gz \
+            --repo "${REPOSITORY}" \
+            --clobber
+          gh release upload "${RELEASE_TAG}" \
+            release-assets/SHA256SUMS \
+            release-assets/install.sh \
+            --repo "${REPOSITORY}" \
+            --clobber
+
+          # target_commitish does not move an existing git tag. Move the ref
+          # only after the complete asset set is available.
+          if gh api "repos/${REPOSITORY}/git/ref/tags/${RELEASE_TAG}" >/dev/null 2>&1; then
+            gh api -X PATCH "repos/${REPOSITORY}/git/refs/tags/${RELEASE_TAG}" \
+              -f "sha=${SOURCE_SHA}" \
+              -F 'force=true' >/dev/null
+          else
+            gh api -X POST "repos/${REPOSITORY}/git/refs" \
+              -f "ref=refs/tags/${RELEASE_TAG}" \
+              -f "sha=${SOURCE_SHA}" >/dev/null
+          fi
+
+          gh release edit "${RELEASE_TAG}" \
+            --repo "${REPOSITORY}" \
+            --draft=false \
+            --prerelease \
+            --latest=false \
+            --target "${SOURCE_SHA}" \
+            --title "${release_title}" \
+            --notes-file "${notes_file}"
+
+          expected_assets=(
+            aether-nightly-linux-amd64.tar.gz
+            aether-nightly-linux-arm64.tar.gz
+            aether-nightly-macos-amd64.tar.gz
+            aether-nightly-macos-arm64.tar.gz
+            SHA256SUMS
+            install.sh
+          )
+          asset_names="$(gh release view "${RELEASE_TAG}" --repo "${REPOSITORY}" --json assets --jq '.assets[].name')"
+          for expected_asset in "${expected_assets[@]}"; do
+            if ! grep -Fxq "${expected_asset}" <<<"${asset_names}"; then
+              echo "Published release is missing asset ${expected_asset}." >&2
+              exit 1
+            fi
+          done
+
+          resolved_sha=""
+          for attempt in {1..10}; do
+            resolved_sha="$(gh api "repos/${REPOSITORY}/commits/${RELEASE_TAG}" --jq '.sha' 2>/dev/null || true)"
+            if [[ "${resolved_sha}" == "${SOURCE_SHA}" ]]; then
+              break
+            fi
+            sleep 2
+          done
+          if [[ "${resolved_sha}" != "${SOURCE_SHA}" ]]; then
+            echo "nightly tag resolved to ${resolved_sha}, expected ${SOURCE_SHA}." >&2
+            exit 1
+          fi
+
+          release_state="$(gh release view "${RELEASE_TAG}" --repo "${REPOSITORY}" --json isDraft,isPrerelease --jq '[.isDraft, .isPrerelease] | @tsv')"
+          if [[ "${release_state}" != $'false\ttrue' ]]; then
+            echo "nightly release has unexpected state: ${release_state}" >&2
+            exit 1
+          fi
+
+          echo "Published ${RELEASE_TAG} for ${SOURCE_SHA}."
+
+  summary:
+    name: Nightly summary
+    runs-on: ubuntu-latest
+    if: ${{ always() }}
+    needs:
+      - source
+      - rust_ci
+      - rust_extended
+      - frontend
+      - repository_health
+      - checks
+      - build
+      - docker
+      - package
+      - github_release
+    steps:
+      - name: Verify nightly pipeline
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          failed=0
+          for entry in \
+            "source=${{ needs.source.result }}" \
+            "rust_ci=${{ needs.rust_ci.result }}" \
+            "rust_extended=${{ needs.rust_extended.result }}" \
+            "frontend=${{ needs.frontend.result }}" \
+            "repository_health=${{ needs.repository_health.result }}" \
+            "checks=${{ needs.checks.result }}" \
+            "build=${{ needs.build.result }}" \
+            "docker=${{ needs.docker.result }}" \
+            "package=${{ needs.package.result }}" \
+            "github_release=${{ needs.github_release.result }}"; do
+            echo "${entry}"
+            if [[ "${entry#*=}" != "success" ]]; then
+              failed=1
+            fi
+          done
+
+          if [[ "${failed}" -ne 0 ]]; then
+            echo 'Nightly pipeline did not publish a new release.' >&2
+            exit 1
+          fi

.github/workflows/release.yml

@@ -0,0 +1,470 @@
+name: Release Aether
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+permissions:
+  actions: read
+  contents: read
+
+concurrency:
+  group: release-aether-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  REGISTRY: ghcr.io
+  GHCR_IMAGE: fawney19/aether
+  DOCKERHUB_IMAGE: fawney19/aether
+
+jobs:
+  preflight:
+    name: Release preflight
+    runs-on: ubuntu-latest
+    outputs:
+      publish: ${{ steps.classify.outputs.publish }}
+      version_tag: ${{ steps.classify.outputs.version_tag }}
+      prerelease: ${{ steps.classify.outputs.prerelease }}
+      make_latest: ${{ steps.classify.outputs.make_latest }}
+    steps:
+      - name: Classify release tag
+        id: classify
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          echo "publish=false" >> "${GITHUB_OUTPUT}"
+          echo "version_tag=" >> "${GITHUB_OUTPUT}"
+          echo "prerelease=false" >> "${GITHUB_OUTPUT}"
+          echo "make_latest=false" >> "${GITHUB_OUTPUT}"
+
+          if [[ "${GITHUB_REF_TYPE}" != "tag" ]]; then
+            echo "Manual release build; publish jobs will be skipped."
+            exit 0
+          fi
+
+          tag="${GITHUB_REF_NAME}"
+          if [[ ! "${tag}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-(beta|rc)\.[0-9]+)?$ ]]; then
+            echo "Unsupported release tag: ${tag}" >&2
+            echo "Expected vX.Y.Z, vX.Y.Z-beta.N, or vX.Y.Z-rc.N." >&2
+            exit 1
+          fi
+
+          echo "version_tag=${tag}" >> "${GITHUB_OUTPUT}"
+
+          if [[ "${tag}" == *-* ]]; then
+            echo "prerelease=true" >> "${GITHUB_OUTPUT}"
+          else
+            echo "make_latest=true" >> "${GITHUB_OUTPUT}"
+          fi
+
+          if [[ "${GITHUB_EVENT_NAME}" == "push" ]]; then
+            echo "publish=true" >> "${GITHUB_OUTPUT}"
+          else
+            echo "Manual release build for ${tag}; publish jobs will be skipped."
+          fi
+
+  frontend:
+    name: Build frontend
+    needs: preflight
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: |
+            frontend/package-lock.json
+            aether-vscodex/web/package-lock.json
+
+      - name: Build aether-vscodex web
+        working-directory: aether-vscodex/web
+        run: |
+          npm ci
+          npm run build
+
+      - name: Install & build
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build
+
+      - name: Upload frontend artifact
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: frontend-dist
+          path: frontend/dist/
+          if-no-files-found: error
+          retention-days: 1
+
+  vscodex:
+    name: Build VS Code Codex extension
+    needs: preflight
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: |
+            aether-vscodex/package-lock.json
+            aether-vscodex/web/package-lock.json
+            aether-vscodex/vscode-extension/package-lock.json
+
+      - name: Install module test dependencies
+        working-directory: aether-vscodex
+        run: npm ci
+
+      - name: Build the embedded Web UI
+        working-directory: aether-vscodex/web
+        run: |
+          npm ci
+          npm run build
+
+      - name: Install extension dependencies
+        working-directory: aether-vscodex/vscode-extension
+        run: npm ci
+
+      - name: Check and compile the extension
+        working-directory: aether-vscodex/vscode-extension
+        run: |
+          npm run check
+          npm run build
+
+      - name: Run module tests
+        working-directory: aether-vscodex
+        run: npm test
+
+      - name: Run Web UI tests
+        working-directory: aether-vscodex/web
+        run: npm test
+
+      - name: Package VSIX
+        working-directory: aether-vscodex/vscode-extension
+        shell: bash
+        run: |
+          set -euo pipefail
+          version="$(node -p "require('./package.json').version")"
+          npx --yes @vscode/vsce package --no-update-package-json --allow-missing-repository
+          source_vsix="codex-remote-collab-${version}.vsix"
+          test -f "${source_vsix}"
+          mv "${source_vsix}" "aether-vscodex-${version}.vsix"
+          unzip -l "aether-vscodex-${version}.vsix" | grep 'extension/node_modules/ws/index.js' >/dev/null
+
+      - name: Upload VSIX artifact
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: aether-vscodex-vsix
+          path: aether-vscodex/vscode-extension/aether-vscodex-*.vsix
+          if-no-files-found: error
+          retention-days: 7
+
+  build:
+    name: Build ${{ matrix.name }}
+    needs: preflight
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: true
+      matrix:
+        include:
+          - name: linux-amd64
+            target: x86_64-unknown-linux-musl
+            platform: linux
+            arch: amd64
+            os: ubuntu-latest
+            use_cross: true
+          - name: linux-arm64
+            target: aarch64-unknown-linux-musl
+            platform: linux
+            arch: arm64
+            os: ubuntu-latest
+            use_cross: true
+          - name: macos-amd64
+            target: x86_64-apple-darwin
+            platform: macos
+            arch: amd64
+            os: macos-15-intel
+            use_cross: false
+          - name: macos-arm64
+            target: aarch64-apple-darwin
+            platform: macos
+            arch: arm64
+            os: macos-15
+            use_cross: false
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@49a0bdc70d2e1b713ca9e2869b211fcce03d3c1c # v2
+        with:
+          shared-key: release-${{ matrix.target }}
+          workspaces: . -> target
+
+      - name: Install cross
+        if: matrix.use_cross
+        uses: taiki-e/install-action@1ae7257be536a92d9218a6b343dc6e6ba650f7e1 # cross
+
+      - name: Build
+        env:
+          AETHER_VERSION: ${{ needs.preflight.outputs.version_tag }}
+          AETHER_BUILD_TYPE: release
+          CARGO_TERM_COLOR: always
+        shell: bash
+        run: |
+          if [[ "${{ matrix.use_cross }}" == "true" ]]; then
+            cross build --release --locked -p aether-gateway --target ${{ matrix.target }}
+          else
+            cargo build --release --locked -p aether-gateway --target ${{ matrix.target }}
+          fi
+
+      - name: Upload binary artifact
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: aether-gateway-${{ matrix.platform }}-${{ matrix.arch }}
+          path: target/${{ matrix.target }}/release/aether-gateway
+          if-no-files-found: error
+          retention-days: 1
+
+  docker:
+    name: Docker multi-arch
+    needs: [preflight, frontend, build]
+    if: needs.preflight.outputs.publish == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      attestations: write
+      contents: read
+      id-token: write
+      packages: write
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          path: artifacts
+
+      - name: Prepare dist layout
+        run: |
+          mkdir -p dist
+          cp artifacts/aether-gateway-linux-amd64/aether-gateway dist/aether-gateway-amd64
+          cp artifacts/aether-gateway-linux-arm64/aether-gateway dist/aether-gateway-arm64
+          chmod +x dist/aether-gateway-amd64 dist/aether-gateway-arm64
+          cp -r artifacts/frontend-dist dist/frontend
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5
+        with:
+          images: |
+            ${{ env.REGISTRY }}/${{ env.GHCR_IMAGE }}
+            docker.io/${{ env.DOCKERHUB_IMAGE }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}},enable=${{ needs.preflight.outputs.make_latest == 'true' }}
+            type=raw,value=latest,enable=${{ needs.preflight.outputs.make_latest == 'true' }}
+            type=raw,value=beta,enable=${{ contains(github.ref_name, '-beta.') }}
+            type=raw,value=rc,enable=${{ contains(github.ref_name, '-rc.') }}
+            type=sha,prefix=
+          flavor: |
+            latest=false
+
+      - name: Build and push
+        id: push
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
+        with:
+          context: .
+          file: ./Dockerfile.app
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          platforms: linux/amd64,linux/arm64
+
+      - name: Attest GHCR image provenance
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
+        with:
+          subject-name: ${{ env.REGISTRY }}/${{ env.GHCR_IMAGE }}
+          subject-digest: ${{ steps.push.outputs.digest }}
+          push-to-registry: true
+          create-storage-record: false
+
+      - name: Attest Docker Hub image provenance
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
+        with:
+          subject-name: docker.io/${{ env.DOCKERHUB_IMAGE }}
+          subject-digest: ${{ steps.push.outputs.digest }}
+          push-to-registry: true
+          create-storage-record: false
+
+  package:
+    name: Release tarballs
+    needs: [preflight, frontend, build]
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      attestations: write
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          path: artifacts
+
+      - name: Build release packages
+        run: |
+          set -euo pipefail
+          if [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            VERSION="${GITHUB_REF_NAME}"
+            SOURCE_REF="${GITHUB_REF_NAME}"
+          else
+            VERSION="snapshot-${GITHUB_SHA::7}"
+            SOURCE_REF="${GITHUB_SHA}"
+          fi
+
+          mkdir -p package release-assets
+          for platform in linux macos; do
+            for arch in amd64 arm64; do
+              bundle="aether-${VERSION}-${platform}-${arch}"
+              root="package/${bundle}"
+              mkdir -p \
+                "${root}/bin" \
+                "${root}/frontend"
+
+              install -m 0755 "artifacts/aether-gateway-${platform}-${arch}/aether-gateway" "${root}/bin/aether-gateway"
+              cp -R artifacts/frontend-dist/. "${root}/frontend/"
+              sed \
+                -e "s/^SOURCE_REF=\"\${AETHER_SOURCE_REF:-main}\"/SOURCE_REF=\"\${AETHER_SOURCE_REF:-${SOURCE_REF}}\"/" \
+                -e "s/^VERSION=\"\${AETHER_VERSION:-}\"/VERSION=\"\${AETHER_VERSION:-${VERSION}}\"/" \
+                install.sh > "${root}/install.sh"
+              chmod 0755 "${root}/install.sh"
+              install -m 0755 update.sh "${root}/update.sh"
+              install -m 0644 docker-compose.yml "${root}/docker-compose.yml"
+              install -m 0644 docker-compose.single-node.yml "${root}/docker-compose.single-node.yml"
+              install -m 0644 .env.example "${root}/.env.example"
+              install -m 0755 generate_keys.sh "${root}/generate_keys.sh"
+              install -m 0644 README.md "${root}/README.md"
+              install -m 0644 LICENSE "${root}/LICENSE"
+
+              tar -C package -czf "release-assets/${bundle}.tar.gz" "${bundle}"
+            done
+          done
+
+          sed \
+            -e "s/^SOURCE_REF=\"\${AETHER_SOURCE_REF:-main}\"/SOURCE_REF=\"\${AETHER_SOURCE_REF:-${SOURCE_REF}}\"/" \
+            -e "s/^VERSION=\"\${AETHER_VERSION:-}\"/VERSION=\"\${AETHER_VERSION:-${VERSION}}\"/" \
+            install.sh > release-assets/install.sh
+          chmod +x release-assets/install.sh
+          (cd release-assets && sha256sum *.tar.gz > SHA256SUMS)
+
+      - name: Attest release package provenance
+        id: attest-release
+        if: needs.preflight.outputs.publish == 'true'
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
+        with:
+          subject-path: |
+            release-assets/*.tar.gz
+            release-assets/install.sh
+            release-assets/SHA256SUMS
+
+      - name: Bundle release package provenance
+        if: needs.preflight.outputs.publish == 'true'
+        env:
+          ATTESTATION_BUNDLE: ${{ steps.attest-release.outputs.bundle-path }}
+        run: install -m 0644 "${ATTESTATION_BUNDLE}" release-assets/AETHER_RELEASE_PROVENANCE.sigstore.json
+
+      - name: Upload release package artifact
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: release-assets
+          path: release-assets/*
+          if-no-files-found: error
+          retention-days: 7
+
+  github-release:
+    name: GitHub Release assets
+    needs: [preflight, docker, package, vscodex]
+    if: needs.preflight.outputs.publish == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: write
+    steps:
+      - name: Download release package artifact
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          name: release-assets
+          path: release-assets
+
+      - name: Download VSIX artifact
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          name: aether-vscodex-vsix
+          path: release-assets
+
+      - name: Delete stale draft releases for tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+          REPOSITORY: ${{ github.repository }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          draft_ids="$(gh api "repos/${REPOSITORY}/releases" --paginate --jq '.[] | select(.tag_name == env.RELEASE_TAG and .draft == true) | .id')"
+
+          if [[ -z "${draft_ids}" ]]; then
+            echo "No stale draft releases for ${RELEASE_TAG}"
+            exit 0
+          fi
+
+          while IFS= read -r release_id; do
+            [[ -z "${release_id}" ]] && continue
+            echo "Deleting stale draft release ${release_id} for ${RELEASE_TAG}"
+            gh api -X DELETE "repos/${REPOSITORY}/releases/${release_id}"
+          done <<< "${draft_ids}"
+
+      - name: Publish GitHub Release assets
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
+        with:
+          generate_release_notes: true
+          prerelease: ${{ needs.preflight.outputs.prerelease }}
+          make_latest: ${{ needs.preflight.outputs.make_latest }}
+          files: |
+            release-assets/*.tar.gz
+            release-assets/AETHER_RELEASE_PROVENANCE.sigstore.json
+            release-assets/SHA256SUMS
+            release-assets/install.sh
+            release-assets/*.vsix

.github/workflows/rust-ci.yml

@@ -0,0 +1,612 @@
+name: Rust CI
+
+on:
+  workflow_call:
+  push:
+    branches:
+      - master
+      - main
+    paths:
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "crates/**"
+      - "apps/**"
+      - "install.sh"
+      - "deploy.sh"
+      - "update.sh"
+      - "generate_keys.sh"
+      - ".env.example"
+      - "README.md"
+      - "Dockerfile.app"
+      - "docker-compose.yml"
+      - "docker-compose.single-node.yml"
+      - "docker-compose.local.yml"
+      - "docker-compose.release-local.yml"
+      - "tests/compose_database_config_test.py"
+      - "tests/install_*_test.sh"
+      - "tests/deploy_*_test.sh"
+      - "tests/update_*_test.sh"
+      - "tests/release_supply_chain_test.sh"
+      - "tests/tunnel_installer_config_security_test.sh"
+      - ".github/workflows/build-tunnel.yml"
+      - ".github/workflows/deploy-pages.yml"
+      - ".github/workflows/release.yml"
+      - ".github/workflows/rust-ci.yml"
+      - ".github/workflows/nightly.yml"
+  pull_request:
+    paths:
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "crates/**"
+      - "apps/**"
+      - "install.sh"
+      - "deploy.sh"
+      - "update.sh"
+      - "generate_keys.sh"
+      - ".env.example"
+      - "README.md"
+      - "Dockerfile.app"
+      - "docker-compose.yml"
+      - "docker-compose.single-node.yml"
+      - "docker-compose.local.yml"
+      - "docker-compose.release-local.yml"
+      - "tests/compose_database_config_test.py"
+      - "tests/install_*_test.sh"
+      - "tests/deploy_*_test.sh"
+      - "tests/update_*_test.sh"
+      - "tests/release_supply_chain_test.sh"
+      - "tests/tunnel_installer_config_security_test.sh"
+      - ".github/workflows/build-tunnel.yml"
+      - ".github/workflows/deploy-pages.yml"
+      - ".github/workflows/release.yml"
+      - ".github/workflows/rust-ci.yml"
+      - ".github/workflows/nightly.yml"
+
+concurrency:
+  group: rust-ci-${{ github.event_name }}-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  CARGO_INCREMENTAL: 0
+  CARGO_PROFILE_DEV_DEBUG: 0
+  CARGO_PROFILE_TEST_DEBUG: 0
+  CARGO_TERM_COLOR: always
+
+jobs:
+  shell_security:
+    name: Shell security fixtures
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Run installer and supply-chain fixtures
+        shell: bash
+        run: |
+          python3 tests/compose_database_config_test.py
+          bash tests/deploy_state_safety_test.sh
+          bash tests/install_archive_safety_test.sh
+          bash tests/install_container_runtime_security_test.sh
+          bash tests/install_current_release_link_test.sh
+          bash tests/install_local_bundle_safety_test.sh
+          bash tests/install_privileged_write_safety_test.sh
+          bash tests/install_source_trust_test.sh
+          bash tests/release_supply_chain_test.sh
+          bash tests/update_compose_safety_test.sh
+          bash tests/tunnel_installer_config_security_test.sh
+
+  fmt:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+        with:
+          toolchain: 1.95.0
+          components: rustfmt
+
+      - name: Format
+        run: cargo fmt --all --check
+
+  clippy_gateway:
+    name: Clippy (Gateway)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+        with:
+          toolchain: 1.95.0
+          components: clippy
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@49a0bdc70d2e1b713ca9e2869b211fcce03d3c1c # v2
+        with:
+          shared-key: rust-ci-${{ runner.os }}
+          workspaces: . -> target
+
+      - name: Setup sccache
+        uses: mozilla-actions/sccache-action@7d986dd989559c6ecdb630a3fd2557667be217ad # v0.0.9
+
+      - name: Clippy
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: cargo clippy -p aether-gateway --lib --bins --examples -- -D warnings
+
+      - name: Show sccache stats
+        if: always()
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: sccache --show-stats
+
+  clippy_data:
+    name: Clippy (Data)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+        with:
+          toolchain: 1.95.0
+          components: clippy
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@49a0bdc70d2e1b713ca9e2869b211fcce03d3c1c # v2
+        with:
+          shared-key: rust-ci-${{ runner.os }}
+          workspaces: . -> target
+
+      - name: Setup sccache
+        uses: mozilla-actions/sccache-action@7d986dd989559c6ecdb630a3fd2557667be217ad # v0.0.9
+
+      - name: Clippy
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: cargo clippy -p aether-data --all-targets -- -D warnings
+
+      - name: Show sccache stats
+        if: always()
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: sccache --show-stats
+
+  clippy_rest:
+    name: Clippy (Workspace Rest)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+        with:
+          toolchain: 1.95.0
+          components: clippy
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@49a0bdc70d2e1b713ca9e2869b211fcce03d3c1c # v2
+        with:
+          shared-key: rust-ci-${{ runner.os }}
+          workspaces: . -> target
+
+      - name: Setup sccache
+        uses: mozilla-actions/sccache-action@7d986dd989559c6ecdb630a3fd2557667be217ad # v0.0.9
+
+      - name: Clippy
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: cargo clippy --workspace --exclude aether-gateway --exclude aether-data --exclude aether-integration-tests --all-targets -- -D warnings
+
+      - name: Show sccache stats
+        if: always()
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: sccache --show-stats
+
+  clippy:
+    name: Clippy
+    runs-on: ubuntu-latest
+    needs:
+      - clippy_gateway
+      - clippy_data
+      - clippy_rest
+    if: ${{ always() }}
+    steps:
+      - name: Verify clippy jobs
+        run: |
+          if [ "${{ needs.clippy_gateway.result }}" != "success" ] || \
+             [ "${{ needs.clippy_data.result }}" != "success" ] || \
+             [ "${{ needs.clippy_rest.result }}" != "success" ]; then
+            echo "Clippy failed"
+            exit 1
+          fi
+
+  test_gateway:
+    name: Test (Gateway)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+
+      - name: Show Rust toolchain
+        run: rustup show active-toolchain
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@49a0bdc70d2e1b713ca9e2869b211fcce03d3c1c # v2
+        with:
+          shared-key: rust-ci-${{ runner.os }}
+          workspaces: . -> target
+
+      - name: Setup sccache
+        uses: mozilla-actions/sccache-action@7d986dd989559c6ecdb630a3fd2557667be217ad # v0.0.9
+
+      - name: Setup mold
+        uses: rui314/setup-mold@7e4f20ad28a2e8ca6fd0892ccf72e2abb706b9c3 # v1
+
+      - name: Install nextest
+        uses: taiki-e/install-action@d5f9268ff7620505a81ada10ddf18cdd72240185 # nextest
+
+      - name: Expose PostgreSQL test binaries
+        run: pg_config --bindir >> "$GITHUB_PATH"
+
+      - name: Test lib
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+          RUST_MIN_STACK: "16777216"
+          RUSTFLAGS: "-C link-arg=-fuse-ld=mold"
+        run: cargo nextest run -p aether-gateway --lib
+
+      - name: Test bins
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+          RUST_MIN_STACK: "16777216"
+          RUSTFLAGS: "-C link-arg=-fuse-ld=mold"
+        run: cargo nextest run -p aether-gateway --bins
+
+      - name: Show sccache stats
+        if: always()
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: sccache --show-stats
+
+  test_data:
+    name: Test (Data)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+
+      - name: Show Rust toolchain
+        run: rustup show active-toolchain
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@49a0bdc70d2e1b713ca9e2869b211fcce03d3c1c # v2
+        with:
+          shared-key: rust-ci-${{ runner.os }}
+          workspaces: . -> target
+
+      - name: Setup sccache
+        uses: mozilla-actions/sccache-action@7d986dd989559c6ecdb630a3fd2557667be217ad # v0.0.9
+
+      - name: Install nextest
+        uses: taiki-e/install-action@d5f9268ff7620505a81ada10ddf18cdd72240185 # nextest
+
+      - name: Expose PostgreSQL test binaries
+        run: pg_config --bindir >> "$GITHUB_PATH"
+
+      - name: Test
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+          AETHER_REQUIRE_LOCAL_POSTGRES_TESTS: "true"
+        run: cargo nextest run -p aether-data
+
+      - name: Show sccache stats
+        if: always()
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: sccache --show-stats
+
+  check_data_features:
+    name: Check (Data Feature - ${{ matrix.feature }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        feature:
+          - postgres
+          - all-drivers
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@49a0bdc70d2e1b713ca9e2869b211fcce03d3c1c # v2
+        with:
+          shared-key: rust-ci-${{ runner.os }}
+          workspaces: . -> target
+
+      - name: Setup sccache
+        uses: mozilla-actions/sccache-action@7d986dd989559c6ecdb630a3fd2557667be217ad # v0.0.9
+
+      - name: Check selected data driver
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: cargo check -p aether-data --no-default-features --features ${{ matrix.feature }}
+
+      - name: Show sccache stats
+        if: always()
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: sccache --show-stats
+
+  test_rest:
+    name: Test (Workspace Rest)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+
+      - name: Show Rust toolchain
+        run: rustup show active-toolchain
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@49a0bdc70d2e1b713ca9e2869b211fcce03d3c1c # v2
+        with:
+          shared-key: rust-ci-${{ runner.os }}
+          workspaces: . -> target
+
+      - name: Setup sccache
+        uses: mozilla-actions/sccache-action@7d986dd989559c6ecdb630a3fd2557667be217ad # v0.0.9
+
+      - name: Install nextest
+        uses: taiki-e/install-action@d5f9268ff7620505a81ada10ddf18cdd72240185 # nextest
+
+      - name: Test
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: cargo nextest run --workspace --exclude aether-gateway --exclude aether-data --exclude aether-integration-tests
+
+      - name: Show sccache stats
+        if: always()
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: sccache --show-stats
+
+  test_data_adapters:
+    name: Test (Data Adapter - ${{ matrix.package }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        package:
+          - aether-data-postgres
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@49a0bdc70d2e1b713ca9e2869b211fcce03d3c1c # v2
+        with:
+          shared-key: rust-ci-${{ runner.os }}
+          workspaces: . -> target
+
+      - name: Setup sccache
+        uses: mozilla-actions/sccache-action@7d986dd989559c6ecdb630a3fd2557667be217ad # v0.0.9
+
+      - name: Install nextest
+        uses: taiki-e/install-action@d5f9268ff7620505a81ada10ddf18cdd72240185 # nextest
+
+      - name: Test adapter
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: cargo nextest run -p ${{ matrix.package }}
+
+      - name: Show sccache stats
+        if: always()
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: sccache --show-stats
+
+  check_integration_scenarios:
+    name: Test (Integration Scenarios)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@49a0bdc70d2e1b713ca9e2869b211fcce03d3c1c # v2
+        with:
+          shared-key: rust-ci-${{ runner.os }}
+          workspaces: . -> target
+
+      - name: Setup sccache
+        uses: mozilla-actions/sccache-action@7d986dd989559c6ecdb630a3fd2557667be217ad # v0.0.9
+
+      - name: Expose PostgreSQL test binaries
+        run: pg_config --bindir >> "$GITHUB_PATH"
+
+      - name: Test scenario binaries and end-to-end suites
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: cargo test -p aether-integration-tests --bins --tests
+
+      - name: Show sccache stats
+        if: always()
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: sccache --show-stats
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    needs:
+      - test_gateway
+      - test_data
+      - check_data_features
+      - test_rest
+      - test_data_adapters
+      - check_integration_scenarios
+    if: ${{ always() }}
+    steps:
+      - name: Verify test jobs
+        run: |
+          if [ "${{ needs.test_gateway.result }}" != "success" ] || \
+             [ "${{ needs.test_data.result }}" != "success" ] || \
+             [ "${{ needs.check_data_features.result }}" != "success" ] || \
+             [ "${{ needs.test_rest.result }}" != "success" ] || \
+             [ "${{ needs.test_data_adapters.result }}" != "success" ] || \
+             [ "${{ needs.check_integration_scenarios.result }}" != "success" ]; then
+            echo "Tests failed"
+            exit 1
+          fi
+
+  data_db_smoke_postgres:
+    name: Data DB Smoke (Postgres)
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_DB: aether_test
+          POSTGRES_USER: aether
+          POSTGRES_PASSWORD: aether
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready -h 127.0.0.1 -U aether -d aether_test"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=20
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+
+      - name: Show Rust toolchain
+        run: rustup show active-toolchain
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@49a0bdc70d2e1b713ca9e2869b211fcce03d3c1c # v2
+        with:
+          shared-key: rust-ci-${{ runner.os }}
+          workspaces: . -> target
+
+      - name: Setup sccache
+        uses: mozilla-actions/sccache-action@7d986dd989559c6ecdb630a3fd2557667be217ad # v0.0.9
+
+      - name: Add PostgreSQL server binaries to PATH
+        run: echo "$(pg_config --bindir)" >> "$GITHUB_PATH"
+
+      - name: Run Postgres migration smoke test
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+          AETHER_TEST_POSTGRES_URL: postgres://aether:[email protected]:5432/aether_test
+        run: cargo test -p aether-data --all-features postgres_migrations_create_core_config_tables_when_url_is_set --lib -- --nocapture
+
+      - name: Run Postgres provider metadata migration smoke test
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+          AETHER_TEST_POSTGRES_URL: postgres://aether:[email protected]:5432/aether_test
+        run: cargo test -p aether-data --all-features postgres_provider_upstream_metadata_migration_preserves_json_when_url_is_set --lib -- --nocapture
+
+      - name: Run Postgres API key lifecycle tests
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+          AETHER_REQUIRE_LOCAL_POSTGRES_TESTS: "true"
+        run: |
+          cargo test -p aether-data --all-features lifecycle::migrate::tests::postgres_request_candidates_preserve_deleted_api_key_identity --lib -- --exact --nocapture
+          cargo test -p aether-data --all-features lifecycle::migrate::tests::postgres_request_candidate_migration_decouples_legacy_api_key_foreign_key --lib -- --exact --nocapture
+          cargo test -p aether-data --all-features lifecycle::migrate::tests::postgres_stats_daily_api_key_migration_decouples_legacy_foreign_key --lib -- --exact --nocapture
+          cargo test -p aether-data --all-features lifecycle::migrate::tests::postgres_expired_api_key_cleanup_preserves_historical_identity --lib -- --exact --nocapture
+          cargo test -p aether-data --all-features lifecycle::migrate::tests::postgres_api_key_leaderboard_user_filter_preserves_aggregate_history --lib -- --exact --nocapture
+
+      - name: Run Postgres core export smoke test
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+          AETHER_TEST_POSTGRES_URL: postgres://aether:[email protected]:5432/aether_test
+        run: cargo test -p aether-data --all-features postgres_core_export_reads_migrated_database_rows_when_url_is_set --lib -- --nocapture
+
+      - name: Show sccache stats
+        if: always()
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+        run: sccache --show-stats
+
+  data_db_smoke:
+    name: Data DB Smoke
+    runs-on: ubuntu-latest
+    needs:
+      - data_db_smoke_postgres
+    if: ${{ always() }}
+    steps:
+      - name: Verify database smoke jobs
+        run: |
+          if [ "${{ needs.data_db_smoke_postgres.result }}" != "success" ]; then
+            echo "Data DB smoke failed"
+            exit 1
+          fi
+
+  check:
+    name: check
+    runs-on: ubuntu-latest
+    needs:
+      - fmt
+      - clippy
+      - test
+      - data_db_smoke
+      - shell_security
+    if: ${{ always() }}
+    steps:
+      - name: Verify required jobs
+        run: |
+          if [ "${{ needs.fmt.result }}" != "success" ] || \
+             [ "${{ needs.clippy.result }}" != "success" ] || \
+             [ "${{ needs.test.result }}" != "success" ] || \
+             [ "${{ needs.data_db_smoke.result }}" != "success" ] || \
+             [ "${{ needs.shell_security.result }}" != "success" ]; then
+            echo "Rust CI failed"
+            exit 1
+          fi

.gitignore

@@ -1,11 +1,21 @@
 # Created by https://www.toptal.com/developers/gitignore/api/python
 # Edit at https://www.toptal.com/developers/gitignore?templates=python
 
+*.rsa
+*_rsa
+
 # AI Assistant Configuration
+.codex/
 .claude/
+.deepseek/
 .serena/
 .gemini*/
 .plans
+.playwright-mcp/
+
+docs/architecture
+!docs/architecture/architecture-dark.svg
+!docs/architecture/architecture-light.svg
 
 ### Python ###
 *.db
@@ -212,6 +222,10 @@ backups/
 
 # Runtime lock files
 .locks/
+
+# Local Rust/Cargo configuration
+.cargo/
+
 # Demo and test files
 frontend/public/*-demo.html
 frontend/public/*-measure.html
@@ -226,6 +240,10 @@ test.py
 .deps-hash
 .code-hash
 .migration-hash
+.hub-hash
+
+# Hub prebuilt binaries
+aether-hub/dist/
 
 # Version file (auto-generated by hatch-vcs)
 src/_version.py
@@ -233,4 +251,6 @@ src/_version.py
 # Analysis folder (third-party code for reference)
 analysis/
 new-api/
-/aether-proxy/target/
+apps/aether-tunnel/aether-tunnel.toml
+# Generated by frontend/scripts/sync-vscodex.mjs.
+frontend/public/aether-vscodex/

.mise.toml

@@ -0,0 +1,2 @@
+[tools]
+rust = "latest"

.python-version

@@ -1 +0,0 @@
-3.13

Cargo.toml

@@ -0,0 +1,157 @@
+[workspace]
+members = [
+    "apps/aether-tunnel",
+    "crates/aether-ai/formats",
+    "crates/aether-admin",
+    "crates/aether-admission-core",
+    "crates/aether-ai/serving",
+    "crates/aether-pool-core",
+    "crates/aether-provider/core",
+    "crates/aether-provider/pool",
+    "crates/aether-routing-core",
+    "crates/aether-data/contracts",
+    "crates/aether-data/adapters/postgres",
+    "crates/aether-data/query",
+    "crates/aether-data/schema",
+    "crates/aether-dispatch-core",
+    "crates/aether-cache",
+    "crates/aether-billing",
+    "crates/aether-wallet",
+    "crates/aether-crypto",
+    "crates/aether-contracts",
+    "crates/aether-data/runtime",
+    "crates/aether-model-fetch",
+    "crates/aether-oauth",
+    "crates/aether-provider/transport",
+    "crates/aether-scheduler-core",
+    "crates/aether-runtime/state",
+    "crates/aether-task/runtime",
+    "crates/aether-task/core",
+    "crates/aether-gateway/frontdoor",
+    "crates/aether-gateway/control",
+    "crates/aether-gateway/execution",
+    "crates/aether-gateway/workers",
+    "crates/aether-gateway/tunnel",
+    "crates/aether-testing/loadtools",
+    "crates/aether-testing/integration",
+    "crates/aether-usage/core",
+    "crates/aether-testing/support",
+    "crates/aether-usage/runtime",
+    "crates/aether-video-tasks-core",
+    "apps/aether-gateway",
+    "crates/aether-http",
+    "crates/aether-runtime/base",
+    "crates/aether-testing/testkit",
+]
+default-members = [
+    "apps/aether-gateway",
+]
+resolver = "2"
+
+[workspace.package]
+edition = "2021"
+license = "LicenseRef-Aether-NonCommercial"
+repository = "https://github.com/fawney19/Aether.git"
+
+[workspace.dependencies]
+aether-admin = { path = "crates/aether-admin" }
+aether-admission-core = { path = "crates/aether-admission-core" }
+aether-ai-formats = { path = "crates/aether-ai/formats" }
+aether-ai-serving = { path = "crates/aether-ai/serving" }
+aether-pool-core = { path = "crates/aether-pool-core" }
+aether-provider-core = { path = "crates/aether-provider/core" }
+aether-provider-pool = { path = "crates/aether-provider/pool" }
+aether-routing-core = { path = "crates/aether-routing-core" }
+aether-data-contracts = { path = "crates/aether-data/contracts" }
+aether-data-postgres = { path = "crates/aether-data/adapters/postgres" }
+aether-data-query = { path = "crates/aether-data/query" }
+aether-data-schema = { path = "crates/aether-data/schema" }
+aether-dispatch-core = { path = "crates/aether-dispatch-core" }
+aether-cache = { path = "crates/aether-cache" }
+aether-billing = { path = "crates/aether-billing" }
+aether-wallet = { path = "crates/aether-wallet" }
+aether-crypto = { path = "crates/aether-crypto" }
+aether-contracts = { path = "crates/aether-contracts" }
+aether-data = { path = "crates/aether-data/runtime" }
+aether-model-fetch = { path = "crates/aether-model-fetch" }
+aether-oauth = { path = "crates/aether-oauth" }
+aether-provider-transport = { path = "crates/aether-provider/transport" }
+aether-scheduler-core = { path = "crates/aether-scheduler-core" }
+aether-runtime-state = { path = "crates/aether-runtime/state" }
+aether-task-runtime = { path = "crates/aether-task/runtime" }
+aether-task-core = { path = "crates/aether-task/core" }
+aether-gateway-frontdoor = { path = "crates/aether-gateway/frontdoor" }
+aether-gateway-control = { path = "crates/aether-gateway/control" }
+aether-gateway-execution = { path = "crates/aether-gateway/execution" }
+aether-gateway-workers = { path = "crates/aether-gateway/workers" }
+aether-gateway-tunnel = { path = "crates/aether-gateway/tunnel" }
+aether-loadtools = { path = "crates/aether-testing/loadtools" }
+aether-integration-tests = { path = "crates/aether-testing/integration" }
+aether-test-support = { path = "crates/aether-testing/support" }
+aether-usage-core = { path = "crates/aether-usage/core" }
+aether-usage-runtime = { path = "crates/aether-usage/runtime" }
+aether-video-tasks-core = { path = "crates/aether-video-tasks-core" }
+aether-gateway = { path = "apps/aether-gateway" }
+aether-http = { path = "crates/aether-http" }
+aether-runtime = { path = "crates/aether-runtime/base" }
+aether-testkit = { path = "crates/aether-testing/testkit" }
+aes = "0.8"
+aes-gcm = "0.10"
+aws-lc-rs = { version = "1.16.2", default-features = false, features = ["alloc", "aws-lc-sys"] }
+async-stream = "0.3"
+async-trait = "0.1"
+axum = "0.8"
+base64 = "0.22"
+bcrypt = "0.16"
+brotli = "8"
+bytes = "1"
+cbc = "0.1"
+chrono = { version = "0.4", features = ["serde"] }
+chrono-tz = "0.10"
+crypto_box = { version = "0.9", features = ["seal"] }
+ed25519-dalek = { version = "2.2", features = ["pkcs8"] }
+flate2 = "1"
+futures-util = "0.3"
+hmac = "0.12"
+http = "1"
+object_store = { version = "0.14.1", default-features = false, features = ["aws"] }
+pbkdf2 = { version = "0.12", default-features = false, features = ["hmac"] }
+percent-encoding = "2"
+reqwest = { version = "0.12", default-features = false, features = ["json", "stream", "rustls-tls", "http2", "socks"] }
+redis = { version = "0.28", default-features = false, features = ["tokio-comp", "script", "streams", "connection-manager"] }
+regex = "1"
+rustls = { version = "0.23", features = ["ring"] }
+semver = "1"
+serde = { version = "1", features = ["derive"] }
+serde_json = { version = "1", features = ["preserve_order"] }
+serde_path_to_error = "0.1"
+sha2 = "0.10"
+socket2 = "0.6"
+tar = "0.4"
+sqlx = { version = "0.8", default-features = false, features = ["runtime-tokio-rustls", "chrono"] }
+thiserror = "2"
+tokio = { version = "1", features = ["macros", "net", "rt-multi-thread", "signal", "sync", "time"] }
+tokio-util = { version = "0.7", features = ["codec", "io-util"] }
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
+uuid = { version = "1", features = ["serde", "v4", "v5", "v7"] }
+webpki-roots = "0.26"
+wreq = { version = "6.0.0-rc.28", default-features = false, features = ["json", "stream", "socks", "webpki-roots", "ws"] }
+wreq-util = "3.0.0-rc.10"
+url = "2"
+zstd = "0.13"
+
+[profile.dev]
+# Keep file/line information for backtraces while avoiding full debug info
+# generation on very large crates during local development builds.
+debug = "line-tables-only"
+
+[profile.test]
+# The gateway test target pulls in a very large in-crate test tree, so use the
+# lighter debug format here as well to reduce rustc peak memory.
+debug = "line-tables-only"
+
+[profile.release]
+lto = "thin"
+strip = true
+codegen-units = 8

Dockerfile.app

@@ -1,159 +1,48 @@
 # syntax=docker/dockerfile:1
-# 运行镜像：从 base 提取产物到精简运行时
-# 构建命令: docker build -f Dockerfile.app -t aether-app:latest .
-# 用于 GitHub Actions CI（官方源）
-FROM aether-base:latest AS builder
-WORKDIR /app
-# 复制前端源码并构建（CI 通过 no-cache-filters=builder 确保每次重建）
-COPY frontend/ ./frontend/
-RUN cd frontend && npm run build
-# ==================== 运行时镜像 ====================
-FROM python:3.13-slim
-WORKDIR /app
-# 运行时依赖（无 gcc/nodejs/npm，使用 BuildKit 缓存加速）
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
-    --mount=type=cache,target=/var/lib/apt,sharing=locked \
-    apt-get update && apt-get install -y --no-install-recommends \
-    nginx \
-    supervisor \
-    libpq5 \
-    curl
-# 从 base 镜像复制 Python 包
-COPY --from=builder /usr/local/lib/python3.13/site-packages /usr/local/lib/python3.13/site-packages
-# 只复制需要的 Python 可执行文件
-COPY --from=builder /usr/local/bin/gunicorn /usr/local/bin/
-COPY --from=builder /usr/local/bin/uvicorn /usr/local/bin/
-COPY --from=builder /usr/local/bin/alembic /usr/local/bin/
-# 从 builder 阶段复制前端构建产物
-COPY --from=builder /app/frontend/dist /usr/share/nginx/html
-RUN chmod -R 755 /usr/share/nginx/html
-# 复制后端代码
-COPY src/ ./src/
-COPY alembic.ini ./
-COPY alembic/ ./alembic/
-COPY gunicorn_conf.py ./
-# Nginx 配置模板
-# 策略：白名单后端路由 → 后端代理，其余全部 → 前端 SPA（index.html）
-# 智能处理 IP：有外层代理头就透传，没有就用直连 IP
-RUN printf '%s\n' \
-    'map $http_x_real_ip $real_ip {' \
-    '    default $http_x_real_ip;' \
-    '    ""      $remote_addr;' \
-    '}' \
-    '' \
-    'map $http_x_forwarded_for $forwarded_for {' \
-    '    default $http_x_forwarded_for;' \
-    '    ""      $remote_addr;' \
-    '}' \
-    '' \
-    'server {' \
-    '    listen 80;' \
-    '    server_name _;' \
-    '    root /usr/share/nginx/html;' \
-    '    index index.html;' \
-    '    client_max_body_size 100M;' \
-    '' \
-    '    # gzip 压缩配置（对 base64 图片等非流式响应有效）' \
-    '    gzip on;' \
-    '    gzip_min_length 256;' \
-    '    gzip_comp_level 5;' \
-    '    gzip_vary on;' \
-    '    gzip_proxied any;' \
-    '    gzip_types application/json text/plain text/css text/javascript application/javascript application/octet-stream;' \
-    '    gzip_disable "msie6";' \
-    '' \
-    '    # 静态资源：长期缓存' \
-    '    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {' \
-    '        expires 1y;' \
-    '        add_header Cache-Control "public, no-transform";' \
-    '        try_files $uri =404;' \
-    '    }' \
-    '' \
-    '    # 安全：阻止访问源码目录' \
-    '    location ~ ^/(src|node_modules)/ {' \
-    '        deny all;' \
-    '        return 404;' \
-    '    }' \
-    '' \
-    '    # 后端 API 路由（白名单）→ 代理到后端' \
-    '    location ~ ^/(api|v1|v1beta|upload|health)(/|$) {' \
-    '        proxy_pass http://127.0.0.1:PORT_PLACEHOLDER;' \
-    '        proxy_http_version 1.1;' \
-    '        proxy_set_header Host $host;' \
-    '        proxy_set_header X-Real-IP $real_ip;' \
-    '        proxy_set_header X-Forwarded-For $forwarded_for;' \
-    '        proxy_set_header X-Forwarded-Proto $scheme;' \
-    '        proxy_set_header Connection "";' \
-    '        proxy_set_header Accept $http_accept;' \
-    '        proxy_set_header Content-Type $content_type;' \
-    '        proxy_set_header Authorization $http_authorization;' \
-    '        proxy_set_header X-Api-Key $http_x_api_key;' \
-    '        proxy_buffering off;' \
-    '        proxy_cache off;' \
-    '        proxy_request_buffering off;' \
-    '        chunked_transfer_encoding on;' \
-    '        gzip off;' \
-    '        add_header X-Accel-Buffering no;' \
-    '        proxy_connect_timeout 60s;' \
-    '        proxy_send_timeout 3600s;' \
-    '        proxy_read_timeout 3600s;' \
-    '    }' \
-    '' \
-    '    # API 文档路由 → 代理到后端' \
-    '    location ~ ^/(docs|redoc|openapi\\.json)$ {' \
-    '        proxy_pass http://127.0.0.1:PORT_PLACEHOLDER;' \
-    '        proxy_http_version 1.1;' \
-    '        proxy_set_header Host $host;' \
-    '        proxy_set_header X-Real-IP $real_ip;' \
-    '        proxy_set_header X-Forwarded-For $forwarded_for;' \
-    '        proxy_set_header X-Forwarded-Proto $scheme;' \
-    '    }' \
-    '' \
-    '    # 所有其他路由 → 前端 SPA（先尝试静态文件，再回退到 index.html）' \
-    '    location / {' \
-    '        try_files $uri $uri/ /index.html;' \
-    '    }' \
-    '}' > /etc/nginx/sites-available/default.template
-# Supervisor 配置
-RUN printf '%s\n' \
-    '[supervisord]' \
-    'nodaemon=true' \
-    'logfile=/var/log/supervisor/supervisord.log' \
-    'pidfile=/var/run/supervisord.pid' \
-    '' \
-    '[program:nginx]' \
-    'command=/bin/bash -c "sed \"s/PORT_PLACEHOLDER/8084/g\" /etc/nginx/sites-available/default.template > /etc/nginx/sites-available/default && /usr/sbin/nginx -g \"daemon off;\""' \
-    'autostart=true' \
-    'autorestart=true' \
-    'stdout_logfile=/var/log/nginx/access.log' \
-    'stderr_logfile=/var/log/nginx/error.log' \
-    '' \
-    '[program:app]' \
-    'command=/bin/bash -c "MAX_REQUESTS_JITTER=$((${MAX_REQUESTS:-4000}/20)); exec gunicorn src.main:app -c gunicorn_conf.py --preload -w %(ENV_GUNICORN_WORKERS)s -k uvicorn.workers.UvicornWorker --bind 127.0.0.1:8084 --timeout 120 --max-requests ${MAX_REQUESTS:-4000} --max-requests-jitter $MAX_REQUESTS_JITTER --access-logfile - --error-logfile - --log-level info"' \
-    'directory=/app' \
-    'autostart=true' \
-    'autorestart=true' \
-    'stdout_logfile=/dev/stdout' \
-    'stdout_logfile_maxbytes=0' \
-    'stderr_logfile=/dev/stderr' \
-    'stderr_logfile_maxbytes=0' \
-    'environment=PYTHONUNBUFFERED=1,PYTHONIOENCODING=utf-8,LANG=C.UTF-8,LC_ALL=C.UTF-8,DOCKER_CONTAINER=true' > /etc/supervisor/conf.d/supervisord.conf
-# 创建目录
-RUN mkdir -p /var/log/supervisor /app/logs /app/data
-# 入口脚本（启动前执行迁移）
-COPY entrypoint.sh /entrypoint.sh
-RUN chmod +x /entrypoint.sh
-# 环境变量
-ENV PYTHONUNBUFFERED=1 \
-    PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONIOENCODING=utf-8 \
-    LANG=C.UTF-8 \
-    LC_ALL=C.UTF-8 \
-    PORT=8084 \
-    GUNICORN_WORKERS=4 \
-    MAX_REQUESTS=4000
-EXPOSE 80
+# Aether Gateway runtime image (cross-compilation)
+# Binary and frontend assets are pre-built by CI; this Dockerfile only packages them.
+# Usage: docker buildx build --platform linux/amd64,linux/arm64 -f Dockerfile.app .
+#
+# Build context must contain:
+#   dist/aether-gateway-amd64   (x86_64-unknown-linux-musl cross-compiled binary)
+#   dist/aether-gateway-arm64   (aarch64-unknown-linux-musl cross-compiled binary)
+#   dist/frontend/              (npm run build output)
+
+# --- layout stage: create /opt/aether directory structure with symlink ---
+# distroless has no shell, so we use busybox to set up the symlink.
+FROM busybox:1.37.0-musl@sha256:fc6dddc4c44b1bfe37f41cae8e67d1693828e8f42a91862816d7953e2c9d3f23 AS layout
+
+ARG TARGETARCH
+
+RUN mkdir -p /opt/aether/releases/image/bin /opt/aether/releases/image/frontend /opt/aether/logs
+
+COPY dist/aether-gateway-${TARGETARCH} /opt/aether/releases/image/bin/aether-gateway
+COPY dist/frontend/ /opt/aether/releases/image/frontend/
+
+# Keep the immutable release root-owned while guaranteeing that the runtime
+# identity can traverse and read every packaged asset.
+RUN chmod -R u=rwX,go=rX /opt/aether/releases/image \
+    && chmod 0755 /opt/aether/releases/image/bin/aether-gateway
+
+RUN ln -s /opt/aether/releases/image /opt/aether/current
+
+# --- final stage: distroless runtime ---
+FROM gcr.io/distroless/static-debian12@sha256:6447365a6337c3732f412d1b74357b30a633831955b2bc45552b0086be907687
+
+COPY --from=layout /opt/aether /opt/aether
+
+WORKDIR /opt/aether
+
+ENV RUST_LOG=aether_gateway=info \
+    APP_PORT=8084 \
+    HOME=/tmp/aether-home \
+    AETHER_UPDATE_STRATEGY=docker \
+    AETHER_GATEWAY_STATIC_DIR=/opt/aether/current/frontend
+
+EXPOSE 8084
+
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
-    CMD curl -f http://localhost/health || exit 1
-ENTRYPOINT ["/entrypoint.sh"]
-CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]
+    CMD ["/opt/aether/current/bin/aether-gateway", "--healthcheck"]
+
+USER 0:0
+ENTRYPOINT ["/opt/aether/current/bin/aether-gateway"]

Dockerfile.app.local

@@ -1,177 +1,161 @@
-# syntax=docker/dockerfile:1
-# 运行镜像：从 base 提取产物到精简运行时（国内镜像源版本）
-# 构建命令: docker build -f Dockerfile.app.local -t aether-app:latest .
-# 用于本地/国内服务器部署
-FROM aether-base:latest AS builder
+# syntax=docker.m.daocloud.io/docker/dockerfile:1
+# Aether 运行镜像：Rust gateway 直接服务 API + 前端静态文件（国内镜像源版本）
+# 构建命令: docker build --build-arg AETHER_BUILD_VERSION=v0.7.2 -f Dockerfile.app.local -t aether-app:latest .
 
-WORKDIR /app
+ARG RUST_VERSION=1.95.0
+ARG NODE_BASE_IMAGE=docker.m.daocloud.io/library/node:22-slim
+ARG RUST_BASE_IMAGE=docker.m.daocloud.io/library/rust:${RUST_VERSION}-slim
 
-# 复制前端源码并构建
-COPY frontend/ ./frontend/
-RUN cd frontend && npm run build
+# ==================== 前端构建 ====================
+FROM ${NODE_BASE_IMAGE} AS frontend-builder
+ARG AETHER_BUILD_VERSION
+ENV AETHER_BUILD_VERSION=${AETHER_BUILD_VERSION} \
+    AETHER_VERSION=${AETHER_BUILD_VERSION}
+WORKDIR /app/aether-vscodex/web
+COPY aether-vscodex/web/package*.json ./
+RUN --mount=type=cache,id=aether-vscodex-npm-cache,target=/root/.npm,sharing=locked \
+    npm config set registry https://registry.npmmirror.com && \
+    npm ci --no-audit --no-fund
+COPY aether-vscodex/public /app/aether-vscodex/public
+COPY aether-vscodex/web/ ./
+RUN npm run build
 
-# ==================== 运行时镜像 ====================
-FROM python:3.13-slim
+WORKDIR /app/frontend
+COPY frontend/package*.json ./
+RUN --mount=type=cache,id=aether-npm-cache,target=/root/.npm,sharing=locked \
+    npm config set registry https://registry.npmmirror.com && \
+    npm ci --no-audit --no-fund
+COPY frontend/ ./
+RUN npm run build
 
-WORKDIR /app
+# ==================== Rust gateway 构建 ====================
+FROM ${RUST_BASE_IMAGE} AS gateway-base
+WORKDIR /build
+
+# 生产级 release 构建：保留 thin LTO，同时用 lld 缩短最终链接阶段。
+ENV CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse \
+    CARGO_PROFILE_RELEASE_LTO=thin \
+    CARGO_PROFILE_RELEASE_CODEGEN_UNITS=16 \
+    RUSTFLAGS="-C linker=clang -C link-arg=-fuse-ld=lld"
 
-# 运行时依赖（使用清华镜像源 + BuildKit 缓存加速）
 RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
     --mount=type=cache,target=/var/lib/apt,sharing=locked \
     sed -i 's/deb.debian.org/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list.d/debian.sources && \
     apt-get update && apt-get install -y --no-install-recommends \
-    nginx \
-    supervisor \
-    libpq5 \
-    curl
+    build-essential \
+    ca-certificates \
+    clang \
+    cmake \
+    git \
+    libclang-dev \
+    libssl-dev \
+    lld \
+    pkg-config \
+    perl
 
-# 从 base 镜像复制 Python 包
-COPY --from=builder /usr/local/lib/python3.13/site-packages /usr/local/lib/python3.13/site-packages
+RUN --mount=type=cache,id=aether-cargo-registry,target=/usr/local/cargo/registry,sharing=locked \
+    --mount=type=cache,id=aether-cargo-git,target=/usr/local/cargo/git,sharing=locked \
+    cargo install cargo-chef --locked
 
-# 只复制需要的 Python 可执行文件
-COPY --from=builder /usr/local/bin/gunicorn /usr/local/bin/
-COPY --from=builder /usr/local/bin/uvicorn /usr/local/bin/
-COPY --from=builder /usr/local/bin/alembic /usr/local/bin/
+FROM gateway-base AS gateway-planner
+COPY Cargo.toml Cargo.lock ./
+COPY apps/ ./apps/
+COPY crates/ ./crates/
+RUN cargo chef prepare --recipe-path recipe.json
 
-# 从 builder 阶段复制前端构建产物
-COPY --from=builder /app/frontend/dist /usr/share/nginx/html
-RUN chmod -R 755 /usr/share/nginx/html
+FROM gateway-base AS gateway-builder
+ARG AETHER_BUILD_VERSION
+ENV AETHER_BUILD_VERSION=${AETHER_BUILD_VERSION} \
+    AETHER_VERSION=${AETHER_BUILD_VERSION}
+COPY --from=gateway-planner /build/recipe.json ./recipe.json
+RUN --mount=type=cache,id=aether-cargo-registry,target=/usr/local/cargo/registry,sharing=locked \
+    --mount=type=cache,id=aether-cargo-git,target=/usr/local/cargo/git,sharing=locked \
+    --mount=type=cache,id=aether-cargo-target-local,target=/build/target,sharing=locked \
+    cargo chef cook --release --locked --package aether-gateway --bin aether-gateway --features jemalloc --recipe-path recipe.json
 
-# 复制后端代码
-COPY src/ ./src/
-COPY alembic.ini ./
-COPY alembic/ ./alembic/
-COPY gunicorn_conf.py ./
+COPY Cargo.toml Cargo.lock ./
+COPY apps/ ./apps/
+COPY crates/ ./crates/
+RUN --mount=type=cache,id=aether-cargo-registry,target=/usr/local/cargo/registry,sharing=locked \
+    --mount=type=cache,id=aether-cargo-git,target=/usr/local/cargo/git,sharing=locked \
+    --mount=type=cache,id=aether-cargo-target-local,target=/build/target,sharing=locked \
+    set -eux; \
+    cargo build --release --locked -p aether-gateway --bin aether-gateway --features jemalloc; \
+    cp target/release/aether-gateway /tmp/aether-gateway
 
-# Nginx 配置模板
-# 策略：白名单后端路由 → 后端代理，其余全部 → 前端 SPA（index.html）
-# 智能处理 IP：有外层代理头就透传，没有就用直连 IP
-RUN printf '%s\n' \
-    'map $http_x_real_ip $real_ip {' \
-    '    default $http_x_real_ip;' \
-    '    ""      $remote_addr;' \
-    '}' \
-    '' \
-    'map $http_x_forwarded_for $forwarded_for {' \
-    '    default $http_x_forwarded_for;' \
-    '    ""      $remote_addr;' \
-    '}' \
-    '' \
-    'server {' \
-    '    listen 80;' \
-    '    server_name _;' \
-    '    root /usr/share/nginx/html;' \
-    '    index index.html;' \
-    '    client_max_body_size 100M;' \
-    '' \
-    '    # gzip 压缩配置（对 base64 图片等非流式响应有效）' \
-    '    gzip on;' \
-    '    gzip_min_length 256;' \
-    '    gzip_comp_level 5;' \
-    '    gzip_vary on;' \
-    '    gzip_proxied any;' \
-    '    gzip_types application/json text/plain text/css text/javascript application/javascript application/octet-stream;' \
-    '    gzip_disable "msie6";' \
-    '' \
-    '    # 静态资源：长期缓存' \
-    '    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {' \
-    '        expires 1y;' \
-    '        add_header Cache-Control "public, no-transform";' \
-    '        try_files $uri =404;' \
-    '    }' \
-    '' \
-    '    # 安全：阻止访问源码目录' \
-    '    location ~ ^/(src|node_modules)/ {' \
-    '        deny all;' \
-    '        return 404;' \
-    '    }' \
-    '' \
-    '    # 后端 API 路由（白名单）→ 代理到后端' \
-    '    location ~ ^/(api|v1|v1beta|upload|health)(/|$) {' \
-    '        proxy_pass http://127.0.0.1:PORT_PLACEHOLDER;' \
-    '        proxy_http_version 1.1;' \
-    '        proxy_set_header Host $host;' \
-    '        proxy_set_header X-Real-IP $real_ip;' \
-    '        proxy_set_header X-Forwarded-For $forwarded_for;' \
-    '        proxy_set_header X-Forwarded-Proto $scheme;' \
-    '        proxy_set_header Connection "";' \
-    '        proxy_set_header Accept $http_accept;' \
-    '        proxy_set_header Content-Type $content_type;' \
-    '        proxy_set_header Authorization $http_authorization;' \
-    '        proxy_set_header X-Api-Key $http_x_api_key;' \
-    '        proxy_buffering off;' \
-    '        proxy_cache off;' \
-    '        proxy_request_buffering off;' \
-    '        chunked_transfer_encoding on;' \
-    '        gzip off;' \
-    '        add_header X-Accel-Buffering no;' \
-    '        proxy_connect_timeout 60s;' \
-    '        proxy_send_timeout 3600s;' \
-    '        proxy_read_timeout 3600s;' \
-    '    }' \
-    '' \
-    '    # API 文档路由 → 代理到后端' \
-    '    location ~ ^/(docs|redoc|openapi\\.json)$ {' \
-    '        proxy_pass http://127.0.0.1:PORT_PLACEHOLDER;' \
-    '        proxy_http_version 1.1;' \
-    '        proxy_set_header Host $host;' \
-    '        proxy_set_header X-Real-IP $real_ip;' \
-    '        proxy_set_header X-Forwarded-For $forwarded_for;' \
-    '        proxy_set_header X-Forwarded-Proto $scheme;' \
-    '    }' \
-    '' \
-    '    # 所有其他路由 → 前端 SPA（先尝试静态文件，再回退到 index.html）' \
-    '    location / {' \
-    '        try_files $uri $uri/ /index.html;' \
-    '    }' \
-    '}' > /etc/nginx/sites-available/default.template
+# ==================== 最小运行时打包 ====================
+FROM gateway-builder AS runtime-prep
+RUN set -eux; \
+    mkdir -p \
+    /runtime-root/app/data \
+    /runtime-root/app/logs \
+    /runtime-root/etc \
+    /runtime-root/etc/ssl \
+    /runtime-root/lib \
+    /runtime-root/lib64 \
+    /runtime-root/usr/local/bin; \
+    cp /tmp/aether-gateway /runtime-root/usr/local/bin/aether-gateway; \
+    : > /tmp/runtime-libs.txt; \
+    : > /tmp/runtime-scan-queue.txt; \
+    printf '%s\n' /tmp/aether-gateway >> /tmp/runtime-scan-queue.txt; \
+    while [ -s /tmp/runtime-scan-queue.txt ]; do \
+        current="$(head -n1 /tmp/runtime-scan-queue.txt)"; \
+        sed -i '1d' /tmp/runtime-scan-queue.txt; \
+        ldd "$current" | awk '/=>/ { print $3 } $1 ~ /^\// { print $1 }' | while read -r lib; do \
+            [ -n "$lib" ]; \
+            if ! grep -Fxq "$lib" /tmp/runtime-libs.txt; then \
+                printf '%s\n' "$lib" >> /tmp/runtime-libs.txt; \
+                printf '%s\n' "$lib" >> /tmp/runtime-scan-queue.txt; \
+            fi; \
+        done; \
+    done; \
+    sort -u /tmp/runtime-libs.txt -o /tmp/runtime-libs.txt; \
+    while read -r lib; do \
+        [ -n "$lib" ]; \
+        dest="/runtime-root$(dirname "$lib")"; \
+        mkdir -p "$dest"; \
+        cp -L "$lib" "$dest/"; \
+    done < /tmp/runtime-libs.txt; \
+    for lib in \
+        /lib/x86_64-linux-gnu/libnss_dns.so.2 \
+        /lib/x86_64-linux-gnu/libnss_files.so.2 \
+        /lib/x86_64-linux-gnu/libresolv.so.2; do \
+        if [ -f "$lib" ]; then \
+            dest="/runtime-root$(dirname "$lib")"; \
+            mkdir -p "$dest"; \
+            cp -L "$lib" "$dest/"; \
+        fi; \
+    done; \
+    cp -a /usr/lib/ssl /runtime-root/usr/lib/; \
+    cp -a /etc/ssl/certs /runtime-root/etc/ssl/; \
+    if [ -f /etc/ssl/openssl.cnf ]; then \
+        cp /etc/ssl/openssl.cnf /runtime-root/etc/ssl/openssl.cnf; \
+    fi; \
+    if [ -f /etc/nsswitch.conf ]; then \
+        cp /etc/nsswitch.conf /runtime-root/etc/nsswitch.conf; \
+    fi
 
-# Supervisor 配置
-RUN printf '%s\n' \
-    '[supervisord]' \
-    'nodaemon=true' \
-    'logfile=/var/log/supervisor/supervisord.log' \
-    'pidfile=/var/run/supervisord.pid' \
-    '' \
-    '[program:nginx]' \
-    'command=/bin/bash -c "sed \"s/PORT_PLACEHOLDER/${PORT:-8084}/g\" /etc/nginx/sites-available/default.template > /etc/nginx/sites-available/default && /usr/sbin/nginx -g \"daemon off;\""' \
-    'autostart=true' \
-    'autorestart=true' \
-    'stdout_logfile=/var/log/nginx/access.log' \
-    'stderr_logfile=/var/log/nginx/error.log' \
-    '' \
-    '[program:app]' \
-    'command=/bin/bash -c "MAX_REQUESTS_JITTER=$((${MAX_REQUESTS:-4000}/20)); exec gunicorn src.main:app -c gunicorn_conf.py --preload -w %(ENV_GUNICORN_WORKERS)s -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:%(ENV_PORT)s --timeout 120 --max-requests ${MAX_REQUESTS:-4000} --max-requests-jitter $MAX_REQUESTS_JITTER --access-logfile - --error-logfile - --log-level info"' \
-    'directory=/app' \
-    'autostart=true' \
-    'autorestart=true' \
-    'stdout_logfile=/dev/stdout' \
-    'stdout_logfile_maxbytes=0' \
-    'stderr_logfile=/dev/stderr' \
-    'stderr_logfile_maxbytes=0' \
-    'environment=PYTHONUNBUFFERED=1,PYTHONIOENCODING=utf-8,LANG=C.UTF-8,LC_ALL=C.UTF-8,DOCKER_CONTAINER=true' > /etc/supervisor/conf.d/supervisord.conf
+# ==================== 运行时镜像 ====================
+FROM scratch
 
-# 创建目录
-RUN mkdir -p /var/log/supervisor /app/logs /app/data
+# 复制 gateway 二进制
+COPY --from=runtime-prep /runtime-root/ /
 
-# 入口脚本（启动前执行迁移）
-COPY entrypoint.sh /entrypoint.sh
-RUN sed -i 's/\r$//' /entrypoint.sh && chmod +x /entrypoint.sh
+# 复制前端构建产物
+COPY --from=frontend-builder /app/frontend/dist /srv/frontend
+WORKDIR /app
 
-# 环境变量
-ENV PYTHONUNBUFFERED=1 \
-    PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONIOENCODING=utf-8 \
-    LANG=C.UTF-8 \
+ENV LANG=C.UTF-8 \
     LC_ALL=C.UTF-8 \
-    PORT=8084 \
-    GUNICORN_WORKERS=4 \
-    MAX_REQUESTS=4000
+    RUST_LOG=aether_gateway=info \
+    APP_PORT=8084 \
+    AETHER_UPDATE_STRATEGY=manual \
+    AETHER_GATEWAY_STATIC_DIR=/srv/frontend
 
-EXPOSE 80
+EXPOSE 8084
 
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
-    CMD curl -f http://localhost/health || exit 1
+    CMD ["/usr/local/bin/aether-gateway", "--healthcheck"]
 
-ENTRYPOINT ["/entrypoint.sh"]
-CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]
+USER 0:0
+ENTRYPOINT ["/usr/local/bin/aether-gateway"]

Dockerfile.app.release-local

@@ -0,0 +1,160 @@
+# syntax=docker.m.daocloud.io/docker/dockerfile:1
+# Aether 本地发布版联调镜像
+# 作用：用当前源码构建一个 release-layout 容器，专门测试管理后台在线更新流程。
+
+ARG RUST_VERSION=1.95.0
+ARG NODE_BASE_IMAGE=docker.m.daocloud.io/library/node:22-slim
+ARG RUST_BASE_IMAGE=docker.m.daocloud.io/library/rust:${RUST_VERSION}-slim
+
+# ==================== 前端构建 ====================
+FROM ${NODE_BASE_IMAGE} AS frontend-builder
+ARG AETHER_BUILD_VERSION
+ENV AETHER_BUILD_VERSION=${AETHER_BUILD_VERSION} \
+    AETHER_VERSION=${AETHER_BUILD_VERSION}
+WORKDIR /app/aether-vscodex/web
+COPY aether-vscodex/web/package*.json ./
+RUN --mount=type=cache,id=aether-vscodex-npm-cache,target=/root/.npm,sharing=locked \
+    npm config set registry https://registry.npmmirror.com && \
+    npm ci --no-audit --no-fund
+COPY aether-vscodex/public /app/aether-vscodex/public
+COPY aether-vscodex/web/ ./
+RUN npm run build
+
+WORKDIR /app/frontend
+COPY frontend/package*.json ./
+RUN --mount=type=cache,id=aether-npm-cache,target=/root/.npm,sharing=locked \
+    npm config set registry https://registry.npmmirror.com && \
+    npm ci --no-audit --no-fund
+COPY frontend/ ./
+RUN npm run build
+
+# ==================== Rust gateway 构建 ====================
+FROM ${RUST_BASE_IMAGE} AS gateway-base
+WORKDIR /build
+
+ENV CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse \
+    CARGO_PROFILE_RELEASE_LTO=thin \
+    CARGO_PROFILE_RELEASE_CODEGEN_UNITS=16
+
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    sed -i 's/deb.debian.org/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list.d/debian.sources && \
+    apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    ca-certificates \
+    cmake \
+    git \
+    libclang-dev \
+    libssl-dev \
+    pkg-config \
+    perl
+
+RUN --mount=type=cache,id=aether-cargo-registry,target=/usr/local/cargo/registry,sharing=locked \
+    --mount=type=cache,id=aether-cargo-git,target=/usr/local/cargo/git,sharing=locked \
+    cargo install cargo-chef --locked
+
+FROM gateway-base AS gateway-planner
+COPY Cargo.toml Cargo.lock ./
+COPY apps/ ./apps/
+COPY crates/ ./crates/
+RUN cargo chef prepare --recipe-path recipe.json
+
+FROM gateway-base AS gateway-builder
+ARG AETHER_BUILD_VERSION
+ARG AETHER_BUILD_TYPE=release
+ENV AETHER_BUILD_VERSION=${AETHER_BUILD_VERSION} \
+    AETHER_VERSION=${AETHER_BUILD_VERSION} \
+    AETHER_BUILD_TYPE=${AETHER_BUILD_TYPE}
+COPY --from=gateway-planner /build/recipe.json ./recipe.json
+RUN --mount=type=cache,id=aether-cargo-registry,target=/usr/local/cargo/registry,sharing=locked \
+    --mount=type=cache,id=aether-cargo-git,target=/usr/local/cargo/git,sharing=locked \
+    --mount=type=cache,id=aether-cargo-target-release-local,target=/build/target,sharing=locked \
+    cargo chef cook --release --locked --package aether-gateway --bin aether-gateway --features jemalloc --recipe-path recipe.json
+
+COPY Cargo.toml Cargo.lock ./
+COPY apps/ ./apps/
+COPY crates/ ./crates/
+RUN --mount=type=cache,id=aether-cargo-registry,target=/usr/local/cargo/registry,sharing=locked \
+    --mount=type=cache,id=aether-cargo-git,target=/usr/local/cargo/git,sharing=locked \
+    --mount=type=cache,id=aether-cargo-target-release-local,target=/build/target,sharing=locked \
+    cargo build --release --locked -p aether-gateway --features jemalloc && \
+    cp target/release/aether-gateway /tmp/aether-gateway
+
+# ==================== 最小运行时打包 ====================
+FROM gateway-builder AS runtime-prep
+RUN set -eux; \
+    mkdir -p \
+    /runtime-root/app/data \
+    /runtime-root/etc \
+    /runtime-root/etc/ssl \
+    /runtime-root/lib \
+    /runtime-root/lib64 \
+    /runtime-root/usr/lib \
+    /runtime-root/opt/aether/logs \
+    /runtime-root/opt/aether/releases/image/bin \
+    /runtime-root/opt/aether/releases/image/frontend; \
+    cp /tmp/aether-gateway /runtime-root/opt/aether/releases/image/bin/aether-gateway; \
+    ln -s /opt/aether/releases/image /runtime-root/opt/aether/current; \
+    : > /tmp/runtime-libs.txt; \
+    : > /tmp/runtime-scan-queue.txt; \
+    printf '%s\n' /tmp/aether-gateway >> /tmp/runtime-scan-queue.txt; \
+    while [ -s /tmp/runtime-scan-queue.txt ]; do \
+        current="$(head -n1 /tmp/runtime-scan-queue.txt)"; \
+        sed -i '1d' /tmp/runtime-scan-queue.txt; \
+        ldd "$current" | awk '/=>/ { print $3 } $1 ~ /^\// { print $1 }' | while read -r lib; do \
+            [ -n "$lib" ]; \
+            if ! grep -Fxq "$lib" /tmp/runtime-libs.txt; then \
+                printf '%s\n' "$lib" >> /tmp/runtime-libs.txt; \
+                printf '%s\n' "$lib" >> /tmp/runtime-scan-queue.txt; \
+            fi; \
+        done; \
+    done; \
+    sort -u /tmp/runtime-libs.txt -o /tmp/runtime-libs.txt; \
+    while read -r lib; do \
+        [ -n "$lib" ]; \
+        dest="/runtime-root$(dirname "$lib")"; \
+        mkdir -p "$dest"; \
+        cp -L "$lib" "$dest/"; \
+    done < /tmp/runtime-libs.txt; \
+    for lib in \
+        /lib/x86_64-linux-gnu/libnss_dns.so.2 \
+        /lib/x86_64-linux-gnu/libnss_files.so.2 \
+        /lib/x86_64-linux-gnu/libresolv.so.2; do \
+        if [ -f "$lib" ]; then \
+            dest="/runtime-root$(dirname "$lib")"; \
+            mkdir -p "$dest"; \
+            cp -L "$lib" "$dest/"; \
+        fi; \
+    done; \
+    cp -a /usr/lib/ssl /runtime-root/usr/lib/; \
+    cp -a /etc/ssl/certs /runtime-root/etc/ssl/; \
+    if [ -f /etc/ssl/openssl.cnf ]; then \
+        cp /etc/ssl/openssl.cnf /runtime-root/etc/ssl/openssl.cnf; \
+    fi; \
+    if [ -f /etc/nsswitch.conf ]; then \
+        cp /etc/nsswitch.conf /runtime-root/etc/nsswitch.conf; \
+    fi
+COPY --from=frontend-builder /app/frontend/dist /runtime-root/opt/aether/releases/image/frontend
+
+# ==================== 运行时镜像 ====================
+FROM scratch
+
+COPY --from=runtime-prep /runtime-root/ /
+
+WORKDIR /app
+
+ENV LANG=C.UTF-8 \
+    LC_ALL=C.UTF-8 \
+    RUST_LOG=aether_gateway=info \
+    APP_PORT=8084 \
+    AETHER_BASE_DIR=/opt/aether \
+    AETHER_UPDATE_STRATEGY=self \
+    AETHER_GATEWAY_STATIC_DIR=/opt/aether/current/frontend
+
+EXPOSE 8084
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD ["/opt/aether/current/bin/aether-gateway", "--healthcheck"]
+
+USER 0:0
+ENTRYPOINT ["/opt/aether/current/bin/aether-gateway"]

Dockerfile.base

@@ -1,28 +0,0 @@
-# syntax=docker/dockerfile:1
-# 构建镜像：编译环境 + 预编译的依赖
-# 用于 GitHub Actions CI 构建（不使用国内镜像源）
-# 构建命令: docker build -f Dockerfile.base -t aether-base:latest .
-# 只在 pyproject.toml 或 frontend/package*.json 变化时需要重建
-FROM python:3.13-slim
-
-WORKDIR /app
-
-# 构建工具（使用 BuildKit 缓存加速）
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
-    --mount=type=cache,target=/var/lib/apt,sharing=locked \
-    apt-get update && apt-get install -y --no-install-recommends \
-    libpq-dev \
-    gcc \
-    nodejs \
-    npm
-
-# Python 依赖（使用 BuildKit 缓存加速）
-COPY pyproject.toml README.md ./
-RUN --mount=type=cache,target=/root/.cache/pip \
-    mkdir -p src && touch src/__init__.py && \
-    SETUPTOOLS_SCM_PRETEND_VERSION=0.1.0 pip install .
-
-# 前端依赖（只安装，不构建，使用 BuildKit 缓存加速）
-COPY frontend/package*.json ./frontend/
-RUN --mount=type=cache,target=/root/.npm \
-    cd frontend && npm ci

Dockerfile.base.local

@@ -1,31 +0,0 @@
-# syntax=docker/dockerfile:1
-# 构建镜像：编译环境 + 预编译的依赖（国内镜像源版本）
-# 构建命令: docker build -f Dockerfile.base.local -t aether-base:latest .
-# 只在 pyproject.toml 或 frontend/package*.json 变化时需要重建
-FROM python:3.13-slim
-
-WORKDIR /app
-
-# 构建工具（使用清华镜像源 + BuildKit 缓存加速）
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
-    --mount=type=cache,target=/var/lib/apt,sharing=locked \
-    sed -i 's/deb.debian.org/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list.d/debian.sources && \
-    apt-get update && apt-get install -y --no-install-recommends \
-    libpq-dev \
-    gcc \
-    nodejs \
-    npm
-
-# pip 镜像源
-RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
-
-# Python 依赖（使用 BuildKit 缓存加速）
-COPY pyproject.toml README.md ./
-RUN --mount=type=cache,target=/root/.cache/pip \
-    mkdir -p src && touch src/__init__.py && \
-    SETUPTOOLS_SCM_PRETEND_VERSION=0.1.0 pip install .
-
-# 前端依赖（只安装，不构建，使用淘宝镜像源 + BuildKit 缓存加速）
-COPY frontend/package*.json ./frontend/
-RUN --mount=type=cache,target=/root/.npm \
-    cd frontend && npm config set registry https://registry.npmmirror.com && npm ci

Makefile

@@ -0,0 +1,582 @@
+SHELL := /bin/bash
+
+DEV_RUST_LOG := info,executor::candidate_loop=debug,stream::execution=debug
+ifeq ($(origin RUST_LOG), command line)
+DEV_RUST_LOG := $(RUST_LOG)
+endif
+export DEV_RUST_LOG
+
+.PHONY: dev dev-backend dev-frontend db-status db-prepare migration backfill
+
+define DEV_BACKEND_SCRIPT
+set -euo pipefail
+
+if [ ! -f .env ]; then
+	echo "=> 未找到 .env，请先执行: cp .env.example .env"
+	exit 1
+fi
+
+set -a
+source .env
+set +a
+
+if [[ -n "$${ADMIN_EMAIL:-}" || -n "$${ADMIN_USERNAME:-}" || -n "$${ADMIN_PASSWORD:-}" ]]; then
+	if [[ -z "$${ADMIN_USERNAME:-}" || -z "$${ADMIN_PASSWORD:-}" ]]; then
+		echo "=> 管理员自举配置不完整，请在 .env 中设置 ADMIN_USERNAME 和 ADMIN_PASSWORD"
+		exit 1
+	fi
+fi
+
+dotenv_has_key() {
+	local key="$$1"
+	grep -Eq "^[[:space:]]*$${key}=" .env
+}
+
+lowercase() {
+	printf '%s' "$$1" | tr '[:upper:]' '[:lower:]'
+}
+
+dev_uses_postgres_database() {
+	local driver
+	local url
+	driver="$$(lowercase "$${AETHER_DATABASE_DRIVER:-}")"
+	url="$${AETHER_DATABASE_URL:-$${DATABASE_URL:-}}"
+
+	if [[ -z "$${driver}" && -z "$${url}" ]]; then
+		return 0
+	fi
+
+	[[ "$${driver}" == "postgres" || "$${driver}" == "postgresql" || "$${url}" == postgres:* || "$${url}" == postgresql:* ]]
+}
+
+dev_uses_redis_runtime() {
+	local backend
+	backend="$$(lowercase "$${AETHER_RUNTIME_BACKEND:-}")"
+
+	if [[ "$${backend}" == "memory" ]]; then
+		return 1
+	fi
+	if [[ "$${backend}" == "redis" ]]; then
+		return 0
+	fi
+
+	return 0
+}
+
+print_dev_infra_hint() {
+	echo "=> 本地开发依赖未就绪。"
+	echo "=> 可手动启动 Postgres / Redis:"
+	echo "=>   docker compose up -d postgres redis"
+}
+
+check_postgres_ready() {
+	local host="$$1"
+	local port="$$2"
+
+	if command -v pg_isready >/dev/null 2>&1; then
+		pg_isready -h "$${host}" -p "$${port}" >/dev/null 2>&1
+		return $$?
+	fi
+
+	if command -v nc >/dev/null 2>&1; then
+		nc -z "$${host}" "$${port}" >/dev/null 2>&1
+		return $$?
+	fi
+
+	return 0
+}
+
+check_redis_ready() {
+	local host="$$1"
+	local port="$$2"
+	local password="$$3"
+
+	if command -v redis-cli >/dev/null 2>&1; then
+		REDISCLI_AUTH="$${password}" redis-cli -h "$${host}" -p "$${port}" ping >/dev/null 2>&1
+		return $$?
+	fi
+
+	if command -v nc >/dev/null 2>&1; then
+		nc -z "$${host}" "$${port}" >/dev/null 2>&1
+		return $$?
+	fi
+
+	return 0
+}
+
+is_local_host() {
+	case "$$1" in
+		localhost|127.0.0.1|::1)
+			return 0
+			;;
+	esac
+
+	return 1
+}
+
+ensure_dev_infra() {
+	local postgres_host="$${DB_HOST:-localhost}"
+	local postgres_port="$${DB_PORT:-5432}"
+	local redis_host="$${REDIS_HOST:-localhost}"
+	local redis_port="$${REDIS_PORT:-6379}"
+	local redis_password="$${REDIS_PASSWORD:-}"
+	local need_postgres=false
+	local need_redis=false
+	local services=()
+
+	if dev_uses_postgres_database; then
+		if ! check_postgres_ready "$${postgres_host}" "$${postgres_port}"; then
+			if is_local_host "$${postgres_host}"; then
+				need_postgres=true
+				services+=(postgres)
+			else
+				echo "=> PostgreSQL 不可用: $${postgres_host}:$${postgres_port}"
+				print_dev_infra_hint
+				return 1
+			fi
+		fi
+	fi
+
+	if dev_uses_redis_runtime; then
+		if ! check_redis_ready "$${redis_host}" "$${redis_port}" "$${redis_password}"; then
+			if is_local_host "$${redis_host}"; then
+				need_redis=true
+				services+=(redis)
+			else
+				echo "=> Redis 不可用: $${redis_host}:$${redis_port}"
+				print_dev_infra_hint
+				return 1
+			fi
+		fi
+	fi
+
+	if [ "$${#services[@]}" -eq 0 ]; then
+		return 0
+	fi
+
+	if ! command -v docker >/dev/null 2>&1; then
+		echo "=> 未找到 docker，无法自动启动本地开发依赖。"
+		print_dev_infra_hint
+		return 1
+	fi
+
+	echo "=> 本地开发依赖未就绪，正在启动: docker compose up -d $${services[*]}"
+	if ! docker compose up -d "$${services[@]}"; then
+		echo "=> docker compose 启动本地开发依赖失败。"
+		print_dev_infra_hint
+		return 1
+	fi
+
+	for _ in {1..100}; do
+		local ready=true
+		if [ "$${need_postgres}" = "true" ] && ! check_postgres_ready "$${postgres_host}" "$${postgres_port}"; then
+			ready=false
+		fi
+		if [ "$${need_redis}" = "true" ] && ! check_redis_ready "$${redis_host}" "$${redis_port}" "$${redis_password}"; then
+			ready=false
+		fi
+		if [ "$${ready}" = "true" ]; then
+			return 0
+		fi
+		sleep 0.2
+	done
+
+	if [ "$${need_postgres}" = "true" ] && ! check_postgres_ready "$${postgres_host}" "$${postgres_port}"; then
+		echo "=> PostgreSQL 不可用: $${postgres_host}:$${postgres_port}"
+	fi
+	if [ "$${need_redis}" = "true" ] && ! check_redis_ready "$${redis_host}" "$${redis_port}" "$${redis_password}"; then
+		echo "=> Redis 不可用: $${redis_host}:$${redis_port}"
+	fi
+	print_dev_infra_hint
+	return 1
+}
+
+print_startup_failure_hint() {
+	local log_file="$$1"
+
+	if [ -n "$${log_file}" ] && [ -f "$${log_file}" ]; then
+		if grep -Eq "database schema is behind" "$${log_file}"; then
+			echo "=> 检测到数据库尚未准备完成，请执行: make db-prepare"
+			return
+		fi
+
+		if grep -Eq "database backfills are behind" "$${log_file}"; then
+			echo "=> 检测到数据库尚未准备完成，请执行: make db-prepare"
+			return
+		fi
+
+		if grep -Eq "bootstrap admin env is partially configured.*ADMIN_PASSWORD" "$${log_file}"; then
+			echo "=> 首次启动需要管理员密码，请在 .env 中设置 ADMIN_PASSWORD"
+			return
+		fi
+	fi
+
+	echo "=> 未识别到明确的修复动作，请根据上面的日志继续排查。"
+}
+
+wait_for_startup() {
+	local pid="$$1"
+	local timeout_seconds="$$2"
+	local service_name="$$3"
+	shift 3
+
+	STARTUP_WAIT_EARLY_EXIT=false
+
+	local attempts=$$((timeout_seconds * 10))
+	if [ "$${attempts}" -lt 1 ]; then
+		attempts=1
+	fi
+
+	for ((i = 0; i < attempts; i++)); do
+		if "$$@" >/dev/null 2>&1; then
+			return 0
+		fi
+
+		if ! kill -0 "$${pid}" >/dev/null 2>&1; then
+			STARTUP_WAIT_EARLY_EXIT=true
+			echo "=> $${service_name} 启动进程已提前退出，请检查上面的日志。"
+			print_startup_failure_hint "$${GATEWAY_LOG_FILE}"
+			return 1
+		fi
+
+		sleep 0.1
+	done
+
+	if "$$@" >/dev/null 2>&1; then
+		return 0
+	fi
+
+	if ! kill -0 "$${pid}" >/dev/null 2>&1; then
+		STARTUP_WAIT_EARLY_EXIT=true
+		echo "=> $${service_name} 启动进程已提前退出，请检查上面的日志。"
+		print_startup_failure_hint "$${GATEWAY_LOG_FILE}"
+		return 1
+	fi
+
+	echo "=> $${service_name} 在 $${timeout_seconds}s 内未通过启动检查。"
+	echo "=> 如果这是冷编译或存在并发 cargo 构建，可调大启动超时后重试。"
+	return 1
+}
+
+create_gateway_log_file() {
+	local tmp_root="$${TMPDIR:-/tmp}"
+	tmp_root="$${tmp_root%/}"
+
+	GATEWAY_LOG_DIR="$$(mktemp -d "$${tmp_root}/aether-dev-startup.XXXXXX")"
+	GATEWAY_LOG_FILE="$${GATEWAY_LOG_DIR}/gateway.log"
+	: > "$${GATEWAY_LOG_FILE}"
+}
+
+cleanup() {
+	local status="$${1:-0}"
+	trap - INT TERM EXIT
+
+	if [ -n "$${GATEWAY_PID:-}" ]; then
+		echo ""
+		echo "=> 停止 aether-gateway..."
+		kill "$${GATEWAY_PID}" >/dev/null 2>&1 || true
+		wait "$${GATEWAY_PID}" >/dev/null 2>&1 || true
+	fi
+
+	if [ -n "$${GATEWAY_LOG_FILE:-}" ] && [ -f "$${GATEWAY_LOG_FILE}" ]; then
+		rm -f "$${GATEWAY_LOG_FILE}"
+	fi
+
+	if [ -n "$${GATEWAY_LOG_DIR:-}" ] && [ -d "$${GATEWAY_LOG_DIR}" ]; then
+		rmdir "$${GATEWAY_LOG_DIR}" >/dev/null 2>&1 || true
+	fi
+
+	exit "$${status}"
+}
+
+trap 'cleanup 130' INT
+trap 'cleanup 143' TERM
+trap 'cleanup $$?' EXIT
+
+export APP_PORT="$${APP_PORT:-8084}"
+export RUST_LOG="$${DEV_RUST_LOG}"
+RUST_SERVICE_STARTUP_TIMEOUT_SECONDS="$${RUST_SERVICE_STARTUP_TIMEOUT_SECONDS:-180}"
+GATEWAY_STARTUP_TIMEOUT_SECONDS="$${GATEWAY_STARTUP_TIMEOUT_SECONDS:-$${RUST_SERVICE_STARTUP_TIMEOUT_SECONDS}}"
+export AETHER_GATEWAY_VIDEO_TASK_TRUTH_SOURCE_MODE="$${AETHER_GATEWAY_VIDEO_TASK_TRUTH_SOURCE_MODE:-rust-authoritative}"
+
+if dev_uses_postgres_database; then
+	export DATABASE_URL="postgresql://$${DB_USER:-postgres}:$${DB_PASSWORD:-}@$${DB_HOST:-localhost}:$${DB_PORT:-5432}/$${DB_NAME:-aether}"
+	if ! dotenv_has_key "AETHER_GATEWAY_DATA_POSTGRES_URL"; then
+		export AETHER_GATEWAY_DATA_POSTGRES_URL="$${DATABASE_URL}"
+	fi
+fi
+
+if dev_uses_redis_runtime; then
+	export REDIS_URL="redis://:$${REDIS_PASSWORD:-}@$${REDIS_HOST:-localhost}:$${REDIS_PORT:-6379}/0"
+	if ! dotenv_has_key "AETHER_GATEWAY_DATA_REDIS_URL"; then
+		export AETHER_GATEWAY_DATA_REDIS_URL="$${REDIS_URL}"
+	fi
+else
+	unset REDIS_URL
+	unset AETHER_GATEWAY_DATA_REDIS_URL
+fi
+
+if ! dotenv_has_key "AETHER_GATEWAY_DATA_ENCRYPTION_KEY"; then
+	export AETHER_GATEWAY_DATA_ENCRYPTION_KEY="$${ENCRYPTION_KEY:-}"
+fi
+
+export DB_POOL_SIZE="$${DB_POOL_SIZE:-5}"
+export DB_MAX_OVERFLOW="$${DB_MAX_OVERFLOW:-5}"
+export HTTP_MAX_CONNECTIONS="$${HTTP_MAX_CONNECTIONS:-20}"
+export HTTP_KEEPALIVE_CONNECTIONS="$${HTTP_KEEPALIVE_CONNECTIONS:-5}"
+
+if ! command -v cargo >/dev/null 2>&1; then
+	echo "=> 未找到 cargo，无法启动 aether-gateway。请先安装 Rust toolchain。"
+	exit 1
+fi
+
+if ! command -v curl >/dev/null 2>&1; then
+	echo "=> 未找到 curl，无法检查 aether-gateway 健康状态。请先安装 curl。"
+	exit 1
+fi
+
+if [ -z "$${RUSTC_WRAPPER:-}" ] && command -v sccache >/dev/null 2>&1; then
+	export RUSTC_WRAPPER="$$(command -v sccache)"
+	echo "=> 启用 Rust 编译缓存: $${RUSTC_WRAPPER}"
+fi
+
+if ! ensure_dev_infra; then
+	exit 1
+fi
+
+echo "=> 编译 aether-gateway..."
+cargo build -p aether-gateway --bin aether-gateway
+
+GATEWAY_PID=""
+GATEWAY_LOG_DIR=""
+GATEWAY_LOG_FILE=""
+STARTUP_WAIT_EARLY_EXIT=false
+create_gateway_log_file
+
+echo "=> 启动 aether-gateway (Rust frontdoor: 0.0.0.0:$${APP_PORT})..."
+echo "=> 日志过滤: $${RUST_LOG}"
+echo "=> 执行命令: target/debug/aether-gateway --app-port $${APP_PORT}"
+target/debug/aether-gateway --app-port "$${APP_PORT}" > >(
+	tee -a "$${GATEWAY_LOG_FILE}"
+) 2>&1 &
+GATEWAY_PID=$$!
+
+if ! wait_for_startup "$${GATEWAY_PID}" "$${GATEWAY_STARTUP_TIMEOUT_SECONDS}" "aether-gateway" curl -sf "http://127.0.0.1:$${APP_PORT}/_gateway/health"; then
+	if [ "$${STARTUP_WAIT_EARLY_EXIT}" = "true" ]; then
+		GATEWAY_PID=""
+	fi
+	exit 1
+fi
+
+if wait "$${GATEWAY_PID}"; then
+	gateway_exit_code=0
+else
+	gateway_exit_code=$$?
+fi
+
+GATEWAY_PID=""
+
+if [ "$${gateway_exit_code}" -ne 130 ] && [ "$${gateway_exit_code}" -ne 143 ]; then
+	echo "=> aether-gateway 运行失败并已退出，请检查上面的日志。"
+	print_startup_failure_hint "$${GATEWAY_LOG_FILE}"
+fi
+
+exit "$${gateway_exit_code}"
+endef
+export DEV_BACKEND_SCRIPT
+
+define DEV_SCRIPT
+set -euo pipefail
+
+backend_pid=""
+frontend_pid=""
+
+cleanup() {
+	local status="$${1:-0}"
+	trap - INT TERM EXIT
+
+	if [ -n "$${backend_pid}" ] || [ -n "$${frontend_pid}" ]; then
+		echo ""
+		echo "=> 停止本地开发服务..."
+		if [ -n "$${backend_pid}" ]; then
+			kill "$${backend_pid}" >/dev/null 2>&1 || true
+			wait "$${backend_pid}" >/dev/null 2>&1 || true
+		fi
+		if [ -n "$${frontend_pid}" ]; then
+			kill "$${frontend_pid}" >/dev/null 2>&1 || true
+			wait "$${frontend_pid}" >/dev/null 2>&1 || true
+		fi
+	fi
+
+	exit "$${status}"
+}
+
+wait_for_backend_ready() {
+	while :; do
+		if curl -sf "http://127.0.0.1:$${APP_PORT}/_gateway/health" >/dev/null 2>&1; then
+			return 0
+		fi
+
+		if ! kill -0 "$${backend_pid}" >/dev/null 2>&1; then
+			if wait "$${backend_pid}"; then
+				status=0
+			else
+				status=$$?
+			fi
+			if [ "$${status}" -ne 0 ]; then
+				echo "=> 后端进程已退出 (status $${status})"
+			else
+				echo "=> 后端进程已退出"
+			fi
+			backend_pid=""
+			cleanup "$${status}"
+		fi
+
+		sleep 0.2
+	done
+}
+
+trap 'cleanup 130' INT
+trap 'cleanup 143' TERM
+trap 'cleanup $$?' EXIT
+
+if [ -f .env ]; then
+	set -a
+	source .env
+	set +a
+fi
+export APP_PORT="$${APP_PORT:-8084}"
+
+echo "=> 启动后端: 先编译 aether-gateway，再运行 target/debug/aether-gateway --app-port $${APP_PORT:-8084}"
+/bin/bash -euo pipefail -c "$$DEV_BACKEND_SCRIPT" &
+backend_pid=$$!
+
+echo "=> 等待后端健康检查: http://127.0.0.1:$${APP_PORT}/_gateway/health"
+wait_for_backend_ready
+
+echo "=> 启动前端: cd frontend && npm run dev"
+( cd frontend && exec npm run dev ) &
+frontend_pid=$$!
+
+while :; do
+	if ! kill -0 "$${backend_pid}" >/dev/null 2>&1; then
+		if wait "$${backend_pid}"; then
+			status=0
+		else
+			status=$$?
+		fi
+		if [ "$${status}" -ne 0 ]; then
+			echo "=> 后端进程已退出 (status $${status})"
+		else
+			echo "=> 后端进程已退出"
+		fi
+		backend_pid=""
+		cleanup "$${status}"
+	fi
+
+	if ! kill -0 "$${frontend_pid}" >/dev/null 2>&1; then
+		if wait "$${frontend_pid}"; then
+			status=0
+		else
+			status=$$?
+		fi
+		if [ "$${status}" -ne 0 ]; then
+			echo "=> 前端进程已退出 (status $${status})"
+		else
+			echo "=> 前端进程已退出"
+		fi
+		frontend_pid=""
+		cleanup "$${status}"
+	fi
+
+	sleep 1
+done
+endef
+export DEV_SCRIPT
+
+define DB_TASK_SCRIPT
+set -euo pipefail
+
+if [ -z "$${DB_TASK_COMMAND:-}" ] || [ -z "$${DB_TASK_LABEL:-}" ]; then
+	echo "=> 内部错误: DB_TASK_COMMAND / DB_TASK_LABEL 未设置"
+	exit 1
+fi
+
+read -r -a db_task_args <<< "$${DB_TASK_COMMAND}"
+if [ "$${#db_task_args[@]}" -eq 0 ]; then
+	echo "=> 内部错误: DB_TASK_COMMAND 为空"
+	exit 1
+fi
+
+if [ ! -f .env ]; then
+	echo "=> 未找到 .env，请先执行: cp .env.example .env"
+	exit 1
+fi
+
+set -a
+source .env
+set +a
+
+dotenv_has_key() {
+	local key="$$1"
+	grep -Eq "^[[:space:]]*$${key}=" .env
+}
+
+lowercase() {
+	printf '%s' "$$1" | tr '[:upper:]' '[:lower:]'
+}
+
+uses_postgres_database() {
+	local driver
+	local url
+	driver="$$(lowercase "$${AETHER_DATABASE_DRIVER:-}")"
+	url="$${AETHER_DATABASE_URL:-$${DATABASE_URL:-}}"
+
+	if [[ -z "$${driver}" && -z "$${url}" ]]; then
+		return 0
+	fi
+
+	[[ "$${driver}" == "postgres" || "$${driver}" == "postgresql" || "$${url}" == postgres:* || "$${url}" == postgresql:* ]]
+}
+
+if uses_postgres_database; then
+	export DATABASE_URL="postgresql://$${DB_USER:-postgres}:$${DB_PASSWORD:-}@$${DB_HOST:-localhost}:$${DB_PORT:-5432}/$${DB_NAME:-aether}"
+	if ! dotenv_has_key "AETHER_GATEWAY_DATA_POSTGRES_URL"; then
+		export AETHER_GATEWAY_DATA_POSTGRES_URL="$${DATABASE_URL}"
+	fi
+fi
+
+if ! dotenv_has_key "AETHER_GATEWAY_DATA_ENCRYPTION_KEY"; then
+	export AETHER_GATEWAY_DATA_ENCRYPTION_KEY="$${ENCRYPTION_KEY:-}"
+fi
+
+if ! command -v cargo >/dev/null 2>&1; then
+	echo "=> 未找到 cargo，无法执行 $${DB_TASK_LABEL}。请先安装 Rust toolchain。"
+	exit 1
+fi
+
+echo "=> 执行 $${DB_TASK_LABEL}: cargo run -p aether-gateway --bin aether-gateway -- $${db_task_args[*]}"
+exec cargo run -p aether-gateway --bin aether-gateway -- "$${db_task_args[@]}"
+endef
+export DB_TASK_SCRIPT
+
+dev:
+	@$(SHELL) -euo pipefail -c "$$DEV_SCRIPT"
+
+dev-backend:
+	@$(SHELL) -euo pipefail -c "$$DEV_BACKEND_SCRIPT"
+
+dev-frontend:
+	@cd frontend && npm run dev
+
+db-status:
+	@DB_TASK_COMMAND="db status" DB_TASK_LABEL="数据库状态检查" $(SHELL) -euo pipefail -c "$$DB_TASK_SCRIPT"
+
+db-prepare:
+	@DB_TASK_COMMAND="db prepare" DB_TASK_LABEL="数据库准备" $(SHELL) -euo pipefail -c "$$DB_TASK_SCRIPT"
+
+migration:
+	@DB_TASK_COMMAND="--migrate" DB_TASK_LABEL="数据库迁移" $(SHELL) -euo pipefail -c "$$DB_TASK_SCRIPT"
+
+backfill:
+	@DB_TASK_COMMAND="--apply-backfills" DB_TASK_LABEL="数据库 backfill" $(SHELL) -euo pipefail -c "$$DB_TASK_SCRIPT"

README.md

@@ -11,6 +11,7 @@
 <p align="center">
   <a href="#简介">简介</a> •
   <a href="#部署">部署</a> •
+  <a href="#api-文档">API 文档</a> •
   <a href="#环境变量">环境变量</a> •
   <a href="#qa">Q&A</a>
 </p>
@@ -22,6 +23,14 @@
 
 Aether 是一个自托管的 AI API 网关，为团队和个人提供多租户管理、智能负载均衡、成本配额控制和健康监控能力。通过统一的 API 入口，可以无缝对接 Claude、OpenAI、Gemini 等主流 AI 服务及其 CLI 工具。
 
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/architecture/architecture-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/architecture/architecture-light.svg">
+    <img src="docs/architecture/architecture-light.svg" width="680" alt="Aether Architecture">
+  </picture>
+</p>
+
 页面预览: https://fawney19.github.io/Aether/
 
 ## 部署
@@ -35,125 +44,121 @@ cd Aether
 
 # 2. 配置环境变量
 cp .env.example .env
-python generate_keys.py  # 生成密钥, 并将生成的密钥填入 .env
+# .env 包含数据库、JWT 和数据加密密钥，先限制为仅当前用户可读写
+chmod 600 .env
+# 生成 JWT / 加密 / Postgres / Redis 独立随机密钥，并填入 .env
+./generate_keys.sh
+# 编辑 .env 设置 ADMIN_PASSWORD
 
-# 3. 部署 / 更新（自动执行数据库迁移）
+# 3. Docker 部署 / 更新（PostgreSQL + Redis）
 docker compose pull && docker compose up -d
-
-# 4. 升级前备份
-docker compose exec postgres pg_dump -U postgres aether | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz
 ```
 
-### Docker Compose（本地构建镜像）
+### 一键安装（PostgreSQL + Redis）
 
 ```bash
-# 1. 克隆代码
 git clone https://github.com/fawney19/Aether.git
 cd Aether
-
-# 2. 配置环境变量
-cp .env.example .env
-python generate_keys.py  # 生成密钥, 并将生成的密钥填入 .env
-
-# 3. 部署 / 更新（自动构建、启动、迁移）
-./deploy.sh
+curl -fsSL https://raw.githubusercontent.com/fawney19/Aether/main/install.sh | sudo bash -s -- --mode compose
 ```
 
-### 本地开发
+原生 Linux systemd / macOS launchd 安装需先准备 PostgreSQL，将连接串通过 `DATABASE_URL` 传给安装进程，并选择 `--mode single-node`；不再自动创建本地数据库文件。
+
+### Nightly（每日 main 构建）
+
+Nightly workflow 每天从 `main` 的固定 commit 构建并发布滚动的 GitHub Release `nightly`，同时推送多架构 GHCR 镜像 `ghcr.io/fawney19/aether:nightly`。Nightly 是预发布版本，适合验证最新代码，不保证与正式版相同的稳定性。滚动 Release 需要仓库保持关闭 GitHub Release immutability。
+
+安装最新 nightly（PostgreSQL + Redis）：
 
 ```bash
-# 启动依赖
-docker compose -f docker-compose.build.yml up -d postgres redis
-
-# 后端
-uv sync
-./dev.sh
-
-# 前端
-cd frontend && npm install && npm run dev
+curl -fsSL https://raw.githubusercontent.com/fawney19/Aether/main/install.sh | sudo bash -s -- --mode compose --channel nightly
 ```
 
-## Aether Proxy
+Docker Compose 用户可在部署目录的 `.env` 中设置 `APP_IMAGE=ghcr.io/fawney19/aether:nightly`，然后运行 `./update.sh` 获取下一次 nightly。二进制部署请沿用已有 PostgreSQL 环境配置，并使用 `--mode single-node --channel nightly` 重新运行安装脚本升级；当前管理后台的在线更新列表只跟踪正式版/RC/Beta，不会自动提示下一次 nightly。
 
-Aether Proxy 是配套的正向代理节点，部署在海外 VPS 上，为墙内的 Aether 实例中转 API 流量。支持 TUI 向导一键配置、systemd 服务管理、TLS 加密、DNS 缓存及连接池调优。
+## 本地开发
+
+依赖 Docker、Rust toolchain、Node.js 和 make。
+首次启动前需要在 `.env` 中设置 `ADMIN_PASSWORD`，用于创建本地管理员。
+
+```bash
+make dev
+```
+
+`make dev` 会同时启动后端 `aether-gateway` 和前端 `frontend` 的 Vite dev server。需要单独启动时可使用 `make dev-backend` 或 `make dev-frontend`。
+Postgres / Redis 本地依赖未就绪时，`make dev` 会自动执行 `docker compose up -d postgres redis`。
+`make dev` 会先完成后端编译，再开始计算服务健康检查超时。数据库 schema 和必要的派生数据准备也会在启动时自动完成；通常不需要手动区分 migration 与 backfill。升级不会主动重写或清除已有业务历史记录，新写入会直接遵循当前的数据持久化策略。排查或部署前预执行时可使用：
+
+```bash
+make db-status
+make db-prepare
+```
+
+## Codex 远程协同
+
+`aether-vscodex/` 是独立的 VS Code Codex 协同模块：同步模式跟随 VS Code 官方 Codex 面板当前会话且不另起进程；异步模式使用独立 app-server，让浏览器自行列出、恢复、新建和切换会话。两种模式都能从本机 URL 或 Aether 云端查看输出、发送消息和处理授权，模块内的 Vue 前端提供中英文界面。
+
+安装、云端配对和安全边界请参阅 [`aether-vscodex/README.md`](aether-vscodex/README.md)。
+
+## Aether Tunnel (可选)
+
+Aether Tunnel 是配套的正向代理节点，部署在海外 VPS 上，为墙内的 Aether 实例中转 API 流量。
 
 - Docker Compose 部署或下载预编译二进制直接运行
-- 通过 `aether-proxy setup` 完成交互式配置，自动注册为系统服务
-- 详细文档见 [aether-proxy/README.md](aether-proxy/README.md)
+- 提供 macOS/Linux 与 Windows 一键脚本，自动下载最新 `tunnel-v*` 制品并向现有 `aether-tunnel.toml` 追加 `[[servers]]`
+- 通过 `aether-tunnel setup` 完成交互式配置，自动注册为系统服务
+- 详细文档见 [apps/aether-tunnel/README.md](apps/aether-tunnel/README.md)
+
+## API 文档
+
+- Embeddings: [OpenAI compatible `POST /v1/embeddings`](docs/api/embeddings.md)
+- Rerank: [OpenAI/Jina compatible `POST /v1/rerank`](docs/api/rerank.md)
+- Responses WebSocket mode: [protocol and Aether behavior](docs/WebSocket-Mode.md)
+- WebSocket probes: [Codex](docs/operations/codex-responses-websocket-probe.md) · [OpenAI Responses](docs/operations/openai-responses-websocket-probe.md)
 
 ## 环境变量
 
-### 必需配置
+- `APP_PORT`：`aether-gateway` 唯一监听端口，固定绑定 `0.0.0.0:${APP_PORT}`
+- `DATABASE_URL`：PostgreSQL 连接串，例如 `postgresql://USER:PASSWORD@HOST:5432/aether`
+- `AETHER_GATEWAY_DATA_POSTGRES_MIN_CONNECTIONS` / `AETHER_GATEWAY_DATA_POSTGRES_MAX_CONNECTIONS`：数据库连接池手动覆盖值；未配置时 PostgreSQL 按每核 `4` 条自动推导，总池范围为 `32-100`。该预算按进程计算，多实例部署应按数据库连接上限显式分配
+- `AETHER_GATEWAY_MAX_IN_FLIGHT_REQUESTS`：单实例请求并发上限；未配置时按 CPU 自动推导（基础范围 `512-65536`），低文件描述符预算时会进一步下调
+- `AETHER_GATEWAY_REQUEST_BODY_BUFFER_BUDGET_MB`：单实例同时读取和解压请求体的加权内存预算，默认 `256MB`
+- `AETHER_GATEWAY_REQUEST_BODY_READ_TIMEOUT_MS`：可选的请求体完整读取超时；默认或显式设为 `0` 时关闭，非零值限制在 `1000-600000ms`
+- `AETHER_MAX_REQUEST_BODY_MB`：单请求解压后请求体上限，默认 `256MB`；显式设为 `0` 表示不再收紧默认值，但仍受 `256MB` 安全硬上限约束
+- `AETHER_MAX_INTERNAL_BUFFERED_BODY_MB`：heartbeat、管理探测等内部整包响应体上限，默认 `64MB`；显式设为 `0` 表示不再收紧默认值，但仍受 `256MB` 安全硬上限约束
+- `AETHER_TUNNEL_NODE_STATUS_QUEUE_CAPACITY`：隧道节点状态上报队列容量，默认 `1024`；满载时拒绝新事件，避免控制面故障导致无界内存增长
+- `AETHER_TUNNEL_RELAY_ALLOW_PRIVATE_TARGETS`：跨网关 owner relay 解析到私有/保留地址时的显式运维开关，默认关闭；仅当多网关 relay URL 是受控的内网 HTTPS 地址时设置为 `true`。它不改变普通 provider 请求的 DNS/代理策略，也不允许明文 HTTP 非 loopback relay
+- `AETHER_TUNNEL_RELAY_PRIVATE_HOST_ALLOWLIST`：更窄的 owner relay 私网例外，填写逗号分隔的精确主机名（例如 `gateway-a.internal,gateway-b.internal`，忽略大小写和末尾点）；仅这些主机解析出的私有地址会被允许，并且请求仍使用解析后地址 pin。不要填写通配符或 `.internal` 这类后缀
+- `AETHER_INTERNAL_GATEWAY_AUTH_SECRET`：旧版 `/api/internal/gateway/*` 高权限控制面的独立 HMAC 密钥，至少 `32` 字节；未配置时该控制面返回 `404`。不要复用 JWT、数据加密或 tunnel relay 密钥，多节点必须使用同一值及共享 Redis 防重放
+- `AETHER_GATEWAY_SECURITY_CACHE_TTL_MS`：IP 黑白名单本地缓存时间，默认 `1000ms`，写操作会主动失效相关缓存
+- `AETHER_MAX_REDACTED_SYNC_RESPONSE_BODY_MB`：PII 恢复同步响应缓冲上限，默认 `64MB`；显式设为 `0` 表示不再收紧默认值，但仍受 `256MB` 安全硬上限约束
+- `REDIS_URL`：Redis 连接串；仅 Postgres + Redis 的 Docker Compose 部署需要配置
+- `AETHER_RUNTIME_BACKEND=memory|redis`：运行时缓存/协调后端。配置 Redis 时使用 `redis`，否则使用 `memory`；多节点部署和需要跨 gateway 重启恢复 OpenAI Responses continuation history 的部署必须使用共享 Redis
+- `AETHER_GATEWAY_DATABASE_MODE=auto|verify-only`：数据库启动策略，默认 `auto`，自动完成挂起的 schema migration 和 backfill；`verify-only` 仅检查并在数据库落后时拒绝启动
+- `AETHER_GATEWAY_AUTO_PREPARE_DATABASE`：旧版兼容开关；新配置请使用 `AETHER_GATEWAY_DATABASE_MODE`
+- `JWT_SECRET_KEY` / `ENCRYPTION_KEY`：认证和敏感数据加密所需密钥
+- `AETHER_BACKUP_ENCRYPTION_KEY`：推荐的 S3 备份独立加密密钥；缺省回退到 `ENCRYPTION_KEY`。新备份使用带 key ID 的 AES-256-GCM v2 envelope，轮换前必须保留旧密钥
+- `API_KEY_PREFIX`：用户和管理员新建 API Key 时使用的前缀，默认 `sk`
+- `ADMIN_USERNAME` / `ADMIN_PASSWORD` / `ADMIN_EMAIL`：首次启动时自举首个本地管理员；`install.sh` 会提示输入管理员密码
+- `CORS_ORIGINS` / `CORS_ALLOW_CREDENTIALS`：前端跨域来源控制；如果要跨域带登录 Cookie，`CORS_ORIGINS` 不能写 `*`
+- `RUST_LOG`：Rust 日志过滤，例如 `aether_gateway=info`、`aether_gateway=debug,sqlx=warn`
+- `DB_PASSWORD` / `REDIS_PASSWORD`：Docker Compose 后端密码，首次安装时分别随机生成；手工部署必须替换示例占位值，不要互相复用
 
-| 变量 | 说明 |
-|------|------|
-| `DB_PASSWORD` | PostgreSQL 数据库密码 |
-| `REDIS_PASSWORD` | Redis 密码 |
-| `JWT_SECRET_KEY` | JWT 签名密钥（使用 `generate_keys.py` 生成） |
-| `ENCRYPTION_KEY` | API Key 加密密钥（更换后需重新配置 Provider Key） |
-| `ADMIN_EMAIL` | 初始管理员邮箱 |
-| `ADMIN_USERNAME` | 初始管理员用户名 |
-| `ADMIN_PASSWORD` | 初始管理员密码 |
+### S3 备份离线恢复
 
-### 可选配置
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `APP_PORT` | 8084 | 应用端口 |
-| `API_KEY_PREFIX` | sk | API Key 前缀 |
-| `LOG_LEVEL` | INFO | 日志级别 (DEBUG/INFO/WARNING/ERROR) |
-| `GUNICORN_WORKERS` | 4 | Gunicorn 工作进程数 |
-| `DB_PORT` | 5432 | PostgreSQL 端口 |
-| `REDIS_PORT` | 6379 | Redis 端口 |
-
-## Q&A
-
-### Q: 如何开启/关闭请求体记录？
-
-管理员在 **系统设置** 中配置日志记录的详细程度:
-
-| 级别 | 记录内容 |
-|------|----------|
-| Base | 基本请求信息 |
-| Headers | Base + 请求头 |
-| Full | Headers + 请求体 |
-
-### Q: 更新出问题如何回滚？
-
-**有备份的情况（推荐）：**
+先从 S3 下载完整的 `.json.zst.aes256gcm` 对象，再使用原始的完整 S3 object key 做认证解密。恢复工具只验证并输出本地 JSON，不会直接写数据库；数据库导入仍应在维护窗口通过管理端完成。
 
 ```bash
-# 1. 停止应用
-docker compose stop app
-
-# 2. 恢复数据库（先清空再导入）
-docker compose exec -T postgres psql -U postgres -c "DROP DATABASE aether; CREATE DATABASE aether;"
-gunzip < backup_xxx.sql.gz | docker compose exec -T postgres psql -U postgres -d aether
-
-# 3. 拉取旧版本镜像并重启
-#    方式一：使用具体版本 tag（如果有发布版本号）
-#    将 docker-compose.yml 中 image 从 ghcr.io/fawney19/aether:latest 改为指定版本
-#    方式二：使用之前记录的镜像 digest
-#    将 image 改为 ghcr.io/fawney19/aether@sha256:xxxxx
-docker compose up -d app
+AETHER_BACKUP_ENCRYPTION_KEY='原备份密钥' \
+  cargo run -p aether-gateway --bin aether-backup-restore -- \
+  --input ./backup.json.zst.aes256gcm \
+  --object-key 'aether/backups/aether-data-backup-20260822-010000.json.zst.aes256gcm' \
+  --output ./restored-backup.json
 ```
 
-> 可以在升级前通过 `docker inspect ghcr.io/fawney19/aether:latest --format '{{index .RepoDigests 0}}'` 记录当前镜像 digest，方便回滚时使用。
+工具默认拒绝覆盖，输出采用原子写并在 Unix 上设置为 `0600`；Unix 可用 `--overwrite` 原子替换，Windows 为避免非原子删除窗口会要求选择新输出路径。密钥不能作为命令行参数。可使用 `AETHER_BACKUP_ENCRYPTION_KEY`、兼容用 `AETHER_GATEWAY_DATA_ENCRYPTION_KEY` / `ENCRYPTION_KEY`、受保护的 `--key-file`，或 `AETHER_BACKUP_KEYRING_FILE`。Keyring JSON 格式为 `{"version":1,"keys":["当前或历史 v2 secret"],"legacy_v1":["旧 v1 secret"]}`；条目也可写成 `{"secret":"..."}`（兼容字段名 `key`）。也可由 `AETHER_BACKUP_HISTORICAL_KEYS_JSON` 提供同一结构。密钥文件必须是非符号链接的普通文件，Unix 下权限需为 `0600` 或更严格。
 
-**没有备份的情况：**
-
-```bash
-# 1. 用当前容器回退数据库迁移（回退 1 步，按需调整数字）
-docker compose exec app alembic downgrade -1
-
-# 2. 查看回退后的版本确认正确
-docker compose exec app alembic current
-
-# 3. 切回旧镜像并重启（同上方式修改 docker-compose.yml 中的 image）
-docker compose up -d app
-```
-
-> 注意：没有备份的回滚依赖 alembic downgrade，如果迁移涉及不可逆的数据变更（如删除列），可能无法完全恢复数据。因此强烈建议升级前备份。
+默认限制密文为 `512MiB`、解压后 JSON 为 `1GiB`，可通过受限的 `--max-encrypted-mib` / `--max-json-mib` 调整。网关最多扫描同一备份前缀下 10,000 个对象，并且不会自动删除 S3 对象：`backup_s3_retention_count` 只用于报告超出保留数量的清理候选。旧明文备份在创建并验证加密副本后仍会保留，必须通过 bucket lifecycle 或支持版本条件的外部清理工具移除；启用 Versioning 时还需清理 noncurrent versions，Object Lock/retention 可能阻止物理删除。
 
 ---
 
@@ -171,5 +176,4 @@ docker compose up -d app
 
 ## Star History
 
-[![Star History Chart](https://api.star-history.com/svg?repos=fawney19/Aether&type=Date)](https://star-history.com/#fawney19/Aether&Date)
-
+[![Star History Chart](https://api.star-history.com/svg?repos=fawney19/Aether&type=date&legend=top-left)](https://www.star-history.com/?repos=fawney19%2FAether&type=date&legend=top-left)

aether-proxy/.env.example

@@ -1,14 +0,0 @@
-# Aether server URL
-AETHER_PROXY_AETHER_URL=https://aether.example.com
-
-# Management Token (ae_xxx, must belong to an ADMIN user)
-AETHER_PROXY_MANAGEMENT_TOKEN=ae_xxxxx
-
-# HMAC key (must match Aether's PROXY_HMAC_KEY)
-AETHER_PROXY_HMAC_KEY=
-
-# Proxy listen port
-AETHER_PROXY_LISTEN_PORT=18080
-
-# Node identification
-AETHER_PROXY_NODE_NAME=proxy-01

aether-proxy/Cargo.toml

@@ -1,46 +0,0 @@
-[package]
-name = "aether-proxy"
-version = "0.1.6"
-edition = "2021"
-description = "Forward proxy for Aether with HMAC authentication"
-
-[dependencies]
-tokio = { version = "1", features = ["full"] }
-hyper = { version = "1", features = ["http1", "server"] }
-hyper-util = { version = "0.1", features = ["tokio", "http1", "http2", "server", "client-legacy"] }
-tower-service = "0.3"
-http-body-util = "0.1"
-reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls", "stream", "http2"] }
-futures-util = "0.3"
-hmac = "0.12"
-sha2 = "0.10"
-subtle = "2"
-base64 = "0.22"
-clap = { version = "4", features = ["derive", "env"] }
-tracing = "0.1"
-tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
-serde = { version = "1", features = ["derive"] }
-serde_json = "1"
-thiserror = "2"
-bytes = "1"
-hex = "0.4"
-anyhow = "1"
-toml = "0.8"
-tokio-rustls = "0.26"
-webpki-roots = "1"
-rustls = { version = "0.23", features = ["ring"] }
-rustls-pki-types = "1"
-rustls-pemfile = "2"
-rcgen = "0.13"
-ratatui = "0.30"
-crossterm = "0.28"
-url = "2"
-sysinfo = "0.32"
-libc = "0.2"
-flate2 = "1"
-tar = "0.4"
-
-[profile.release]
-lto = true
-strip = true
-codegen-units = 1

aether-proxy/Dockerfile

@@ -1,12 +0,0 @@
-FROM debian:bookworm-slim
-
-ARG TARGETARCH
-
-RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates \
-    && rm -rf /var/lib/apt/lists/*
-
-COPY build/linux-${TARGETARCH}/aether-proxy /usr/local/bin/aether-proxy
-
-EXPOSE 18080
-
-ENTRYPOINT ["aether-proxy"]

aether-proxy/README.md

@@ -1,120 +0,0 @@
-# aether-proxy
-
-Aether 正向代理节点，部署在海外 VPS 上，为墙内的 Aether 实例中转 API 流量。
-
-## 安装
-
-### Docker Compose 部署
-
-```bash
-# 拉取镜像
-docker pull ghcr.io/fawney19/aether-proxy:latest
-
-# 或使用 docker compose
-cp .env.example .env
-# 编辑 .env 填入 AETHER_PROXY_AETHER_URL, MANAGEMENT_TOKEN, HMAC_KEY
-docker compose up -d
-```
-
-### 下载预编译二进制
-
-<!-- DOWNLOAD_TABLE_START -->
-| Platform | Download |
-|----------|----------|
-| Linux x86_64 | [aether-proxy-linux-amd64.tar.gz](https://github.com/fawney19/Aether/releases/download/proxy-v0.1.6/aether-proxy-linux-amd64.tar.gz) |
-| Linux ARM64 | [aether-proxy-linux-arm64.tar.gz](https://github.com/fawney19/Aether/releases/download/proxy-v0.1.6/aether-proxy-linux-arm64.tar.gz) |
-| macOS x86_64 | [aether-proxy-macos-amd64.tar.gz](https://github.com/fawney19/Aether/releases/download/proxy-v0.1.6/aether-proxy-macos-amd64.tar.gz) |
-| macOS ARM64 | [aether-proxy-macos-arm64.tar.gz](https://github.com/fawney19/Aether/releases/download/proxy-v0.1.6/aether-proxy-macos-arm64.tar.gz) |
-| Windows x86_64 | [aether-proxy-windows-amd64.zip](https://github.com/fawney19/Aether/releases/download/proxy-v0.1.6/aether-proxy-windows-amd64.zip) |
-<!-- DOWNLOAD_TABLE_END -->
-
-## 快速开始
-
-```bash
-# 1. 首次安装配置（TUI 向导，勾选 Install Service 随系统启动服务）
-sudo ./aether-proxy setup
-
-# 2. 日常管理 (勾选 Install Service 作为系统服务的情况下)
-aether-proxy status          # 看状态
-aether-proxy logs            # 看日志
-
-sudo aether-proxy start      # 启动服务
-sudo aether-proxy stop       # 停止服务
-sudo aether-proxy restart    # 重启服务
-
-# 3. 重新配置（改完自动重启服务）
-sudo aether-proxy setup
-
-# 4. 彻底卸载
-sudo aether-proxy uninstall
-```
-
-完成向导后, 配置自动保存到 `aether-proxy.toml`，如果启用了 Install Service，将自动注册并启动 systemd 服务。
-
-### 直接运行
-
-如果不需要安装为系统服务，可以直接运行。缺少必填参数时会自动进入 setup 向导：
-
-```bash
-./aether-proxy
-```
-
-## 配置
-
-配置按以下优先级加载（高优先级覆盖低优先级）：
-
-1. CLI 参数
-2. 环境变量（`AETHER_PROXY_*`）
-3. 配置文件（`aether-proxy.toml`，或通过 `AETHER_PROXY_CONFIG` 指定路径）
-
-### 参数一览
-
-| 参数 | 环境变量 | 默认值 | 说明 |
-|------|----------|--------|------|
-| `--aether-url` | `AETHER_PROXY_AETHER_URL` | **必填** | Aether 服务器地址 |
-| `--management-token` | `AETHER_PROXY_MANAGEMENT_TOKEN` | **必填** | 管理员 Token（`ae_xxx` 格式） |
-| `--hmac-key` | `AETHER_PROXY_HMAC_KEY` | **必填** | HMAC 密钥，需与 Aether 端一致 |
-| `--listen-port` | `AETHER_PROXY_LISTEN_PORT` | `18080` | 监听端口 |
-| `--public-ip` | `AETHER_PROXY_PUBLIC_IP` | 自动检测 | 公网 IP |
-| `--node-name` | `AETHER_PROXY_NODE_NAME` | `proxy-01` | 节点名称标识 |
-| `--node-region` | `AETHER_PROXY_NODE_REGION` | 自动检测 | 地区标识 |
-| `--heartbeat-interval` | `AETHER_PROXY_HEARTBEAT_INTERVAL` | `30` | 心跳间隔（秒） |
-| `--allowed-ports` | `AETHER_PROXY_ALLOWED_PORTS` | `80,443,8080,8443` | 允许代理的目标端口 |
-| `--timestamp-tolerance` | `AETHER_PROXY_TIMESTAMP_TOLERANCE` | `300` | HMAC 时间戳容差（秒） |
-| `--aether-request-timeout` | `AETHER_PROXY_AETHER_REQUEST_TIMEOUT` | `10` | Aether API 请求总超时（秒） |
-| `--aether-connect-timeout` | `AETHER_PROXY_AETHER_CONNECT_TIMEOUT` | `10` | Aether API 建连超时（秒） |
-| `--aether-pool-max-idle-per-host` | `AETHER_PROXY_AETHER_POOL_MAX_IDLE_PER_HOST` | `8` | Aether API 每 Host 最大空闲连接数 |
-| `--aether-pool-idle-timeout` | `AETHER_PROXY_AETHER_POOL_IDLE_TIMEOUT` | `90` | Aether API 连接池空闲超时（秒） |
-| `--aether-tcp-keepalive` | `AETHER_PROXY_AETHER_TCP_KEEPALIVE` | `60` | Aether API TCP keepalive（秒，0 关闭） |
-| `--aether-tcp-nodelay` | `AETHER_PROXY_AETHER_TCP_NODELAY` | `true` | Aether API 启用 TCP_NODELAY |
-| `--aether-http2` | `AETHER_PROXY_AETHER_HTTP2` | `true` | Aether API 启用 HTTP/2 |
-| `--aether-retry-max-attempts` | `AETHER_PROXY_AETHER_RETRY_MAX_ATTEMPTS` | `3` | Aether API 最大重试次数（含首次） |
-| `--aether-retry-base-delay-ms` | `AETHER_PROXY_AETHER_RETRY_BASE_DELAY_MS` | `200` | Aether API 重试基础延迟（毫秒） |
-| `--aether-retry-max-delay-ms` | `AETHER_PROXY_AETHER_RETRY_MAX_DELAY_MS` | `2000` | Aether API 重试最大延迟（毫秒） |
-| `--max-concurrent-connections` | `AETHER_PROXY_MAX_CONCURRENT_CONNECTIONS` | 自动估算 | 最大并发连接数（默认硬件估算） |
-| `--connect-timeout` | `AETHER_PROXY_CONNECT_TIMEOUT` | `30` | CONNECT 上游建连超时（秒） |
-| `--tls-handshake-timeout` | `AETHER_PROXY_TLS_HANDSHAKE_TIMEOUT` | `10` | TLS 握手超时（秒） |
-| `--dns-cache-ttl` | `AETHER_PROXY_DNS_CACHE_TTL` | `60` | DNS 缓存 TTL（秒） |
-| `--dns-cache-capacity` | `AETHER_PROXY_DNS_CACHE_CAPACITY` | `1024` | DNS 缓存容量（条目数） |
-| `--delegate-connect-timeout` | `AETHER_PROXY_DELEGATE_CONNECT_TIMEOUT` | `30` | delegate 上游建连超时（秒） |
-| `--delegate-pool-max-idle-per-host` | `AETHER_PROXY_DELEGATE_POOL_MAX_IDLE_PER_HOST` | `64` | delegate 每 Host 最大空闲连接数 |
-| `--delegate-pool-idle-timeout` | `AETHER_PROXY_DELEGATE_POOL_IDLE_TIMEOUT` | `300` | delegate 连接池空闲超时（秒） |
-| `--delegate-tcp-keepalive` | `AETHER_PROXY_DELEGATE_TCP_KEEPALIVE` | `60` | delegate TCP keepalive（秒，0 关闭） |
-| `--delegate-tcp-nodelay` | `AETHER_PROXY_DELEGATE_TCP_NODELAY` | `true` | delegate 启用 TCP_NODELAY |
-| `--log-level` | `AETHER_PROXY_LOG_LEVEL` | `info` | 日志级别 |
-| `--log-json` | `AETHER_PROXY_LOG_JSON` | `false` | JSON 格式日志 |
-| `--enable-tls` | `AETHER_PROXY_ENABLE_TLS` | `true` | 启用 TLS |
-| `--tls-cert` | `AETHER_PROXY_TLS_CERT` | `aether-proxy-cert.pem` | TLS 证书路径 |
-| `--tls-key` | `AETHER_PROXY_TLS_KEY` | `aether-proxy-key.pem` | TLS 私钥路径 |
-
-## 发布新版本
-
-推送 `proxy-v*` 格式的 tag，GitHub Actions 会自动：
-- 编译所有平台二进制并发布到 Releases
-- 构建 Docker 镜像并推送到 GHCR 和 Docker Hub
-- 更新 README 中的下载链接表格
-
-```bash
-git tag proxy-v0.1.0
-git push origin proxy-v0.1.0
-```

aether-proxy/docker-compose.yml

@@ -1,17 +0,0 @@
-services:
-  aether-proxy:
-    image: ghcr.io/fawney19/aether-proxy:latest
-    container_name: aether-proxy
-    restart: unless-stopped
-    ports:
-      - "${AETHER_PROXY_LISTEN_PORT:-18080}:18080"
-    env_file:
-      - .env
-    environment:
-      AETHER_PROXY_LISTEN_PORT: 18080
-      AETHER_PROXY_LOG_JSON: "true"
-    logging:
-      driver: json-file
-      options:
-        max-size: "50m"
-        max-file: "3"

aether-proxy/src/app.rs

@@ -1,213 +0,0 @@
-//! Application lifecycle: initialization, task orchestration, and shutdown.
-//!
-//! Extracted from `main.rs` to keep the entry point minimal and consolidate
-//! the startup sequence, tracing init, and graceful shutdown logic.
-
-use std::sync::atomic::AtomicU64;
-use std::sync::{Arc, RwLock};
-use std::time::Duration;
-
-use tokio::signal;
-use tokio::sync::{watch, Semaphore};
-use tracing::{error, info};
-
-use crate::config::Config;
-use crate::net;
-use crate::registration::client::AetherClient;
-use crate::runtime::{self, DynamicConfig};
-use crate::state::{AppState, ProxyMetrics};
-use crate::{hardware, proxy};
-
-/// Run the full application lifecycle after config has been parsed.
-pub async fn run(mut config: Config) -> anyhow::Result<()> {
-    init_tracing(&config);
-
-    info!(
-        version = env!("CARGO_PKG_VERSION"),
-        port = config.listen_port,
-        node_name = %config.node_name,
-        "aether-proxy starting"
-    );
-
-    // Resolve public IP
-    let public_ip = match &config.public_ip {
-        Some(ip) => ip.clone(),
-        None => net::detect_public_ip().await?,
-    };
-    info!(public_ip = %public_ip, "using public IP");
-
-    // Auto-detect region if not configured
-    if config.node_region.is_none() {
-        if let Some(region) = net::detect_region(&public_ip).await {
-            config.node_region = Some(region);
-        }
-    }
-
-    // Initialize TLS if enabled
-    let (tls_acceptor, tls_fingerprint) = if config.enable_tls {
-        let cert_path = std::path::PathBuf::from(&config.tls_cert);
-        let key_path = std::path::PathBuf::from(&config.tls_key);
-
-        proxy::tls::ensure_self_signed_cert(&cert_path, &key_path)?;
-        let acceptor = proxy::tls::build_tls_acceptor(&cert_path, &key_path)?;
-        let fingerprint = proxy::tls::cert_sha256_fingerprint(&cert_path)?;
-
-        info!(fingerprint = %fingerprint, "TLS enabled");
-        (Some(acceptor), Some(fingerprint))
-    } else {
-        info!("TLS disabled");
-        (None, None)
-    };
-
-    // Collect hardware info (once at startup)
-    let hw_info = hardware::collect();
-
-    let max_connections_raw = config
-        .max_concurrent_connections
-        .unwrap_or(hw_info.estimated_max_concurrency)
-        .max(1);
-    let max_connections = usize::try_from(max_connections_raw).unwrap_or(usize::MAX);
-    info!(
-        max_connections = max_connections_raw,
-        "connection limit configured"
-    );
-
-    let connection_semaphore = Arc::new(Semaphore::new(max_connections));
-    let metrics = Arc::new(ProxyMetrics::new());
-    let dns_cache = Arc::new(proxy::target_filter::DnsCache::new(
-        Duration::from_secs(config.dns_cache_ttl_secs),
-        config.dns_cache_capacity,
-    ));
-
-    // Register with Aether
-    let aether_client = Arc::new(AetherClient::new(&config));
-    let node_id = aether_client
-        .register(
-            &config,
-            &public_ip,
-            config.enable_tls,
-            tls_fingerprint.as_deref(),
-            Some(&hw_info),
-        )
-        .await?;
-
-    info!(node_id = %node_id, "node registered");
-
-    // Build DynamicConfig before moving config into Arc
-    let dynamic = Arc::new(RwLock::new(DynamicConfig::from_config(&config)));
-
-    // Build delegate HTTP client (for proxy-initiated upstream requests).
-    let delegate_client = proxy::delegate_client::build_delegate_client(&config);
-
-    // Build shared application state
-    let state = Arc::new(AppState {
-        config: Arc::new(config),
-        node_id: Arc::new(RwLock::new(node_id)),
-        dynamic,
-        aether_client,
-        hardware_info: Arc::new(hw_info),
-        public_ip,
-        tls_fingerprint,
-        tls_acceptor,
-        delegate_client,
-        active_connections: Arc::new(AtomicU64::new(0)),
-        connection_semaphore,
-        dns_cache,
-        metrics,
-    });
-
-    // Shutdown signal channel
-    let (shutdown_tx, shutdown_rx) = watch::channel(false);
-
-    // Start heartbeat task
-    let heartbeat_handle = {
-        let state = Arc::clone(&state);
-        let rx = shutdown_rx.clone();
-        tokio::spawn(async move {
-            crate::registration::heartbeat::run(&state, rx).await;
-        })
-    };
-
-    // Start proxy server
-    let server_handle = {
-        let state = Arc::clone(&state);
-        let rx = shutdown_rx.clone();
-        tokio::spawn(async move {
-            if let Err(e) = proxy::server::run(&state, rx).await {
-                error!(error = %e, "proxy server error");
-            }
-        })
-    };
-
-    // Wait for shutdown signal (SIGTERM or SIGINT)
-    wait_for_shutdown().await;
-
-    info!("shutdown signal received, cleaning up...");
-
-    // Signal all tasks to stop
-    let _ = shutdown_tx.send(true);
-
-    // Graceful unregister (best-effort)
-    let current_node_id = state.node_id.read().unwrap().clone();
-    if let Err(e) = state.aether_client.unregister(&current_node_id).await {
-        error!(error = %e, "unregister failed during shutdown");
-    }
-
-    // Wait for tasks to finish
-    let _ = tokio::join!(heartbeat_handle, server_handle);
-
-    info!("aether-proxy stopped");
-    Ok(())
-}
-
-fn init_tracing(config: &Config) {
-    use tracing_subscriber::prelude::*;
-    use tracing_subscriber::{reload, EnvFilter};
-
-    let filter = EnvFilter::try_new(&config.log_level).unwrap_or_else(|_| EnvFilter::new("info"));
-
-    let (filter_layer, reload_handle) = reload::Layer::new(filter);
-
-    // Register log-level hot-reloader
-    runtime::set_log_reloader(Box::new(move |level: &str| {
-        if let Ok(new_filter) = EnvFilter::try_new(level) {
-            let _ = reload_handle.modify(|f| *f = new_filter);
-        }
-    }));
-
-    if config.log_json {
-        tracing_subscriber::registry()
-            .with(filter_layer)
-            .with(tracing_subscriber::fmt::layer().json())
-            .init();
-    } else {
-        tracing_subscriber::registry()
-            .with(filter_layer)
-            .with(tracing_subscriber::fmt::layer())
-            .init();
-    }
-}
-
-async fn wait_for_shutdown() {
-    let ctrl_c = async {
-        signal::ctrl_c()
-            .await
-            .expect("failed to install Ctrl+C handler");
-    };
-
-    #[cfg(unix)]
-    let terminate = async {
-        signal::unix::signal(signal::unix::SignalKind::terminate())
-            .expect("failed to install SIGTERM handler")
-            .recv()
-            .await;
-    };
-
-    #[cfg(not(unix))]
-    let terminate = std::future::pending::<()>();
-
-    tokio::select! {
-        _ = ctrl_c => {},
-        _ = terminate => {},
-    }
-}

aether-proxy/src/auth/hmac.rs

@@ -1,196 +0,0 @@
-use base64::Engine;
-use hmac::{Hmac, Mac};
-use sha2::Sha256;
-use subtle::ConstantTimeEq;
-
-use crate::config::Config;
-
-type HmacSha256 = Hmac<Sha256>;
-
-#[derive(Debug)]
-pub enum AuthError {
-    MissingHeader,
-    InvalidBasicAuth,
-    InvalidUsername,
-    InvalidPasswordFormat,
-    TimestampParseError,
-    TimestampExpired,
-    SignatureMismatch,
-}
-
-impl std::fmt::Display for AuthError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            Self::MissingHeader => write!(f, "missing Proxy-Authorization header"),
-            Self::InvalidBasicAuth => write!(f, "invalid Basic auth encoding"),
-            Self::InvalidUsername => write!(f, "username must be 'hmac'"),
-            Self::InvalidPasswordFormat => {
-                write!(f, "password format must be 'timestamp.signature'")
-            }
-            Self::TimestampParseError => write!(f, "invalid timestamp"),
-            Self::TimestampExpired => write!(f, "timestamp outside tolerance window"),
-            Self::SignatureMismatch => write!(f, "HMAC signature mismatch"),
-        }
-    }
-}
-
-/// Validate Proxy-Authorization header.
-///
-/// Expected format: `Basic base64(hmac:{timestamp}.{signature})`
-/// where signature = hex(HMAC-SHA256(hmac_key, "{timestamp}"))
-///
-/// The signature no longer includes `node_id`, eliminating race conditions
-/// during re-registration where the Aether server's cached `node_id` could
-/// differ from the proxy's freshly assigned `node_id`.
-///
-/// `timestamp_tolerance` is accepted separately so the caller can supply
-/// the value from [`DynamicConfig`](crate::runtime::DynamicConfig) (which
-/// may be updated remotely).
-pub fn validate_proxy_auth(
-    proxy_auth_header: Option<&str>,
-    config: &Config,
-    timestamp_tolerance: u64,
-) -> Result<(), AuthError> {
-    let header = proxy_auth_header.ok_or(AuthError::MissingHeader)?;
-
-    let encoded = header
-        .strip_prefix("Basic ")
-        .or_else(|| header.strip_prefix("basic "))
-        .ok_or(AuthError::InvalidBasicAuth)?;
-
-    let decoded_bytes = base64::engine::general_purpose::STANDARD
-        .decode(encoded.trim())
-        .map_err(|_| AuthError::InvalidBasicAuth)?;
-
-    let decoded = String::from_utf8(decoded_bytes).map_err(|_| AuthError::InvalidBasicAuth)?;
-
-    // format: hmac:{timestamp}.{signature}
-    let (username, password) = decoded.split_once(':').ok_or(AuthError::InvalidBasicAuth)?;
-
-    if username != "hmac" {
-        return Err(AuthError::InvalidUsername);
-    }
-
-    let (timestamp_str, signature_hex) = password
-        .split_once('.')
-        .ok_or(AuthError::InvalidPasswordFormat)?;
-
-    // Validate timestamp window
-    let timestamp: u64 = timestamp_str
-        .parse()
-        .map_err(|_| AuthError::TimestampParseError)?;
-
-    let now = std::time::SystemTime::now()
-        .duration_since(std::time::UNIX_EPOCH)
-        .expect("system clock before epoch")
-        .as_secs();
-
-    let diff = now.abs_diff(timestamp);
-
-    if diff > timestamp_tolerance {
-        return Err(AuthError::TimestampExpired);
-    }
-
-    // Recompute signature: HMAC-SHA256(key, timestamp)
-    let mut mac =
-        HmacSha256::new_from_slice(config.hmac_key.as_bytes()).expect("HMAC accepts any key size");
-    mac.update(timestamp_str.as_bytes());
-    let expected = mac.finalize().into_bytes();
-    let expected_hex = hex::encode(expected);
-
-    // Constant-time comparison
-    let sig_bytes = signature_hex.as_bytes();
-    let exp_bytes = expected_hex.as_bytes();
-
-    if sig_bytes.len() != exp_bytes.len() || sig_bytes.ct_eq(exp_bytes).unwrap_u8() != 1 {
-        return Err(AuthError::SignatureMismatch);
-    }
-
-    Ok(())
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn make_config() -> Config {
-        Config {
-            aether_url: String::new(),
-            management_token: String::new(),
-            hmac_key: "test-hmac-key".to_string(),
-            listen_port: 18080,
-            public_ip: None,
-            node_name: "test".to_string(),
-            node_region: None,
-            heartbeat_interval: 30,
-            allowed_ports: vec![80, 443],
-            timestamp_tolerance: 300,
-            aether_request_timeout_secs: 10,
-            aether_connect_timeout_secs: 10,
-            aether_pool_max_idle_per_host: 8,
-            aether_pool_idle_timeout_secs: 90,
-            aether_tcp_keepalive_secs: 60,
-            aether_tcp_nodelay: true,
-            aether_http2: true,
-            aether_retry_max_attempts: 3,
-            aether_retry_base_delay_ms: 200,
-            aether_retry_max_delay_ms: 2000,
-            max_concurrent_connections: None,
-            connect_timeout_secs: 30,
-            tls_handshake_timeout_secs: 10,
-            dns_cache_ttl_secs: 60,
-            dns_cache_capacity: 1024,
-            delegate_connect_timeout_secs: 30,
-            delegate_pool_max_idle_per_host: 64,
-            delegate_pool_idle_timeout_secs: 300,
-            delegate_tcp_keepalive_secs: 60,
-            delegate_tcp_nodelay: true,
-            log_level: "info".to_string(),
-            log_json: false,
-            enable_tls: false,
-            tls_cert: String::new(),
-            tls_key: String::new(),
-        }
-    }
-
-    fn make_valid_auth(config: &Config) -> String {
-        let now = std::time::SystemTime::now()
-            .duration_since(std::time::UNIX_EPOCH)
-            .unwrap()
-            .as_secs();
-        let mut mac = HmacSha256::new_from_slice(config.hmac_key.as_bytes()).unwrap();
-        mac.update(now.to_string().as_bytes());
-        let sig = hex::encode(mac.finalize().into_bytes());
-        let cred = format!("hmac:{}.{}", now, sig);
-        let encoded = base64::engine::general_purpose::STANDARD.encode(cred);
-        format!("Basic {}", encoded)
-    }
-
-    #[test]
-    fn test_valid_auth() {
-        let config = make_config();
-        let header = make_valid_auth(&config);
-        assert!(validate_proxy_auth(Some(&header), &config, config.timestamp_tolerance).is_ok());
-    }
-
-    #[test]
-    fn test_missing_header() {
-        let config = make_config();
-        assert!(matches!(
-            validate_proxy_auth(None, &config, config.timestamp_tolerance),
-            Err(AuthError::MissingHeader)
-        ));
-    }
-
-    #[test]
-    fn test_wrong_username() {
-        let cred = "user:12345.abc";
-        let encoded = base64::engine::general_purpose::STANDARD.encode(cred);
-        let header = format!("Basic {}", encoded);
-        let config = make_config();
-        assert!(matches!(
-            validate_proxy_auth(Some(&header), &config, config.timestamp_tolerance),
-            Err(AuthError::InvalidUsername)
-        ));
-    }
-}

aether-proxy/src/auth/mod.rs

@@ -1,3 +0,0 @@
-pub mod hmac;
-
-pub use self::hmac::validate_proxy_auth;

aether-proxy/src/config.rs

@@ -1,427 +0,0 @@
-use std::path::Path;
-
-use clap::Parser;
-use serde::{Deserialize, Serialize};
-
-/// Aether forward proxy with HMAC authentication.
-///
-/// Deployed on overseas VPS to relay API traffic for Aether instances
-/// behind the GFW. Registers with Aether, sends heartbeats, and validates
-/// incoming proxy requests via HMAC-SHA256 signatures in Basic Auth.
-#[derive(Parser, Debug, Clone)]
-#[command(version, about)]
-pub struct Config {
-    /// Aether server URL (e.g. https://aether.example.com)
-    #[arg(long, env = "AETHER_PROXY_AETHER_URL")]
-    pub aether_url: String,
-
-    /// Management Token for Aether admin API (ae_xxx)
-    #[arg(long, env = "AETHER_PROXY_MANAGEMENT_TOKEN")]
-    pub management_token: String,
-
-    /// HMAC-SHA256 key for proxy authentication
-    #[arg(long, env = "AETHER_PROXY_HMAC_KEY")]
-    pub hmac_key: String,
-
-    /// Port to listen on for proxy connections
-    #[arg(long, env = "AETHER_PROXY_LISTEN_PORT", default_value_t = 18080)]
-    pub listen_port: u16,
-
-    /// Public IP address of this node (auto-detected if omitted)
-    #[arg(long, env = "AETHER_PROXY_PUBLIC_IP")]
-    pub public_ip: Option<String>,
-
-    /// Human-readable node name
-    #[arg(long, env = "AETHER_PROXY_NODE_NAME", default_value = "proxy-01")]
-    pub node_name: String,
-
-    /// Region label (e.g. ap-northeast-1)
-    #[arg(long, env = "AETHER_PROXY_NODE_REGION")]
-    pub node_region: Option<String>,
-
-    /// Heartbeat interval in seconds
-    #[arg(long, env = "AETHER_PROXY_HEARTBEAT_INTERVAL", default_value_t = 30)]
-    pub heartbeat_interval: u64,
-
-    /// Allowed destination ports (default: 80,443,8080,8443)
-    #[arg(
-        long,
-        env = "AETHER_PROXY_ALLOWED_PORTS",
-        value_delimiter = ',',
-        default_values_t = vec![80, 443, 8080, 8443]
-    )]
-    pub allowed_ports: Vec<u16>,
-
-    /// Timestamp tolerance window in seconds for HMAC validation
-    #[arg(long, env = "AETHER_PROXY_TIMESTAMP_TOLERANCE", default_value_t = 300)]
-    pub timestamp_tolerance: u64,
-
-    /// Aether API request timeout in seconds
-    #[arg(
-        long,
-        env = "AETHER_PROXY_AETHER_REQUEST_TIMEOUT",
-        default_value_t = 10
-    )]
-    pub aether_request_timeout_secs: u64,
-
-    /// Aether API connect timeout in seconds
-    #[arg(
-        long,
-        env = "AETHER_PROXY_AETHER_CONNECT_TIMEOUT",
-        default_value_t = 10
-    )]
-    pub aether_connect_timeout_secs: u64,
-
-    /// Aether API max idle connections per host
-    #[arg(
-        long,
-        env = "AETHER_PROXY_AETHER_POOL_MAX_IDLE_PER_HOST",
-        default_value_t = 8
-    )]
-    pub aether_pool_max_idle_per_host: usize,
-
-    /// Aether API idle timeout in seconds
-    #[arg(
-        long,
-        env = "AETHER_PROXY_AETHER_POOL_IDLE_TIMEOUT",
-        default_value_t = 90
-    )]
-    pub aether_pool_idle_timeout_secs: u64,
-
-    /// Aether API TCP keepalive in seconds (0 disables)
-    #[arg(long, env = "AETHER_PROXY_AETHER_TCP_KEEPALIVE", default_value_t = 60)]
-    pub aether_tcp_keepalive_secs: u64,
-
-    /// Aether API TCP_NODELAY
-    #[arg(long, env = "AETHER_PROXY_AETHER_TCP_NODELAY", default_value_t = true)]
-    pub aether_tcp_nodelay: bool,
-
-    /// Enable HTTP/2 when talking to Aether API
-    #[arg(long, env = "AETHER_PROXY_AETHER_HTTP2", default_value_t = true)]
-    pub aether_http2: bool,
-
-    /// Aether API retry attempts (including initial)
-    #[arg(
-        long,
-        env = "AETHER_PROXY_AETHER_RETRY_MAX_ATTEMPTS",
-        default_value_t = 3
-    )]
-    pub aether_retry_max_attempts: u32,
-
-    /// Aether API retry base delay in milliseconds
-    #[arg(
-        long,
-        env = "AETHER_PROXY_AETHER_RETRY_BASE_DELAY_MS",
-        default_value_t = 200
-    )]
-    pub aether_retry_base_delay_ms: u64,
-
-    /// Aether API retry max delay in milliseconds
-    #[arg(
-        long,
-        env = "AETHER_PROXY_AETHER_RETRY_MAX_DELAY_MS",
-        default_value_t = 2000
-    )]
-    pub aether_retry_max_delay_ms: u64,
-
-    /// Maximum concurrent TCP connections (defaults to hardware estimate)
-    #[arg(long, env = "AETHER_PROXY_MAX_CONCURRENT_CONNECTIONS")]
-    pub max_concurrent_connections: Option<u64>,
-
-    /// Upstream TCP connect timeout in seconds for CONNECT tunnels
-    #[arg(long, env = "AETHER_PROXY_CONNECT_TIMEOUT", default_value_t = 30)]
-    pub connect_timeout_secs: u64,
-
-    /// TLS handshake timeout in seconds for incoming TLS connections
-    #[arg(long, env = "AETHER_PROXY_TLS_HANDSHAKE_TIMEOUT", default_value_t = 10)]
-    pub tls_handshake_timeout_secs: u64,
-
-    /// DNS cache TTL in seconds
-    #[arg(long, env = "AETHER_PROXY_DNS_CACHE_TTL", default_value_t = 60)]
-    pub dns_cache_ttl_secs: u64,
-
-    /// DNS cache capacity (entries)
-    #[arg(long, env = "AETHER_PROXY_DNS_CACHE_CAPACITY", default_value_t = 1024)]
-    pub dns_cache_capacity: usize,
-
-    /// Delegate HTTP client connect timeout in seconds
-    #[arg(
-        long,
-        env = "AETHER_PROXY_DELEGATE_CONNECT_TIMEOUT",
-        default_value_t = 30
-    )]
-    pub delegate_connect_timeout_secs: u64,
-
-    /// Delegate HTTP client max idle connections per host
-    #[arg(
-        long,
-        env = "AETHER_PROXY_DELEGATE_POOL_MAX_IDLE_PER_HOST",
-        default_value_t = 64
-    )]
-    pub delegate_pool_max_idle_per_host: usize,
-
-    /// Delegate HTTP client idle timeout in seconds
-    #[arg(
-        long,
-        env = "AETHER_PROXY_DELEGATE_POOL_IDLE_TIMEOUT",
-        default_value_t = 300
-    )]
-    pub delegate_pool_idle_timeout_secs: u64,
-
-    /// Delegate TCP keepalive in seconds (0 disables)
-    #[arg(
-        long,
-        env = "AETHER_PROXY_DELEGATE_TCP_KEEPALIVE",
-        default_value_t = 60
-    )]
-    pub delegate_tcp_keepalive_secs: u64,
-
-    /// Delegate TCP_NODELAY
-    #[arg(
-        long,
-        env = "AETHER_PROXY_DELEGATE_TCP_NODELAY",
-        default_value_t = true
-    )]
-    pub delegate_tcp_nodelay: bool,
-
-    /// Log level (trace, debug, info, warn, error)
-    #[arg(long, env = "AETHER_PROXY_LOG_LEVEL", default_value = "info")]
-    pub log_level: String,
-
-    /// Output logs as JSON
-    #[arg(long, env = "AETHER_PROXY_LOG_JSON", default_value_t = false)]
-    pub log_json: bool,
-
-    /// Enable TLS encryption (dual-stack: accepts both HTTP and TLS on same port)
-    #[arg(long, env = "AETHER_PROXY_ENABLE_TLS", default_value_t = true)]
-    pub enable_tls: bool,
-
-    /// Path to TLS certificate PEM file
-    #[arg(
-        long,
-        env = "AETHER_PROXY_TLS_CERT",
-        default_value = "aether-proxy-cert.pem"
-    )]
-    pub tls_cert: String,
-
-    /// Path to TLS private key PEM file
-    #[arg(
-        long,
-        env = "AETHER_PROXY_TLS_KEY",
-        default_value = "aether-proxy-key.pem"
-    )]
-    pub tls_key: String,
-}
-
-// ---------------------------------------------------------------------------
-// TOML config file support
-// ---------------------------------------------------------------------------
-
-/// Serializable config for TOML file persistence.
-/// All fields are optional — only populated values are written.
-#[derive(Debug, Default, Serialize, Deserialize)]
-pub struct ConfigFile {
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub aether_url: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub management_token: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub hmac_key: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub listen_port: Option<u16>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub public_ip: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub node_name: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub node_region: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub heartbeat_interval: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub allowed_ports: Option<Vec<u16>>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub timestamp_tolerance: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub aether_request_timeout_secs: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub aether_connect_timeout_secs: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub aether_pool_max_idle_per_host: Option<usize>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub aether_pool_idle_timeout_secs: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub aether_tcp_keepalive_secs: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub aether_tcp_nodelay: Option<bool>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub aether_http2: Option<bool>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub aether_retry_max_attempts: Option<u32>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub aether_retry_base_delay_ms: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub aether_retry_max_delay_ms: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub max_concurrent_connections: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub connect_timeout_secs: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub tls_handshake_timeout_secs: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub dns_cache_ttl_secs: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub dns_cache_capacity: Option<usize>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub delegate_connect_timeout_secs: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub delegate_pool_max_idle_per_host: Option<usize>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub delegate_pool_idle_timeout_secs: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub delegate_tcp_keepalive_secs: Option<u64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub delegate_tcp_nodelay: Option<bool>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub log_level: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub log_json: Option<bool>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub enable_tls: Option<bool>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub tls_cert: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub tls_key: Option<String>,
-}
-
-impl ConfigFile {
-    /// Load from a TOML file.
-    pub fn load(path: &Path) -> anyhow::Result<Self> {
-        let content = std::fs::read_to_string(path)?;
-        Ok(toml::from_str(&content)?)
-    }
-
-    /// Save to a TOML file.
-    pub fn save(&self, path: &Path) -> anyhow::Result<()> {
-        let content = toml::to_string_pretty(self)?;
-        std::fs::write(path, content)?;
-        Ok(())
-    }
-
-    /// Inject values as environment variables so clap picks them up.
-    ///
-    /// Only sets variables that are **not** already present in the
-    /// environment, preserving the precedence: CLI > env > config file.
-    pub fn inject_env(&self) {
-        self.inject_env_inner(false);
-    }
-
-    /// Inject values as environment variables, **overriding** any existing
-    /// values.  Used after setup to ensure the freshly-saved config takes
-    /// effect before re-parsing.
-    pub fn inject_env_override(&self) {
-        self.inject_env_inner(true);
-    }
-
-    fn inject_env_inner(&self, force: bool) {
-        macro_rules! set {
-            ($env:expr, $val:expr) => {
-                if let Some(ref v) = $val {
-                    if force || std::env::var($env).is_err() {
-                        std::env::set_var($env, v.to_string());
-                    }
-                }
-            };
-        }
-        set!("AETHER_PROXY_AETHER_URL", self.aether_url);
-        set!("AETHER_PROXY_MANAGEMENT_TOKEN", self.management_token);
-        set!("AETHER_PROXY_HMAC_KEY", self.hmac_key);
-        set!("AETHER_PROXY_LISTEN_PORT", self.listen_port);
-        set!("AETHER_PROXY_PUBLIC_IP", self.public_ip);
-        set!("AETHER_PROXY_NODE_NAME", self.node_name);
-        set!("AETHER_PROXY_NODE_REGION", self.node_region);
-        set!("AETHER_PROXY_HEARTBEAT_INTERVAL", self.heartbeat_interval);
-        set!("AETHER_PROXY_TIMESTAMP_TOLERANCE", self.timestamp_tolerance);
-        set!(
-            "AETHER_PROXY_AETHER_REQUEST_TIMEOUT",
-            self.aether_request_timeout_secs
-        );
-        set!(
-            "AETHER_PROXY_AETHER_CONNECT_TIMEOUT",
-            self.aether_connect_timeout_secs
-        );
-        set!(
-            "AETHER_PROXY_AETHER_POOL_MAX_IDLE_PER_HOST",
-            self.aether_pool_max_idle_per_host
-        );
-        set!(
-            "AETHER_PROXY_AETHER_POOL_IDLE_TIMEOUT",
-            self.aether_pool_idle_timeout_secs
-        );
-        set!(
-            "AETHER_PROXY_AETHER_TCP_KEEPALIVE",
-            self.aether_tcp_keepalive_secs
-        );
-        set!("AETHER_PROXY_AETHER_TCP_NODELAY", self.aether_tcp_nodelay);
-        set!("AETHER_PROXY_AETHER_HTTP2", self.aether_http2);
-        set!(
-            "AETHER_PROXY_AETHER_RETRY_MAX_ATTEMPTS",
-            self.aether_retry_max_attempts
-        );
-        set!(
-            "AETHER_PROXY_AETHER_RETRY_BASE_DELAY_MS",
-            self.aether_retry_base_delay_ms
-        );
-        set!(
-            "AETHER_PROXY_AETHER_RETRY_MAX_DELAY_MS",
-            self.aether_retry_max_delay_ms
-        );
-        set!(
-            "AETHER_PROXY_MAX_CONCURRENT_CONNECTIONS",
-            self.max_concurrent_connections
-        );
-        set!("AETHER_PROXY_CONNECT_TIMEOUT", self.connect_timeout_secs);
-        set!(
-            "AETHER_PROXY_TLS_HANDSHAKE_TIMEOUT",
-            self.tls_handshake_timeout_secs
-        );
-        set!("AETHER_PROXY_DNS_CACHE_TTL", self.dns_cache_ttl_secs);
-        set!("AETHER_PROXY_DNS_CACHE_CAPACITY", self.dns_cache_capacity);
-        set!(
-            "AETHER_PROXY_DELEGATE_CONNECT_TIMEOUT",
-            self.delegate_connect_timeout_secs
-        );
-        set!(
-            "AETHER_PROXY_DELEGATE_POOL_MAX_IDLE_PER_HOST",
-            self.delegate_pool_max_idle_per_host
-        );
-        set!(
-            "AETHER_PROXY_DELEGATE_POOL_IDLE_TIMEOUT",
-            self.delegate_pool_idle_timeout_secs
-        );
-        set!(
-            "AETHER_PROXY_DELEGATE_TCP_KEEPALIVE",
-            self.delegate_tcp_keepalive_secs
-        );
-        set!(
-            "AETHER_PROXY_DELEGATE_TCP_NODELAY",
-            self.delegate_tcp_nodelay
-        );
-        set!("AETHER_PROXY_LOG_LEVEL", self.log_level);
-        set!("AETHER_PROXY_LOG_JSON", self.log_json);
-        set!("AETHER_PROXY_ENABLE_TLS", self.enable_tls);
-        set!("AETHER_PROXY_TLS_CERT", self.tls_cert);
-        set!("AETHER_PROXY_TLS_KEY", self.tls_key);
-
-        // allowed_ports needs special handling (comma-separated)
-        if let Some(ref ports) = self.allowed_ports {
-            if force || std::env::var("AETHER_PROXY_ALLOWED_PORTS").is_err() {
-                let s: String = ports
-                    .iter()
-                    .map(|p| p.to_string())
-                    .collect::<Vec<_>>()
-                    .join(",");
-                std::env::set_var("AETHER_PROXY_ALLOWED_PORTS", s);
-            }
-        }
-    }
-}

aether-proxy/src/hardware.rs

@@ -1,79 +0,0 @@
-use serde::Serialize;
-use sysinfo::System;
-use tracing::info;
-
-/// Hardware information collected at startup.
-///
-/// The struct is `Serialize`-able so it can be sent directly as the
-/// `hardware_info` JSON bag in the registration request.  New fields
-/// can be added without database schema migrations.
-#[derive(Debug, Clone, Serialize)]
-pub struct HardwareInfo {
-    pub cpu_cores: u32,
-    pub total_memory_mb: u64,
-    pub os_info: String,
-    pub fd_limit: u64,
-    #[serde(skip)]
-    pub estimated_max_concurrency: u64,
-}
-
-/// Collect hardware information and estimate max concurrency.
-///
-/// Should be called once at startup -- hardware does not change at runtime.
-pub fn collect() -> HardwareInfo {
-    let sys = System::new_all();
-
-    let cpu_cores = sys.cpus().len() as u32;
-    let total_memory_mb = sys.total_memory() / (1024 * 1024);
-    let os_info = format!(
-        "{} {}",
-        System::name().unwrap_or_else(|| "Unknown".into()),
-        System::os_version().unwrap_or_default(),
-    )
-    .trim()
-    .to_string();
-
-    // Estimate max concurrent connections:
-    //   - Each tokio async task uses ~8-16 KB stack + heap buffers
-    //   - OS file descriptor limit is often the real bottleneck
-    //   - Conservative formula: min(fd_limit - 100, ram_mb * 40, cpu_cores * 2000)
-    let fd_limit = get_fd_limit();
-    let by_fd = fd_limit.saturating_sub(100);
-    let by_ram = total_memory_mb.saturating_mul(40);
-    let by_cpu = (cpu_cores as u64).saturating_mul(2000);
-    let estimated_max_concurrency = by_fd.min(by_ram).min(by_cpu);
-
-    info!(
-        cpu_cores,
-        total_memory_mb,
-        os_info = %os_info,
-        fd_limit,
-        estimated_max_concurrency,
-        "hardware info collected"
-    );
-
-    HardwareInfo {
-        cpu_cores,
-        total_memory_mb,
-        os_info,
-        fd_limit,
-        estimated_max_concurrency,
-    }
-}
-
-/// Read the soft file-descriptor limit (RLIMIT_NOFILE).
-fn get_fd_limit() -> u64 {
-    #[cfg(unix)]
-    {
-        let mut rlim = libc::rlimit {
-            rlim_cur: 0,
-            rlim_max: 0,
-        };
-        let ret = unsafe { libc::getrlimit(libc::RLIMIT_NOFILE, &mut rlim) };
-        if ret == 0 {
-            return rlim.rlim_cur;
-        }
-    }
-    // Fallback for non-unix or error
-    1024
-}

aether-proxy/src/main.rs

@@ -1,139 +0,0 @@
-mod app;
-mod auth;
-mod config;
-mod hardware;
-mod net;
-mod proxy;
-mod registration;
-mod runtime;
-mod setup;
-mod state;
-
-use std::path::PathBuf;
-
-use clap::{CommandFactory, FromArgMatches, Parser};
-
-use config::Config;
-
-/// Default config file name.
-const DEFAULT_CONFIG: &str = "aether-proxy.toml";
-
-/// Build the full clap command: Config args + discoverable subcommands.
-///
-/// `subcommand_negates_reqs` lets subcommands bypass the required Config
-/// flags so that e.g. `aether-proxy setup` doesn't demand `--aether-url`.
-fn build_command() -> clap::Command {
-    Config::command()
-        .subcommand(
-            clap::Command::new("setup")
-                .about("Interactive setup wizard (TUI)")
-                .arg(
-                    clap::Arg::new("config_path")
-                        .help("Path to config file")
-                        .default_value(DEFAULT_CONFIG),
-                ),
-        )
-        .subcommand(clap::Command::new("start").about("Start the systemd service"))
-        .subcommand(clap::Command::new("status").about("Show service status"))
-        .subcommand(clap::Command::new("logs").about("Tail service logs"))
-        .subcommand(clap::Command::new("restart").about("Restart the systemd service"))
-        .subcommand(clap::Command::new("stop").about("Stop the systemd service"))
-        .subcommand(clap::Command::new("uninstall").about("Uninstall the systemd service"))
-        .subcommand(
-            clap::Command::new("upgrade")
-                .about("Self-upgrade from GitHub releases")
-                .arg(clap::Arg::new("version").help("Target version (e.g. 0.2.0)")),
-        )
-        .subcommand_negates_reqs(true)
-}
-
-#[tokio::main]
-async fn main() -> anyhow::Result<()> {
-    rustls::crypto::ring::default_provider()
-        .install_default()
-        .map_err(|_| anyhow::anyhow!("Failed to install rustls CryptoProvider"))?;
-
-    // Load config file as env-var defaults (before clap parsing)
-    let config_file_path =
-        std::env::var("AETHER_PROXY_CONFIG").unwrap_or_else(|_| DEFAULT_CONFIG.to_string());
-    if std::path::Path::new(&config_file_path).exists() {
-        if let Ok(file_cfg) = config::ConfigFile::load(std::path::Path::new(&config_file_path)) {
-            file_cfg.inject_env();
-        }
-    }
-
-    // Parse CLI (subcommands + config args in one pass)
-    match build_command().try_get_matches() {
-        Ok(matches) => match matches.subcommand() {
-            Some(("setup", sub_m)) => {
-                let path = sub_m
-                    .get_one::<String>("config_path")
-                    .map(PathBuf::from)
-                    .unwrap_or_else(|| PathBuf::from(DEFAULT_CONFIG));
-                handle_setup_result(setup::run(path)?).await
-            }
-            Some(("start", _)) => setup::service::cmd_start(),
-            Some(("status", _)) => setup::service::cmd_status(),
-            Some(("logs", _)) => setup::service::cmd_logs(),
-            Some(("restart", _)) => setup::service::cmd_restart(),
-            Some(("stop", _)) => setup::service::cmd_stop(),
-            Some(("uninstall", _)) => setup::service::cmd_uninstall(),
-            Some(("upgrade", sub_m)) => {
-                let version = sub_m.get_one::<String>("version").cloned();
-                setup::upgrade::cmd_upgrade(version).await
-            }
-            Some(_) => unreachable!(),
-            None => {
-                // No subcommand — run the proxy with parsed config.
-                let config = Config::from_arg_matches(&matches)?;
-                run_proxy(config).await
-            }
-        },
-        Err(e) => {
-            if e.kind() == clap::error::ErrorKind::MissingRequiredArgument {
-                eprintln!("Missing required config, launching setup wizard...\n");
-                handle_setup_result(setup::run(PathBuf::from(&config_file_path))?).await
-            } else {
-                e.exit();
-            }
-        }
-    }
-}
-
-/// Decide what to do after the setup wizard completes.
-async fn handle_setup_result(outcome: setup::SetupOutcome) -> anyhow::Result<()> {
-    match outcome {
-        setup::SetupOutcome::ServiceInstalled => Ok(()),
-        setup::SetupOutcome::ReadyToRun(config_path) => {
-            // Reload config from the file that setup just wrote, overriding
-            // any stale env vars from a previous config.
-            match config::ConfigFile::load(&config_path) {
-                Ok(file_cfg) => file_cfg.inject_env_override(),
-                Err(e) => anyhow::bail!("failed to reload config after setup: {}", e),
-            }
-            // Parse from env-only (argv may still contain "setup" etc.)
-            let config = Config::try_parse_from(["aether-proxy"])
-                .map_err(|e| anyhow::anyhow!("config invalid after setup: {}", e))?;
-            eprintln!("  Starting proxy...\n");
-            run_proxy(config).await
-        }
-        setup::SetupOutcome::Cancelled => {
-            eprintln!("  Setup cancelled.");
-            Ok(())
-        }
-    }
-}
-
-/// Start the proxy server, checking for systemd conflicts first.
-async fn run_proxy(config: Config) -> anyhow::Result<()> {
-    // Warn if systemd service is already running (would cause port conflict).
-    // Skip this check when we ARE the systemd service (INVOCATION_ID is set by systemd).
-    if std::env::var_os("INVOCATION_ID").is_none() && setup::service::is_service_active() {
-        eprintln!("Warning: systemd service is already running.");
-        eprintln!("Use `aether-proxy stop` to stop it first, or manage via subcommands:");
-        eprintln!("  aether-proxy status / logs / restart / stop");
-        std::process::exit(1);
-    }
-
-    app::run(config).await
-}

aether-proxy/src/net.rs

@@ -1,86 +0,0 @@
-//! Network utility functions (public IP detection, region detection).
-//!
-//! These are standalone helpers not tied to any specific client or service.
-
-use reqwest::Client;
-use tracing::{debug, info};
-
-/// Auto-detect public IP by querying external services.
-pub async fn detect_public_ip() -> anyhow::Result<String> {
-    let endpoints = [
-        "https://api.ipify.org",
-        "https://ifconfig.me/ip",
-        "https://icanhazip.com",
-    ];
-
-    let client = Client::builder()
-        .timeout(std::time::Duration::from_secs(5))
-        .build()?;
-
-    for endpoint in &endpoints {
-        match client.get(*endpoint).send().await {
-            Ok(resp) if resp.status().is_success() => {
-                let ip = resp.text().await?.trim().to_string();
-                if !ip.is_empty() {
-                    info!(ip = %ip, source = %endpoint, "detected public IP");
-                    return Ok(ip);
-                }
-            }
-            Ok(resp) => {
-                debug!(endpoint = %endpoint, status = %resp.status(), "IP detection failed");
-            }
-            Err(e) => {
-                debug!(endpoint = %endpoint, error = %e, "IP detection failed");
-            }
-        }
-    }
-
-    anyhow::bail!("failed to detect public IP from any source; use --public-ip")
-}
-
-/// Auto-detect geographic region from a public IP address.
-///
-/// Uses multiple providers with HTTPS preferred.  Falls back to ip-api.com
-/// over plain HTTP (their free tier doesn't support HTTPS).
-/// This is best-effort and non-sensitive -- region detection should never
-/// block startup.
-pub async fn detect_region(ip: &str) -> Option<String> {
-    // Try HTTPS provider first
-    let https_url = format!("https://ipinfo.io/{}/country", ip);
-
-    let client = Client::builder()
-        .timeout(std::time::Duration::from_secs(5))
-        .build()
-        .ok()?;
-
-    // Try ipinfo.io (HTTPS, returns plain text country code)
-    if let Ok(resp) = client.get(&https_url).send().await {
-        if resp.status().is_success() {
-            if let Ok(text) = resp.text().await {
-                let code = text.trim();
-                if !code.is_empty() && code.len() <= 3 {
-                    info!(region = %code, ip = %ip, source = "ipinfo.io", "detected region");
-                    return Some(code.to_string());
-                }
-            }
-        }
-    }
-
-    // Fallback: ip-api.com (HTTP only on free tier, non-sensitive data)
-    let http_url = format!("http://ip-api.com/json/{}?fields=countryCode", ip);
-    match client.get(&http_url).send().await {
-        Ok(resp) if resp.status().is_success() => {
-            let body: serde_json::Value = resp.json().await.ok()?;
-            let code = body.get("countryCode")?.as_str()?;
-            if code.is_empty() {
-                return None;
-            }
-            info!(region = %code, ip = %ip, source = "ip-api.com", "detected region");
-            Some(code.to_string())
-        }
-        _ => {
-            debug!(ip = %ip, "region detection failed");
-            None
-        }
-    }
-}

aether-proxy/src/proxy/connect.rs

@@ -1,163 +0,0 @@
-use std::collections::HashSet;
-use std::sync::Arc;
-use std::time::Duration;
-
-use hyper::body::Incoming;
-use hyper::{Request, Response};
-use tokio::net::TcpStream;
-use tokio::time::timeout;
-use tracing::{debug, warn};
-
-use crate::auth;
-use crate::config::Config;
-use crate::proxy::target_filter::{self, DnsCache};
-
-/// Handle HTTP CONNECT tunnel requests.
-///
-/// Flow: validate auth -> check target filter -> TCP connect -> 200 -> bidirectional copy
-pub async fn handle_connect(
-    req: Request<Incoming>,
-    config: Arc<Config>,
-    allowed_ports: &HashSet<u16>,
-    timestamp_tolerance: u64,
-    dns_cache: &DnsCache,
-) -> Response<http_body_util::Empty<bytes::Bytes>> {
-    // Extract Proxy-Authorization header
-    let proxy_auth = req
-        .headers()
-        .get("proxy-authorization")
-        .and_then(|v| v.to_str().ok());
-
-    // HMAC authentication
-    if let Err(e) = auth::validate_proxy_auth(proxy_auth, &config, timestamp_tolerance) {
-        warn!(error = %e, "CONNECT auth failed");
-        return proxy_auth_required(&e.to_string());
-    }
-
-    // Parse target host:port from CONNECT URI
-    let authority = match req.uri().authority() {
-        Some(auth) => auth.clone(),
-        None => {
-            warn!("CONNECT request missing authority");
-            return bad_request("missing target authority");
-        }
-    };
-
-    let host = authority.host().to_string();
-    let port = authority.port_u16().unwrap_or(443);
-
-    // Target filter: private IP + port whitelist
-    let target_addr =
-        match target_filter::validate_target(&host, port, allowed_ports, dns_cache).await {
-            Ok(addr) => addr,
-            Err(e) => {
-                warn!(host = %host, port, error = %e, "CONNECT target rejected");
-                return forbidden(&e.to_string());
-            }
-        };
-
-    debug!(target = %target_addr, "CONNECT tunnel establishing");
-
-    // Connect to target
-    let connect_timeout = Duration::from_secs(config.connect_timeout_secs);
-    let target_stream = match timeout(connect_timeout, TcpStream::connect(target_addr)).await {
-        Ok(Ok(s)) => s,
-        Ok(Err(e)) => {
-            warn!(target = %target_addr, error = %e, "CONNECT target connection failed");
-            return bad_gateway(&e.to_string());
-        }
-        Err(_) => {
-            warn!(target = %target_addr, "CONNECT target connection timeout");
-            return gateway_timeout("connect timeout");
-        }
-    };
-
-    if let Err(e) = target_stream.set_nodelay(true) {
-        debug!(target = %target_addr, error = %e, "failed to set TCP_NODELAY");
-    }
-
-    // Respond 200 and upgrade connection to raw TCP tunnel
-    let target_display = target_addr.to_string();
-    // Reuse connect_timeout for upgrade: both are connection-phase operations
-    // and should complete within the same order of magnitude.
-    let upgrade_timeout = Duration::from_secs(config.connect_timeout_secs);
-    tokio::task::spawn(async move {
-        match timeout(upgrade_timeout, hyper::upgrade::on(req)).await {
-            Ok(Ok(upgraded)) => {
-                let mut upgraded = hyper_util::rt::TokioIo::new(upgraded);
-                let mut target = target_stream;
-
-                match tokio::io::copy_bidirectional(&mut upgraded, &mut target).await {
-                    Ok((from_client, from_target)) => {
-                        debug!(
-                            target = %target_display,
-                            from_client,
-                            from_target,
-                            "CONNECT tunnel closed"
-                        );
-                    }
-                    Err(e) => {
-                        debug!(target = %target_display, error = %e, "CONNECT tunnel error");
-                    }
-                }
-            }
-            Ok(Err(e)) => {
-                warn!(target = %target_display, error = %e, "CONNECT upgrade failed");
-            }
-            Err(_) => {
-                warn!(target = %target_display, "CONNECT upgrade timeout");
-            }
-        }
-    });
-
-    Response::builder()
-        .status(200)
-        .body(http_body_util::Empty::new())
-        .unwrap()
-}
-
-fn proxy_auth_required(msg: &str) -> Response<http_body_util::Empty<bytes::Bytes>> {
-    Response::builder()
-        .status(407)
-        .header("Proxy-Authenticate", "HMAC-SHA256")
-        .header("Content-Length", "0")
-        .header("X-Error", msg)
-        .body(http_body_util::Empty::new())
-        .unwrap()
-}
-
-fn forbidden(msg: &str) -> Response<http_body_util::Empty<bytes::Bytes>> {
-    Response::builder()
-        .status(403)
-        .header("Content-Length", "0")
-        .header("X-Error", msg)
-        .body(http_body_util::Empty::new())
-        .unwrap()
-}
-
-fn bad_request(msg: &str) -> Response<http_body_util::Empty<bytes::Bytes>> {
-    Response::builder()
-        .status(400)
-        .header("Content-Length", "0")
-        .header("X-Error", msg)
-        .body(http_body_util::Empty::new())
-        .unwrap()
-}
-
-fn bad_gateway(msg: &str) -> Response<http_body_util::Empty<bytes::Bytes>> {
-    Response::builder()
-        .status(502)
-        .header("Content-Length", "0")
-        .header("X-Error", msg)
-        .body(http_body_util::Empty::new())
-        .unwrap()
-}
-
-fn gateway_timeout(msg: &str) -> Response<http_body_util::Empty<bytes::Bytes>> {
-    Response::builder()
-        .status(504)
-        .header("Content-Length", "0")
-        .header("X-Error", msg)
-        .body(http_body_util::Empty::new())
-        .unwrap()
-}

aether-proxy/src/proxy/delegate.rs

@@ -1,389 +0,0 @@
-use std::collections::HashMap;
-use std::collections::HashSet;
-use std::error::Error as StdError;
-use std::sync::Arc;
-use std::time::Instant;
-
-use futures_util::StreamExt;
-use http_body_util::{BodyExt, Full, Limited, StreamBody};
-use hyper::body::{Frame, Incoming};
-use hyper::header::{HeaderName, HeaderValue};
-use hyper::{Method, Request, Response, Uri};
-use tracing::{debug, warn};
-use url::Url;
-
-use super::BoxBody;
-use crate::auth;
-use crate::config::Config;
-use crate::proxy::delegate_client::{ConnectTiming, DelegateClient};
-use crate::proxy::target_filter::{self, DnsCache};
-
-/// Handle delegation requests: Aether sends a full request description,
-/// and the proxy issues the actual upstream HTTP call using its own TLS stack.
-///
-/// Endpoint: POST /_aether/delegate
-///
-/// Wire format: metadata in HTTP headers, upstream body sent directly
-/// as HTTP body (optionally gzip-compressed via `Content-Encoding: gzip`).
-///
-/// Headers:
-///   X-Delegate-Method: POST
-///   X-Delegate-Url: https://api.anthropic.com/v1/messages
-///   X-Delegate-Headers: base64-encoded JSON {"Authorization": "Bearer ...", ...}
-///   X-Delegate-Timeout: 30              (accepted but not used — Aether controls timeouts)
-///   Content-Encoding: gzip              (optional, indicates body is gzip-compressed)
-pub async fn handle_delegate(
-    req: Request<Incoming>,
-    config: Arc<Config>,
-    allowed_ports: &HashSet<u16>,
-    timestamp_tolerance: u64,
-    dns_cache: &DnsCache,
-    http_client: &DelegateClient,
-) -> Response<BoxBody> {
-    let total_start = Instant::now();
-
-    // ── Auth ──
-    let auth_header = req
-        .headers()
-        .get("authorization")
-        .and_then(|v| v.to_str().ok());
-
-    if let Err(e) = auth::validate_proxy_auth(auth_header, &config, timestamp_tolerance) {
-        warn!(error = %e, "delegate auth failed");
-        return error_response(401, "authentication_failed", &e.to_string());
-    }
-    let auth_ms = total_start.elapsed().as_millis() as u64;
-
-    // ── Parse metadata from headers ──
-    let meta_start = Instant::now();
-
-    let method_str = match req
-        .headers()
-        .get("x-delegate-method")
-        .and_then(|v| v.to_str().ok())
-    {
-        Some(m) => m.to_string(),
-        None => {
-            warn!("delegate missing X-Delegate-Method");
-            return error_response(400, "bad_request", "missing X-Delegate-Method header");
-        }
-    };
-
-    let target_url = match req
-        .headers()
-        .get("x-delegate-url")
-        .and_then(|v| v.to_str().ok())
-    {
-        Some(u) => u.to_string(),
-        None => {
-            warn!("delegate missing X-Delegate-Url");
-            return error_response(400, "bad_request", "missing X-Delegate-Url header");
-        }
-    };
-
-    let upstream_headers: HashMap<String, String> = match req
-        .headers()
-        .get("x-delegate-headers")
-        .and_then(|v| v.to_str().ok())
-    {
-        Some(b64) => {
-            match base64::Engine::decode(&base64::engine::general_purpose::STANDARD, b64) {
-                Ok(decoded) => match serde_json::from_slice(&decoded) {
-                    Ok(h) => h,
-                    Err(e) => {
-                        warn!(error = %e, "delegate invalid X-Delegate-Headers JSON");
-                        return error_response(
-                            400,
-                            "bad_request",
-                            "invalid X-Delegate-Headers JSON",
-                        );
-                    }
-                },
-                Err(e) => {
-                    warn!(error = %e, "delegate invalid X-Delegate-Headers base64");
-                    return error_response(400, "bad_request", "invalid X-Delegate-Headers base64");
-                }
-            }
-        }
-        None => HashMap::new(),
-    };
-
-    let is_gzip = req
-        .headers()
-        .get("content-encoding")
-        .and_then(|v| v.to_str().ok())
-        .map(|v| v.eq_ignore_ascii_case("gzip"))
-        .unwrap_or(false);
-
-    let req_content_length: u64 = req
-        .headers()
-        .get("content-length")
-        .and_then(|v| v.to_str().ok())
-        .and_then(|v| v.parse().ok())
-        .unwrap_or(0);
-
-    let meta_ms = meta_start.elapsed().as_millis() as u64;
-
-    // ── Target validation ──
-    let parsed_url = match Url::parse(&target_url) {
-        Ok(u) => u,
-        Err(e) => {
-            warn!(url = %target_url, error = %e, "delegate invalid target URL");
-            return error_response(400, "bad_request", &format!("invalid URL: {}", e));
-        }
-    };
-
-    let host = match parsed_url.host_str() {
-        Some(h) => h.to_string(),
-        None => {
-            warn!(url = %target_url, "delegate target URL missing host");
-            return error_response(400, "bad_request", "URL missing host");
-        }
-    };
-
-    let port = parsed_url.port_or_known_default().unwrap_or(443);
-
-    let dns_start = Instant::now();
-    if let Err(e) = target_filter::validate_target(&host, port, allowed_ports, dns_cache).await {
-        warn!(host = %host, port, error = %e, "delegate target rejected");
-        return error_response(403, "target_not_allowed", &e.to_string());
-    }
-    let dns_ms = dns_start.elapsed().as_millis() as u64;
-
-    debug!(method = %method_str, url = %target_url, is_gzip, "delegate request");
-
-    // ── Build upstream request ──
-    let method = match method_str.parse::<Method>() {
-        Ok(m) => m,
-        Err(e) => {
-            warn!(error = %e, method = %method_str, "delegate invalid HTTP method");
-            return error_response(400, "bad_request", &format!("invalid method: {}", e));
-        }
-    };
-
-    let uri = match target_url.parse::<Uri>() {
-        Ok(u) => u,
-        Err(e) => {
-            warn!(error = %e, url = %target_url, "delegate invalid target URI");
-            return error_response(400, "bad_request", &format!("invalid URL: {}", e));
-        }
-    };
-
-    // ── Stream body passthrough ──
-    // When body is gzip-compressed, forward it directly to upstream with
-    // Content-Encoding: gzip header — no collect/decompress needed.
-    // All major AI API providers (Anthropic, OpenAI, Google) accept gzip request bodies.
-    let wire_size: u64;
-    let upstream_body: BoxBody;
-    if is_gzip {
-        let body_stream =
-            http_body_util::BodyStream::new(req.into_body()).filter_map(|result| async {
-                match result {
-                    Ok(frame) => frame.into_data().ok().map(|data| {
-                        Ok::<_, Box<dyn std::error::Error + Send + Sync>>(Frame::data(data))
-                    }),
-                    Err(e) => Some(Err(Box::new(e) as Box<dyn std::error::Error + Send + Sync>)),
-                }
-            });
-        let stream_body = StreamBody::new(body_stream);
-        upstream_body = BodyExt::boxed(stream_body);
-        // wire_size will be reported from Content-Length if available, otherwise 0
-        wire_size = req_content_length;
-    } else {
-        // Non-gzip: read body into memory (legacy path)
-        const MAX_BODY: usize = 10 * 1024 * 1024;
-        let body_bytes = match Limited::new(req.into_body(), MAX_BODY).collect().await {
-            Ok(collected) => collected.to_bytes(),
-            Err(e) => {
-                warn!(error = %e, "delegate failed to read request body");
-                return error_response(413, "payload_too_large", "request body exceeds 10MB limit");
-            }
-        };
-        wire_size = body_bytes.len() as u64;
-        let body = Full::new(body_bytes)
-            .map_err(|e| -> Box<dyn std::error::Error + Send + Sync> { match e {} })
-            .boxed();
-        upstream_body = body;
-    }
-
-    let mut upstream_req = Request::new(upstream_body);
-    *upstream_req.method_mut() = method;
-    *upstream_req.uri_mut() = uri;
-
-    {
-        let headers = upstream_req.headers_mut();
-        // Set headers (skip `host` — hyper sets it from the URI automatically,
-        // and a duplicate Host header can confuse certain upstreams)
-        for (name, value) in &upstream_headers {
-            if name.eq_ignore_ascii_case("host") {
-                continue;
-            }
-            let header_name = match HeaderName::from_bytes(name.as_bytes()) {
-                Ok(n) => n,
-                Err(_) => {
-                    warn!(header = %name, "delegate invalid header name");
-                    return error_response(400, "bad_request", "invalid header name");
-                }
-            };
-            let header_value = match HeaderValue::from_str(value) {
-                Ok(v) => v,
-                Err(_) => {
-                    warn!(header = %name, "delegate invalid header value");
-                    return error_response(400, "bad_request", "invalid header value");
-                }
-            };
-            headers.insert(header_name, header_value);
-        }
-        if is_gzip {
-            headers.insert(
-                hyper::header::CONTENT_ENCODING,
-                HeaderValue::from_static("gzip"),
-            );
-        }
-    }
-
-    // ── Send upstream request ──
-    // NOTE: We intentionally do NOT set a per-request timeout here.
-    // Connect timeout limits connection establishment; Aether controls
-    // first-byte / idle timeouts on its own side via asyncio.
-    let upstream_start = Instant::now();
-    let upstream_resp = match http_client.request(upstream_req).await {
-        Ok(resp) => resp,
-        Err(e) => {
-            warn!(url = %target_url, error = %e, "delegate upstream request failed");
-            let safe_detail = sanitize_upstream_error(&root_error_message(&e));
-            if is_timeout_error(&e) {
-                return error_response(504, "upstream_timeout", &safe_detail);
-            }
-            return error_response(502, "upstream_connection_failed", &safe_detail);
-        }
-    };
-    let ttfb_ms = upstream_start.elapsed().as_millis() as u64;
-
-    // ── Build response ──
-    let status = upstream_resp.status().as_u16();
-    let resp_headers = upstream_resp.headers().clone();
-    let (connect_ms, tls_ms) = upstream_resp
-        .extensions()
-        .get::<ConnectTiming>()
-        .map(|t| (t.connect_ms, t.tls_ms))
-        .unwrap_or((0, 0));
-    let upstream_processing_ms = ttfb_ms.saturating_sub(connect_ms.saturating_add(tls_ms));
-    let total_ms = total_start.elapsed().as_millis() as u64;
-
-    debug!(
-        url = %target_url,
-        status,
-        dns_ms,
-        connect_ms,
-        tls_ms,
-        ttfb_ms,
-        upstream_processing_ms,
-        total_ms,
-        wire_size,
-        is_gzip,
-        "delegate upstream response"
-    );
-
-    let timing = serde_json::json!({
-        "auth_ms": auth_ms,
-        "meta_ms": meta_ms,
-        "wire_size": wire_size,
-        "passthrough": is_gzip,
-        "dns_ms": dns_ms,
-        "connect_ms": connect_ms,
-        "tls_ms": tls_ms,
-        "ttfb_ms": ttfb_ms,
-        "upstream_ms": ttfb_ms,
-        "upstream_processing_ms": upstream_processing_ms,
-        "total_ms": total_ms,
-    });
-
-    let stream_body: BoxBody = upstream_resp
-        .into_body()
-        .map_err(|e| -> Box<dyn std::error::Error + Send + Sync> { Box::new(e) })
-        .boxed();
-
-    let mut builder = Response::builder().status(status);
-    for (name, value) in resp_headers.iter() {
-        builder = builder.header(name, value);
-    }
-    builder = builder.header("X-Proxy-Timing", timing.to_string());
-
-    builder.body(stream_body).unwrap_or_else(|_| {
-        Response::builder()
-            .status(500)
-            .body(super::empty_box_body())
-            .unwrap()
-    })
-}
-
-fn root_error_message(err: &dyn StdError) -> String {
-    let mut current = err;
-    while let Some(source) = current.source() {
-        current = source;
-    }
-    current.to_string()
-}
-
-fn is_timeout_error(err: &(dyn StdError + 'static)) -> bool {
-    if err.is::<tokio::time::error::Elapsed>() {
-        return true;
-    }
-    if let Some(io_err) = err.downcast_ref::<std::io::Error>() {
-        if io_err.kind() == std::io::ErrorKind::TimedOut {
-            return true;
-        }
-    }
-    if let Some(source) = err.source() {
-        // source() returns &(dyn Error + 'static), so this is safe
-        return is_timeout_error(source);
-    }
-    false
-}
-
-// ── Sanitisation ─────────────────────────────────────────────────────────────
-
-/// Strip full URLs from error messages to prevent leaking upstream API keys,
-/// paths, or query parameters in the delegate error response.
-///
-/// Replaces `https://api.example.com/v1/chat?key=xxx` with `api.example.com`.
-fn sanitize_upstream_error(msg: &str) -> String {
-    // Simple regex-free approach: find "https://..." or "http://..." spans and
-    // replace them with just the host portion.
-    let mut result = msg.to_string();
-    for scheme in &["https://", "http://"] {
-        while let Some(start) = result.find(scheme) {
-            let after_scheme = start + scheme.len();
-            // Host ends at '/', '?', '#', ' ', or end of string
-            let host_end = result[after_scheme..]
-                .find(['/', '?', '#', ' '])
-                .map(|i| after_scheme + i)
-                .unwrap_or(result.len());
-            let host = &result[after_scheme..host_end];
-            result = format!("{}{}{}", &result[..start], host, &result[host_end..]);
-        }
-    }
-    result
-}
-
-// ── Error response helpers ───────────────────────────────────────────────────
-
-fn error_response(status: u16, error: &str, detail: &str) -> Response<BoxBody> {
-    let body = serde_json::json!({
-        "error": error,
-        "detail": detail,
-    });
-    let body_bytes = bytes::Bytes::from(body.to_string());
-
-    Response::builder()
-        .status(status)
-        .header("Content-Type", "application/json")
-        .header("X-Delegate-Error", "true")
-        .body(
-            Full::new(body_bytes)
-                .map_err(|e| -> Box<dyn std::error::Error + Send + Sync> { match e {} })
-                .boxed(),
-        )
-        .unwrap()
-}

aether-proxy/src/proxy/delegate_client.rs

@@ -1,282 +0,0 @@
-use std::future::Future;
-use std::pin::Pin;
-use std::sync::Arc;
-use std::task::{Context, Poll};
-use std::time::{Duration, Instant};
-
-use hyper::rt;
-use hyper::Uri;
-use hyper_util::client::legacy::connect::{Connected, Connection, HttpConnector};
-use hyper_util::client::legacy::Client;
-use hyper_util::rt::{TokioExecutor, TokioIo, TokioTimer};
-use rustls::ClientConfig;
-use rustls_pki_types::ServerName;
-use tokio_rustls::TlsConnector;
-use tower_service::Service;
-
-use crate::config::Config;
-use crate::proxy::BoxBody;
-
-type BoxError = Box<dyn std::error::Error + Send + Sync>;
-
-type DelegateStream = MaybeHttpsStream<TokioIo<tokio::net::TcpStream>>;
-
-type DelegateConn = TimedConn<DelegateStream>;
-
-pub(crate) type DelegateClient = Client<InstrumentedConnector, BoxBody>;
-
-#[derive(Clone, Copy, Debug, Default)]
-pub(crate) struct ConnectTiming {
-    pub connect_ms: u64,
-    pub tls_ms: u64,
-}
-
-pub(crate) fn build_delegate_client(config: &Config) -> DelegateClient {
-    let mut http = HttpConnector::new();
-    http.enforce_http(false);
-    http.set_connect_timeout(Some(Duration::from_secs(
-        config.delegate_connect_timeout_secs,
-    )));
-    http.set_nodelay(config.delegate_tcp_nodelay);
-    if config.delegate_tcp_keepalive_secs > 0 {
-        http.set_keepalive(Some(Duration::from_secs(
-            config.delegate_tcp_keepalive_secs,
-        )));
-    } else {
-        http.set_keepalive(None);
-    }
-
-    let connector = InstrumentedConnector {
-        http,
-        tls_config: build_tls_config(),
-    };
-
-    let mut builder = Client::builder(TokioExecutor::new());
-    builder.pool_max_idle_per_host(config.delegate_pool_max_idle_per_host);
-    builder.pool_idle_timeout(Duration::from_secs(config.delegate_pool_idle_timeout_secs));
-    builder.pool_timer(TokioTimer::new());
-
-    builder.build::<_, BoxBody>(connector)
-}
-
-fn build_tls_config() -> Arc<ClientConfig> {
-    let root_store =
-        rustls::RootCertStore::from_iter(webpki_roots::TLS_SERVER_ROOTS.iter().cloned());
-    let mut config = ClientConfig::builder()
-        .with_root_certificates(root_store)
-        .with_no_client_auth();
-    config.alpn_protocols = vec![b"h2".to_vec(), b"http/1.1".to_vec()];
-    Arc::new(config)
-}
-
-#[derive(Clone)]
-pub(crate) struct InstrumentedConnector {
-    http: HttpConnector,
-    tls_config: Arc<ClientConfig>,
-}
-
-impl Service<Uri> for InstrumentedConnector {
-    type Response = DelegateConn;
-    type Error = BoxError;
-    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, BoxError>> + Send>>;
-
-    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
-        self.http.poll_ready(cx).map_err(Into::into)
-    }
-
-    fn call(&mut self, dst: Uri) -> Self::Future {
-        let scheme = dst.scheme_str().map(|s| s.to_ascii_lowercase());
-        let tls_config = self.tls_config.clone();
-        let connecting = self.http.call(dst.clone());
-        let connect_start = Instant::now();
-
-        Box::pin(async move {
-            match scheme.as_deref() {
-                Some("http") => {
-                    let tcp = connecting.await.map_err(|e| Box::new(e) as BoxError)?;
-                    let connect_ms = connect_start.elapsed().as_millis() as u64;
-                    Ok(TimedConn::new(
-                        MaybeHttpsStream::Http(tcp),
-                        ConnectTiming {
-                            connect_ms,
-                            tls_ms: 0,
-                        },
-                    ))
-                }
-                Some("https") => {
-                    let server_name = resolve_server_name(&dst)?;
-                    let tcp = connecting.await.map_err(|e| Box::new(e) as BoxError)?;
-                    let connect_ms = connect_start.elapsed().as_millis() as u64;
-
-                    let tls_start = Instant::now();
-                    let tls_stream = TlsConnector::from(tls_config)
-                        .connect(server_name, TokioIo::new(tcp))
-                        .await
-                        .map_err(std::io::Error::other)?;
-                    let tls_ms = tls_start.elapsed().as_millis() as u64;
-
-                    Ok(TimedConn::new(
-                        MaybeHttpsStream::Https(TokioIo::new(tls_stream)),
-                        ConnectTiming { connect_ms, tls_ms },
-                    ))
-                }
-                Some(other) => {
-                    Err(std::io::Error::other(format!("unsupported scheme {other}")).into())
-                }
-                None => Err(std::io::Error::other("missing scheme").into()),
-            }
-        })
-    }
-}
-
-fn resolve_server_name(uri: &Uri) -> Result<ServerName<'static>, BoxError> {
-    let host = uri.host().ok_or("missing host")?;
-    let host = host.trim_start_matches('[').trim_end_matches(']');
-    Ok(ServerName::try_from(host.to_string())?)
-}
-
-pub(crate) struct TimedConn<T> {
-    inner: T,
-    timing: ConnectTiming,
-}
-
-impl<T> TimedConn<T> {
-    fn new(inner: T, timing: ConnectTiming) -> Self {
-        Self { inner, timing }
-    }
-}
-
-impl<T: Connection> Connection for TimedConn<T> {
-    fn connected(&self) -> Connected {
-        self.inner.connected().extra(self.timing)
-    }
-}
-
-impl<T: rt::Read + Unpin> rt::Read for TimedConn<T> {
-    fn poll_read(
-        mut self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: rt::ReadBufCursor<'_>,
-    ) -> Poll<Result<(), std::io::Error>> {
-        Pin::new(&mut self.inner).poll_read(cx, buf)
-    }
-}
-
-impl<T: rt::Write + Unpin> rt::Write for TimedConn<T> {
-    fn poll_write(
-        mut self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &[u8],
-    ) -> Poll<Result<usize, std::io::Error>> {
-        Pin::new(&mut self.inner).poll_write(cx, buf)
-    }
-
-    fn poll_flush(
-        mut self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-    ) -> Poll<Result<(), std::io::Error>> {
-        Pin::new(&mut self.inner).poll_flush(cx)
-    }
-
-    fn poll_shutdown(
-        mut self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-    ) -> Poll<Result<(), std::io::Error>> {
-        Pin::new(&mut self.inner).poll_shutdown(cx)
-    }
-
-    fn is_write_vectored(&self) -> bool {
-        self.inner.is_write_vectored()
-    }
-
-    fn poll_write_vectored(
-        mut self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        bufs: &[std::io::IoSlice<'_>],
-    ) -> Poll<Result<usize, std::io::Error>> {
-        Pin::new(&mut self.inner).poll_write_vectored(cx, bufs)
-    }
-}
-
-#[allow(clippy::large_enum_variant)]
-pub(crate) enum MaybeHttpsStream<T> {
-    Http(T),
-    Https(TokioIo<tokio_rustls::client::TlsStream<TokioIo<T>>>),
-}
-
-impl<T: rt::Read + rt::Write + Connection + Unpin> Connection for MaybeHttpsStream<T> {
-    fn connected(&self) -> Connected {
-        match self {
-            Self::Http(stream) => stream.connected(),
-            Self::Https(stream) => {
-                let (tcp, tls) = stream.inner().get_ref();
-                if tls.alpn_protocol() == Some(b"h2") {
-                    tcp.inner().connected().negotiated_h2()
-                } else {
-                    tcp.inner().connected()
-                }
-            }
-        }
-    }
-}
-
-impl<T: rt::Read + rt::Write + Unpin> rt::Read for MaybeHttpsStream<T> {
-    fn poll_read(
-        self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: rt::ReadBufCursor<'_>,
-    ) -> Poll<Result<(), std::io::Error>> {
-        match Pin::get_mut(self) {
-            Self::Http(stream) => Pin::new(stream).poll_read(cx, buf),
-            Self::Https(stream) => Pin::new(stream).poll_read(cx, buf),
-        }
-    }
-}
-
-impl<T: rt::Write + rt::Read + Unpin> rt::Write for MaybeHttpsStream<T> {
-    fn poll_write(
-        self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &[u8],
-    ) -> Poll<Result<usize, std::io::Error>> {
-        match Pin::get_mut(self) {
-            Self::Http(stream) => Pin::new(stream).poll_write(cx, buf),
-            Self::Https(stream) => Pin::new(stream).poll_write(cx, buf),
-        }
-    }
-
-    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), std::io::Error>> {
-        match Pin::get_mut(self) {
-            Self::Http(stream) => Pin::new(stream).poll_flush(cx),
-            Self::Https(stream) => Pin::new(stream).poll_flush(cx),
-        }
-    }
-
-    fn poll_shutdown(
-        self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-    ) -> Poll<Result<(), std::io::Error>> {
-        match Pin::get_mut(self) {
-            Self::Http(stream) => Pin::new(stream).poll_shutdown(cx),
-            Self::Https(stream) => Pin::new(stream).poll_shutdown(cx),
-        }
-    }
-
-    fn is_write_vectored(&self) -> bool {
-        match self {
-            Self::Http(stream) => stream.is_write_vectored(),
-            Self::Https(stream) => stream.is_write_vectored(),
-        }
-    }
-
-    fn poll_write_vectored(
-        self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        bufs: &[std::io::IoSlice<'_>],
-    ) -> Poll<Result<usize, std::io::Error>> {
-        match Pin::get_mut(self) {
-            Self::Http(stream) => Pin::new(stream).poll_write_vectored(cx, bufs),
-            Self::Https(stream) => Pin::new(stream).poll_write_vectored(cx, bufs),
-        }
-    }
-}

aether-proxy/src/proxy/mod.rs

@@ -1,19 +0,0 @@
-pub mod connect;
-pub mod delegate;
-pub mod delegate_client;
-pub mod server;
-pub mod target_filter;
-pub mod tls;
-
-use http_body_util::BodyExt;
-
-/// Boxed body type used across proxy handlers.
-pub type BoxBody =
-    http_body_util::combinators::BoxBody<bytes::Bytes, Box<dyn std::error::Error + Send + Sync>>;
-
-/// Create an empty [`BoxBody`] (for error responses, 405, etc.).
-pub fn empty_box_body() -> BoxBody {
-    http_body_util::Full::new(bytes::Bytes::new())
-        .map_err(|e| -> Box<dyn std::error::Error + Send + Sync> { match e {} })
-        .boxed()
-}

aether-proxy/src/proxy/server.rs

@@ -1,213 +0,0 @@
-use std::net::SocketAddr;
-use std::sync::atomic::Ordering;
-use std::sync::Arc;
-use std::time::{Duration, Instant};
-
-use http_body_util::BodyExt;
-use hyper::body::Incoming;
-use hyper::rt::{Read, Write};
-use hyper::server::conn::http1;
-use hyper::service::service_fn;
-use hyper::{Method, Request, Response};
-use hyper_util::rt::TokioIo;
-use tokio::net::TcpListener;
-use tokio::sync::watch;
-use tokio::time::timeout;
-use tracing::{debug, info, warn};
-
-use crate::proxy::{connect, delegate, tls, BoxBody};
-use crate::state::AppState;
-
-/// Start the proxy server.
-///
-/// Listens for incoming TCP connections and dispatches:
-/// - CONNECT requests -> tunnel handler
-/// - POST /_aether/delegate -> delegate handler
-/// - Other requests -> 405 Method Not Allowed
-///
-/// When TLS is configured, the server operates in dual-stack mode:
-/// it peeks at the first byte of each connection to distinguish TLS ClientHello
-/// (0x16) from plain HTTP, and handles both on the same port.
-pub async fn run(
-    state: &Arc<AppState>,
-    mut shutdown_rx: watch::Receiver<bool>,
-) -> anyhow::Result<()> {
-    let addr = SocketAddr::from(([0, 0, 0, 0], state.config.listen_port));
-    let listener = TcpListener::bind(addr).await?;
-
-    if state.tls_acceptor.is_some() {
-        info!(addr = %addr, "proxy server listening (HTTP+TLS dual-stack)");
-    } else {
-        info!(addr = %addr, "proxy server listening (HTTP only)");
-    }
-
-    let handshake_timeout = Duration::from_secs(state.config.tls_handshake_timeout_secs);
-
-    loop {
-        tokio::select! {
-            result = listener.accept() => {
-                let (stream, peer_addr) = match result {
-                    Ok(v) => v,
-                    Err(e) => {
-                        warn!(error = %e, "failed to accept connection");
-                        continue;
-                    }
-                };
-
-                debug!(peer = %peer_addr, "new connection");
-
-                if let Err(e) = stream.set_nodelay(true) {
-                    debug!(peer = %peer_addr, error = %e, "failed to set TCP_NODELAY");
-                }
-
-                let permit = match state.connection_semaphore.clone().try_acquire_owned() {
-                    Ok(permit) => permit,
-                    Err(_) => {
-                        warn!(peer = %peer_addr, "connection rejected: limit reached");
-                        continue;
-                    }
-                };
-
-                let state = Arc::clone(state);
-                state.active_connections.fetch_add(1, Ordering::Relaxed);
-
-                tokio::task::spawn(async move {
-                    let _permit = permit;
-
-                    // Dual-stack: peek first byte to decide TLS vs plain HTTP
-                    if let Some(ref acceptor) = state.tls_acceptor {
-                        let is_tls = match timeout(handshake_timeout, tls::is_tls_client_hello(&stream)).await {
-                            Ok(v) => v,
-                            Err(_) => {
-                                debug!(peer = %peer_addr, "TLS detection timeout");
-                                state.active_connections.fetch_sub(1, Ordering::Relaxed);
-                                return;
-                            }
-                        };
-
-                        if is_tls {
-                            match timeout(handshake_timeout, acceptor.clone().accept(stream)).await {
-                                Ok(Ok(tls_stream)) => {
-                                    debug!(peer = %peer_addr, "TLS handshake ok");
-                                    serve_connection(
-                                        TokioIo::new(tls_stream),
-                                        peer_addr,
-                                        &state,
-                                    )
-                                    .await;
-                                }
-                                Ok(Err(e)) => {
-                                    debug!(peer = %peer_addr, error = %e, "TLS handshake failed");
-                                }
-                                Err(_) => {
-                                    debug!(peer = %peer_addr, "TLS handshake timeout");
-                                }
-                            }
-                            state.active_connections.fetch_sub(1, Ordering::Relaxed);
-                            return;
-                        }
-                    }
-
-                    // Plain HTTP
-                    serve_connection(
-                        TokioIo::new(stream),
-                        peer_addr,
-                        &state,
-                    )
-                    .await;
-
-                    state.active_connections.fetch_sub(1, Ordering::Relaxed);
-                });
-            }
-            _ = shutdown_rx.changed() => {
-                info!("proxy server shutting down");
-                break;
-            }
-        }
-    }
-
-    Ok(())
-}
-
-/// Serve a single HTTP/1.1 connection (works over both plain TCP and TLS).
-async fn serve_connection<I>(io: I, peer_addr: SocketAddr, state: &Arc<AppState>)
-where
-    I: Read + Write + Unpin + Send + 'static,
-{
-    let config = Arc::clone(&state.config);
-    let dynamic = Arc::clone(&state.dynamic);
-    let delegate_client = state.delegate_client.clone();
-    let dns_cache = Arc::clone(&state.dns_cache);
-    let metrics = Arc::clone(&state.metrics);
-
-    let service = service_fn(move |req: Request<Incoming>| {
-        let config = Arc::clone(&config);
-        let dynamic = Arc::clone(&dynamic);
-        let delegate_client = delegate_client.clone();
-        let dns_cache = Arc::clone(&dns_cache);
-        let metrics = Arc::clone(&metrics);
-
-        async move {
-            let start = Instant::now();
-            // Snapshot current dynamic values (may be updated by remote config)
-            let (allowed_ports, timestamp_tolerance) = {
-                let d = dynamic.read().unwrap();
-                (d.allowed_ports.clone(), d.timestamp_tolerance)
-            };
-
-            if req.method() == Method::CONNECT {
-                let resp = connect::handle_connect(
-                    req,
-                    config,
-                    &allowed_ports,
-                    timestamp_tolerance,
-                    dns_cache.as_ref(),
-                )
-                .await;
-                let resp = resp.map(|_| -> BoxBody {
-                    http_body_util::Empty::new()
-                        .map_err(|e| -> Box<dyn std::error::Error + Send + Sync> { match e {} })
-                        .boxed()
-                });
-                metrics.record_request(start.elapsed());
-                Ok::<_, hyper::Error>(resp)
-            } else if req.uri().path() == "/_aether/delegate" && req.method() == hyper::Method::POST
-            {
-                let resp = delegate::handle_delegate(
-                    req,
-                    config,
-                    &allowed_ports,
-                    timestamp_tolerance,
-                    dns_cache.as_ref(),
-                    &delegate_client,
-                )
-                .await;
-                metrics.record_request(start.elapsed());
-                Ok(resp)
-            } else {
-                // Only CONNECT tunnels and /_aether/delegate are supported;
-                // plain HTTP forward proxy was removed (all API traffic is HTTPS).
-                let resp = Response::builder()
-                    .status(405)
-                    .header("Allow", "CONNECT")
-                    .header("Content-Length", "0")
-                    .body(crate::proxy::empty_box_body())
-                    .unwrap();
-                metrics.record_request(start.elapsed());
-                Ok(resp)
-            }
-        }
-    });
-
-    if let Err(e) = http1::Builder::new()
-        .preserve_header_case(true)
-        .title_case_headers(false)
-        .serve_connection(io, service)
-        .with_upgrades()
-        .await
-    {
-        if !e.to_string().contains("connection closed") {
-            debug!(peer = %peer_addr, error = %e, "connection error");
-        }
-    }
-}

aether-proxy/src/proxy/target_filter.rs

@@ -1,276 +0,0 @@
-use std::collections::{HashMap, HashSet};
-use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
-use std::time::{Duration, Instant};
-
-use tokio::sync::RwLock;
-
-/// Check if an IP address belongs to a private/reserved network.
-fn is_private_ip(ip: &IpAddr) -> bool {
-    match ip {
-        IpAddr::V4(v4) => is_private_ipv4(v4),
-        IpAddr::V6(v6) => is_private_ipv6(v6),
-    }
-}
-
-fn is_private_ipv4(ip: &Ipv4Addr) -> bool {
-    let octets = ip.octets();
-    // 10.0.0.0/8
-    if octets[0] == 10 {
-        return true;
-    }
-    // 172.16.0.0/12
-    if octets[0] == 172 && (16..=31).contains(&octets[1]) {
-        return true;
-    }
-    // 192.168.0.0/16
-    if octets[0] == 192 && octets[1] == 168 {
-        return true;
-    }
-    // 127.0.0.0/8
-    if octets[0] == 127 {
-        return true;
-    }
-    // 169.254.0.0/16 (link-local)
-    if octets[0] == 169 && octets[1] == 254 {
-        return true;
-    }
-    // 0.0.0.0/8
-    if octets[0] == 0 {
-        return true;
-    }
-    false
-}
-
-fn is_private_ipv6(ip: &Ipv6Addr) -> bool {
-    // ::1 loopback
-    if ip.is_loopback() {
-        return true;
-    }
-    // :: unspecified
-    if ip.is_unspecified() {
-        return true;
-    }
-    let segments = ip.segments();
-    // fc00::/7 (ULA) - first byte is 0xfc or 0xfd
-    if segments[0] & 0xfe00 == 0xfc00 {
-        return true;
-    }
-    // fe80::/10 (link-local)
-    if segments[0] & 0xffc0 == 0xfe80 {
-        return true;
-    }
-    // IPv4-mapped IPv6 (::ffff:x.x.x.x) - check the embedded IPv4
-    if let Some(v4) = ip.to_ipv4_mapped() {
-        return is_private_ipv4(&v4);
-    }
-    false
-}
-
-#[derive(Debug)]
-pub enum FilterError {
-    PrivateIp(IpAddr),
-    PortNotAllowed(u16),
-    DnsResolutionFailed(String),
-}
-
-impl std::fmt::Display for FilterError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            Self::PrivateIp(ip) => write!(f, "target IP {} is in private/reserved range", ip),
-            Self::PortNotAllowed(port) => write!(f, "port {} not in allowed list", port),
-            Self::DnsResolutionFailed(host) => write!(f, "DNS resolution failed for {}", host),
-        }
-    }
-}
-
-struct DnsCacheEntry {
-    addr: SocketAddr,
-    expires_at: Instant,
-    inserted_at: Instant,
-}
-
-/// Lightweight DNS cache with TTL + capacity bounds.
-pub struct DnsCache {
-    ttl: Duration,
-    capacity: usize,
-    entries: RwLock<HashMap<String, DnsCacheEntry>>,
-}
-
-impl DnsCache {
-    pub fn new(ttl: Duration, capacity: usize) -> Self {
-        Self {
-            ttl,
-            capacity,
-            entries: RwLock::new(HashMap::new()),
-        }
-    }
-
-    pub async fn get(&self, host: &str, port: u16) -> Option<SocketAddr> {
-        if self.capacity == 0 || self.ttl.is_zero() {
-            return None;
-        }
-        let key = Self::key(host, port);
-        let now = Instant::now();
-
-        // Fast path: read lock for cache hit
-        {
-            let entries = self.entries.read().await;
-            match entries.get(&key) {
-                Some(entry) if entry.expires_at > now => return Some(entry.addr),
-                None => return None,
-                Some(_) => {} // expired, fall through to evict
-            }
-        }
-
-        // Slow path: write lock to remove expired entry
-        let mut entries = self.entries.write().await;
-        entries.remove(&key);
-        None
-    }
-
-    pub async fn insert(&self, host: &str, port: u16, addr: SocketAddr) {
-        if self.capacity == 0 || self.ttl.is_zero() {
-            return;
-        }
-        let key = Self::key(host, port);
-        let now = Instant::now();
-        let mut entries = self.entries.write().await;
-        entries.retain(|_, entry| entry.expires_at > now);
-        while entries.len() >= self.capacity {
-            let oldest_key = entries
-                .iter()
-                .min_by_key(|(_, entry)| entry.inserted_at)
-                .map(|(key, _)| key.clone());
-            if let Some(key) = oldest_key {
-                entries.remove(&key);
-            } else {
-                break;
-            }
-        }
-        entries.insert(
-            key,
-            DnsCacheEntry {
-                addr,
-                expires_at: now + self.ttl,
-                inserted_at: now,
-            },
-        );
-    }
-
-    fn key(host: &str, port: u16) -> String {
-        format!("{}:{}", host, port)
-    }
-}
-
-/// Validate that the target host:port is allowed.
-///
-/// Uses async DNS resolution (via `tokio::net::lookup_host`) to avoid
-/// blocking the async runtime on potentially slow DNS lookups.
-///
-/// Returns the resolved socket address to connect to.
-pub async fn validate_target(
-    host: &str,
-    port: u16,
-    allowed_ports: &HashSet<u16>,
-    dns_cache: &DnsCache,
-) -> Result<SocketAddr, FilterError> {
-    // Port whitelist check
-    if !allowed_ports.contains(&port) {
-        return Err(FilterError::PortNotAllowed(port));
-    }
-
-    // Try parsing as IP directly (no DNS needed)
-    if let Ok(ip) = host.parse::<IpAddr>() {
-        if is_private_ip(&ip) {
-            return Err(FilterError::PrivateIp(ip));
-        }
-        return Ok(SocketAddr::new(ip, port));
-    }
-
-    if let Some(addr) = dns_cache.get(host, port).await {
-        return Ok(addr);
-    }
-
-    // Async DNS resolution with private IP check (DNS rebinding protection)
-    let addr_str = format!("{}:{}", host, port);
-    let addrs: Vec<SocketAddr> = tokio::net::lookup_host(&addr_str)
-        .await
-        .map_err(|_| FilterError::DnsResolutionFailed(host.to_string()))?
-        .collect();
-
-    if addrs.is_empty() {
-        return Err(FilterError::DnsResolutionFailed(host.to_string()));
-    }
-
-    // All resolved addresses must be non-private
-    for addr in &addrs {
-        if is_private_ip(&addr.ip()) {
-            return Err(FilterError::PrivateIp(addr.ip()));
-        }
-    }
-
-    // Return the first valid address
-    let selected = addrs[0];
-    dns_cache.insert(host, port, selected).await;
-    Ok(selected)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn ports() -> HashSet<u16> {
-        [80, 443, 8080, 8443].into_iter().collect()
-    }
-
-    fn cache() -> DnsCache {
-        DnsCache::new(Duration::from_secs(60), 128)
-    }
-
-    #[test]
-    fn test_private_ipv4() {
-        assert!(is_private_ip(&IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1))));
-        assert!(is_private_ip(&IpAddr::V4(Ipv4Addr::new(172, 16, 0, 1))));
-        assert!(is_private_ip(&IpAddr::V4(Ipv4Addr::new(192, 168, 1, 1))));
-        assert!(is_private_ip(&IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1))));
-        assert!(is_private_ip(&IpAddr::V4(Ipv4Addr::new(169, 254, 1, 1))));
-        assert!(is_private_ip(&IpAddr::V4(Ipv4Addr::new(0, 0, 0, 0))));
-        assert!(!is_private_ip(&IpAddr::V4(Ipv4Addr::new(8, 8, 8, 8))));
-        assert!(!is_private_ip(&IpAddr::V4(Ipv4Addr::new(203, 0, 113, 1))));
-    }
-
-    #[test]
-    fn test_private_ipv6() {
-        assert!(is_private_ip(&IpAddr::V6(Ipv6Addr::LOCALHOST)));
-        assert!(is_private_ip(&IpAddr::V6(Ipv6Addr::UNSPECIFIED)));
-        // fc00::1 (ULA)
-        assert!(is_private_ip(&IpAddr::V6(Ipv6Addr::new(
-            0xfc00, 0, 0, 0, 0, 0, 0, 1
-        ))));
-        // fe80::1 (link-local)
-        assert!(is_private_ip(&IpAddr::V6(Ipv6Addr::new(
-            0xfe80, 0, 0, 0, 0, 0, 0, 1
-        ))));
-    }
-
-    #[tokio::test]
-    async fn test_port_not_allowed() {
-        let cache = cache();
-        let result = validate_target("8.8.8.8", 22, &ports(), &cache).await;
-        assert!(matches!(result, Err(FilterError::PortNotAllowed(22))));
-    }
-
-    #[tokio::test]
-    async fn test_private_ip_blocked() {
-        let cache = cache();
-        let result = validate_target("127.0.0.1", 80, &ports(), &cache).await;
-        assert!(matches!(result, Err(FilterError::PrivateIp(_))));
-    }
-
-    #[tokio::test]
-    async fn test_public_ip_allowed() {
-        let cache = cache();
-        let result = validate_target("8.8.8.8", 443, &ports(), &cache).await;
-        assert!(result.is_ok());
-    }
-}

aether-proxy/src/proxy/tls.rs

@@ -1,125 +0,0 @@
-use std::fs;
-use std::io::BufReader;
-use std::path::Path;
-use std::sync::Arc;
-
-use rcgen::{CertificateParams, KeyPair};
-use rustls_pki_types::{CertificateDer, PrivateKeyDer};
-use sha2::{Digest, Sha256};
-use tokio_rustls::TlsAcceptor;
-use tracing::{info, warn};
-
-const SESSION_CACHE_SIZE: usize = 1024;
-
-/// Generate a self-signed certificate if the files do not already exist.
-///
-/// The certificate includes SANs: `localhost` and `aether-proxy`.
-/// The private key file is set to mode 0600 on unix.
-pub fn ensure_self_signed_cert(cert_path: &Path, key_path: &Path) -> anyhow::Result<()> {
-    if cert_path.exists() && key_path.exists() {
-        info!(
-            cert = %cert_path.display(),
-            key = %key_path.display(),
-            "using existing TLS certificate"
-        );
-        return Ok(());
-    }
-
-    info!("generating self-signed TLS certificate");
-
-    let mut params = CertificateParams::new(vec!["localhost".into(), "aether-proxy".into()])?;
-    params.distinguished_name = rcgen::DistinguishedName::new();
-    params
-        .distinguished_name
-        .push(rcgen::DnType::CommonName, "aether-proxy");
-
-    let key_pair = KeyPair::generate()?;
-    let cert = params.self_signed(&key_pair)?;
-
-    let cert_pem = cert.pem();
-    let key_pem = key_pair.serialize_pem();
-
-    fs::write(cert_path, &cert_pem)?;
-    fs::write(key_path, &key_pem)?;
-
-    // Set key file permissions to 0600 on unix
-    #[cfg(unix)]
-    {
-        use std::os::unix::fs::PermissionsExt;
-        let perms = fs::Permissions::from_mode(0o600);
-        fs::set_permissions(key_path, perms)?;
-    }
-
-    info!(
-        cert = %cert_path.display(),
-        key = %key_path.display(),
-        "self-signed TLS certificate generated"
-    );
-
-    Ok(())
-}
-
-/// Build a `TlsAcceptor` from PEM certificate and key files.
-pub fn build_tls_acceptor(cert_path: &Path, key_path: &Path) -> anyhow::Result<TlsAcceptor> {
-    let cert_file = fs::File::open(cert_path)?;
-    let key_file = fs::File::open(key_path)?;
-
-    let certs: Vec<CertificateDer<'static>> =
-        rustls_pemfile::certs(&mut BufReader::new(cert_file)).collect::<Result<Vec<_>, _>>()?;
-
-    if certs.is_empty() {
-        anyhow::bail!("no certificates found in {}", cert_path.display());
-    }
-
-    let key: PrivateKeyDer<'static> =
-        rustls_pemfile::private_key(&mut BufReader::new(key_file))?
-            .ok_or_else(|| anyhow::anyhow!("no private key found in {}", key_path.display()))?;
-
-    let mut config = rustls::ServerConfig::builder()
-        .with_no_client_auth()
-        .with_single_cert(certs, key)?;
-
-    config.alpn_protocols = vec![b"http/1.1".to_vec()];
-    config.session_storage = rustls::server::ServerSessionMemoryCache::new(SESSION_CACHE_SIZE);
-    match rustls::crypto::ring::Ticketer::new() {
-        Ok(ticketer) => {
-            config.ticketer = ticketer;
-        }
-        Err(e) => {
-            warn!(error = %e, "failed to init TLS ticketer; tickets disabled");
-        }
-    }
-
-    Ok(TlsAcceptor::from(Arc::new(config)))
-}
-
-/// Compute the SHA-256 fingerprint of the first certificate in a PEM file.
-///
-/// Returns the hex-encoded fingerprint (lowercase, no separators).
-pub fn cert_sha256_fingerprint(cert_path: &Path) -> anyhow::Result<String> {
-    let cert_file = fs::File::open(cert_path)?;
-    let certs: Vec<CertificateDer<'static>> =
-        rustls_pemfile::certs(&mut BufReader::new(cert_file)).collect::<Result<Vec<_>, _>>()?;
-
-    let cert = certs
-        .first()
-        .ok_or_else(|| anyhow::anyhow!("no certificates found in {}", cert_path.display()))?;
-
-    let digest = Sha256::digest(cert.as_ref());
-    Ok(hex::encode(digest))
-}
-
-/// Peek at the first byte of a TCP stream to determine if it is a TLS ClientHello.
-///
-/// Returns `true` if the first byte is 0x16 (TLS record type: Handshake).
-pub async fn is_tls_client_hello(stream: &tokio::net::TcpStream) -> bool {
-    let mut buf = [0u8; 1];
-    match stream.peek(&mut buf).await {
-        Ok(1) => buf[0] == 0x16,
-        Ok(_) => false,
-        Err(e) => {
-            warn!(error = %e, "failed to peek first byte");
-            false
-        }
-    }
-}

aether-proxy/src/registration/client.rs

@@ -1,385 +0,0 @@
-use std::time::{Duration, SystemTime, UNIX_EPOCH};
-
-use reqwest::{Client, StatusCode};
-use serde::{Deserialize, Serialize};
-use tokio::time::sleep;
-use tracing::{debug, error, info, warn};
-
-use crate::config::Config;
-use crate::hardware::HardwareInfo;
-
-/// Heartbeat-specific error that distinguishes "node not found" (needs
-/// re-registration) from transient / other failures.
-#[derive(Debug)]
-pub enum HeartbeatError {
-    /// HTTP 404 – the node_id is no longer known to Aether.
-    NodeNotFound(String),
-    /// Any other failure (network, 5xx, etc.).
-    Other(anyhow::Error),
-}
-
-impl std::fmt::Display for HeartbeatError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            Self::NodeNotFound(msg) => write!(f, "node not found: {}", msg),
-            Self::Other(e) => write!(f, "{}", e),
-        }
-    }
-}
-
-#[derive(Debug, Serialize)]
-struct RegisterRequest {
-    name: String,
-    ip: String,
-    port: u16,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    region: Option<String>,
-    heartbeat_interval: u64,
-    #[serde(skip_serializing_if = "std::ops::Not::not")]
-    tls_enabled: bool,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    tls_cert_fingerprint: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    hardware_info: Option<serde_json::Value>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    estimated_max_concurrency: Option<u64>,
-}
-
-#[derive(Debug, Deserialize)]
-pub struct RegisterResponse {
-    pub node_id: String,
-}
-
-#[derive(Debug, Serialize)]
-struct HeartbeatRequest {
-    node_id: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    active_connections: Option<i64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    total_requests: Option<i64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    avg_latency_ms: Option<f64>,
-}
-
-/// Remote configuration pushed by the Aether management backend.
-#[derive(Debug, Clone, Deserialize)]
-pub struct RemoteConfig {
-    pub node_name: Option<String>,
-    pub allowed_ports: Option<Vec<u16>>,
-    pub log_level: Option<String>,
-    pub heartbeat_interval: Option<u64>,
-    pub timestamp_tolerance: Option<u64>,
-}
-
-/// Parsed heartbeat response from Aether.
-#[derive(Debug, Deserialize)]
-struct HeartbeatResponseBody {
-    #[serde(default)]
-    node: Option<HeartbeatNodeInfo>,
-}
-
-#[derive(Debug, Deserialize)]
-struct HeartbeatNodeInfo {
-    #[serde(default)]
-    remote_config: Option<RemoteConfig>,
-    #[serde(default)]
-    config_version: Option<u64>,
-}
-
-/// Heartbeat result returned to the caller.
-#[derive(Debug)]
-pub struct HeartbeatResult {
-    pub remote_config: Option<RemoteConfig>,
-    pub config_version: u64,
-}
-
-#[derive(Debug, Serialize)]
-struct UnregisterRequest {
-    node_id: String,
-}
-
-/// Aether API client for proxy node lifecycle management.
-pub struct AetherClient {
-    http: Client,
-    base_url: String,
-    token: String,
-    retry_max_attempts: u32,
-    retry_base_delay: Duration,
-    retry_max_delay: Duration,
-}
-
-impl AetherClient {
-    pub fn new(config: &Config) -> Self {
-        let mut builder = Client::builder()
-            .timeout(Duration::from_secs(config.aether_request_timeout_secs))
-            .connect_timeout(Duration::from_secs(config.aether_connect_timeout_secs))
-            .pool_max_idle_per_host(config.aether_pool_max_idle_per_host)
-            .pool_idle_timeout(Duration::from_secs(config.aether_pool_idle_timeout_secs))
-            .tcp_nodelay(config.aether_tcp_nodelay);
-
-        if config.aether_tcp_keepalive_secs > 0 {
-            builder =
-                builder.tcp_keepalive(Some(Duration::from_secs(config.aether_tcp_keepalive_secs)));
-        } else {
-            builder = builder.tcp_keepalive(None);
-        }
-
-        if config.aether_http2 {
-            builder = builder.http2_adaptive_window(true);
-        }
-
-        let http = builder.build().expect("failed to create HTTP client");
-
-        let retry_base_delay = Duration::from_millis(config.aether_retry_base_delay_ms);
-        let retry_max_delay =
-            Duration::from_millis(config.aether_retry_max_delay_ms).max(retry_base_delay);
-
-        Self {
-            http,
-            base_url: config.aether_url.trim_end_matches('/').to_string(),
-            token: config.management_token.clone(),
-            retry_max_attempts: config.aether_retry_max_attempts.max(1),
-            retry_base_delay,
-            retry_max_delay,
-        }
-    }
-
-    /// Register this node with Aether (idempotent upsert by ip:port).
-    ///
-    /// Returns the stable node_id assigned by Aether.
-    pub async fn register(
-        &self,
-        config: &Config,
-        public_ip: &str,
-        tls_enabled: bool,
-        tls_cert_fingerprint: Option<&str>,
-        hw: Option<&HardwareInfo>,
-    ) -> anyhow::Result<String> {
-        let url = format!("{}/api/admin/proxy-nodes/register", self.base_url);
-        let body = RegisterRequest {
-            name: config.node_name.clone(),
-            ip: public_ip.to_string(),
-            port: config.listen_port,
-            region: config.node_region.clone(),
-            heartbeat_interval: config.heartbeat_interval,
-            tls_enabled,
-            tls_cert_fingerprint: tls_cert_fingerprint.map(|s| s.to_string()),
-            hardware_info: hw.and_then(|h| serde_json::to_value(h).ok()),
-            estimated_max_concurrency: hw.map(|h| h.estimated_max_concurrency),
-        };
-
-        info!(
-            url = %url,
-            name = %body.name,
-            ip = %body.ip,
-            port = body.port,
-            "registering with Aether"
-        );
-
-        let resp = self
-            .send_with_retry(
-                || {
-                    self.http
-                        .post(&url)
-                        .header("Authorization", format!("Bearer {}", self.token))
-                        .json(&body)
-                },
-                "register",
-            )
-            .await?;
-
-        let status = resp.status();
-        if !status.is_success() {
-            let text = resp.text().await.unwrap_or_default();
-            anyhow::bail!("register failed (HTTP {}): {}", status, text);
-        }
-
-        let data: RegisterResponse = resp.json().await?;
-        info!(node_id = %data.node_id, "registered successfully");
-        Ok(data.node_id)
-    }
-
-    /// Send heartbeat to Aether.
-    ///
-    /// On success, returns any remote config included in the response.
-    /// Returns [`HeartbeatError::NodeNotFound`] on HTTP 404 so the caller
-    /// can trigger re-registration.
-    pub async fn heartbeat(
-        &self,
-        node_id: &str,
-        active_connections: Option<i64>,
-        total_requests: Option<i64>,
-        avg_latency_ms: Option<f64>,
-    ) -> Result<HeartbeatResult, HeartbeatError> {
-        let url = format!("{}/api/admin/proxy-nodes/heartbeat", self.base_url);
-        let body = HeartbeatRequest {
-            node_id: node_id.to_string(),
-            active_connections,
-            total_requests,
-            avg_latency_ms,
-        };
-
-        debug!(node_id = %node_id, "sending heartbeat");
-
-        let resp = self
-            .send_with_retry(
-                || {
-                    self.http
-                        .post(&url)
-                        .header("Authorization", format!("Bearer {}", self.token))
-                        .json(&body)
-                },
-                "heartbeat",
-            )
-            .await
-            .map_err(|e| HeartbeatError::Other(e.into()))?;
-
-        let status = resp.status();
-        if !status.is_success() {
-            let text = resp.text().await.unwrap_or_default();
-            warn!(status = %status, body = %text, "heartbeat failed");
-            if status == StatusCode::NOT_FOUND {
-                return Err(HeartbeatError::NodeNotFound(text));
-            }
-            return Err(HeartbeatError::Other(anyhow::anyhow!(
-                "heartbeat failed (HTTP {}): {}",
-                status,
-                text
-            )));
-        }
-
-        // Parse remote config from response (best-effort)
-        let result = match resp.json::<HeartbeatResponseBody>().await {
-            Ok(body) => {
-                let (remote_config, config_version) = match body.node {
-                    Some(node) => (node.remote_config, node.config_version.unwrap_or(0)),
-                    None => (None, 0),
-                };
-                HeartbeatResult {
-                    remote_config,
-                    config_version,
-                }
-            }
-            Err(e) => {
-                debug!(error = %e, "failed to parse heartbeat response body");
-                HeartbeatResult {
-                    remote_config: None,
-                    config_version: 0,
-                }
-            }
-        };
-
-        debug!(node_id = %node_id, config_version = result.config_version, "heartbeat ok");
-        Ok(result)
-    }
-
-    /// Unregister this node from Aether (graceful shutdown).
-    pub async fn unregister(&self, node_id: &str) -> anyhow::Result<()> {
-        let url = format!("{}/api/admin/proxy-nodes/unregister", self.base_url);
-        let body = UnregisterRequest {
-            node_id: node_id.to_string(),
-        };
-
-        info!(node_id = %node_id, "unregistering from Aether");
-
-        let resp = self
-            .send_with_retry(
-                || {
-                    self.http
-                        .post(&url)
-                        .header("Authorization", format!("Bearer {}", self.token))
-                        .json(&body)
-                },
-                "unregister",
-            )
-            .await;
-
-        match resp {
-            Ok(r) if r.status().is_success() => {
-                info!(node_id = %node_id, "unregistered successfully");
-                Ok(())
-            }
-            Ok(r) => {
-                let text = r.text().await.unwrap_or_default();
-                error!(body = %text, "unregister failed");
-                anyhow::bail!("unregister failed: {}", text);
-            }
-            Err(e) => {
-                // Best-effort during shutdown
-                error!(error = %e, "unregister request failed");
-                anyhow::bail!("unregister request failed: {}", e);
-            }
-        }
-    }
-
-    async fn send_with_retry<F>(
-        &self,
-        mut make_req: F,
-        label: &str,
-    ) -> Result<reqwest::Response, reqwest::Error>
-    where
-        F: FnMut() -> reqwest::RequestBuilder,
-    {
-        let mut attempt: u32 = 0;
-        let mut delay = self.retry_base_delay;
-
-        loop {
-            attempt = attempt.saturating_add(1);
-            let resp = make_req().send().await;
-            match resp {
-                Ok(resp) => {
-                    if should_retry_status(resp.status()) && attempt < self.retry_max_attempts {
-                        let sleep_for = jitter_delay(delay);
-                        debug!(
-                            attempt,
-                            status = %resp.status(),
-                            sleep_ms = sleep_for.as_millis(),
-                            label,
-                            "Aether request retrying"
-                        );
-                        sleep(sleep_for).await;
-                        let next_delay = delay.checked_mul(2).unwrap_or(self.retry_max_delay);
-                        delay = std::cmp::min(next_delay, self.retry_max_delay);
-                        continue;
-                    }
-                    return Ok(resp);
-                }
-                Err(e) => {
-                    if attempt < self.retry_max_attempts {
-                        let sleep_for = jitter_delay(delay);
-                        debug!(
-                            attempt,
-                            error = %e,
-                            sleep_ms = sleep_for.as_millis(),
-                            label,
-                            "Aether request retrying"
-                        );
-                        sleep(sleep_for).await;
-                        let next_delay = delay.checked_mul(2).unwrap_or(self.retry_max_delay);
-                        delay = std::cmp::min(next_delay, self.retry_max_delay);
-                        continue;
-                    }
-                    return Err(e);
-                }
-            }
-        }
-    }
-}
-
-fn should_retry_status(status: StatusCode) -> bool {
-    status.is_server_error()
-        || status == StatusCode::TOO_MANY_REQUESTS
-        || status == StatusCode::REQUEST_TIMEOUT
-}
-
-fn jitter_delay(base: Duration) -> Duration {
-    if base.is_zero() {
-        return base;
-    }
-    let nanos = SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .map(|d| d.subsec_nanos() as u64)
-        .unwrap_or(0);
-    let jitter_ms = nanos % 100;
-    base + Duration::from_millis(jitter_ms)
-}

aether-proxy/src/registration/heartbeat.rs

@@ -1,127 +0,0 @@
-use std::sync::atomic::Ordering;
-use std::sync::Arc;
-
-use tokio::sync::watch;
-use tracing::{debug, error, info, warn};
-
-use crate::registration::client::HeartbeatError;
-use crate::runtime;
-use crate::state::AppState;
-
-/// Run periodic heartbeat task until shutdown signal.
-///
-/// When Aether responds with 404 (node not found), this task automatically
-/// re-registers the node and updates the shared `node_id` so the proxy
-/// server and future heartbeats use the new identity.
-///
-/// When the heartbeat response includes a `remote_config`, it is applied
-/// to the [`DynamicConfig`](crate::runtime::DynamicConfig) so the proxy
-/// picks up changes without a restart.
-pub async fn run(state: &Arc<AppState>, mut shutdown_rx: watch::Receiver<bool>) {
-    let mut consecutive_failures: u32 = 0;
-
-    // Skip the first tick (registration already acts as initial heartbeat)
-    let initial_interval = state.dynamic.read().unwrap().heartbeat_interval;
-    tokio::select! {
-        _ = tokio::time::sleep(std::time::Duration::from_secs(initial_interval)) => {}
-        _ = shutdown_rx.changed() => {
-            debug!("heartbeat task stopping (during initial wait)");
-            return;
-        }
-    }
-
-    loop {
-        let current_node_id = state.node_id.read().unwrap().clone();
-        let active_conns = state.active_connections.load(Ordering::Relaxed) as i64;
-
-        // Swap-and-reset: report incremental metrics since last heartbeat
-        let interval_requests = state.metrics.total_requests.swap(0, Ordering::Relaxed);
-        let interval_latency_ns = state.metrics.total_latency_ns.swap(0, Ordering::Relaxed);
-        let interval_requests_i64 = i64::try_from(interval_requests).unwrap_or(i64::MAX);
-        let avg_latency_ms = if interval_requests > 0 {
-            Some(interval_latency_ns as f64 / interval_requests as f64 / 1_000_000.0)
-        } else {
-            None
-        };
-
-        match state
-            .aether_client
-            .heartbeat(
-                &current_node_id,
-                Some(active_conns),
-                Some(interval_requests_i64),
-                avg_latency_ms,
-            )
-            .await
-        {
-            Ok(result) => {
-                if consecutive_failures > 0 {
-                    info!(
-                        previous_failures = consecutive_failures,
-                        "heartbeat recovered"
-                    );
-                }
-                consecutive_failures = 0;
-
-                // Apply remote config if present and version changed
-                if let Some(ref remote) = result.remote_config {
-                    runtime::apply_remote_config(&state.dynamic, remote, result.config_version);
-                }
-            }
-            Err(HeartbeatError::NodeNotFound(_)) => {
-                warn!(
-                    old_node_id = %current_node_id,
-                    "node not found, re-registering"
-                );
-                match state
-                    .aether_client
-                    .register(
-                        &state.config,
-                        &state.public_ip,
-                        state.config.enable_tls,
-                        state.tls_fingerprint.as_deref(),
-                        Some(&state.hardware_info),
-                    )
-                    .await
-                {
-                    Ok(new_id) => {
-                        info!(
-                            old_node_id = %current_node_id,
-                            new_node_id = %new_id,
-                            "re-registered successfully"
-                        );
-                        *state.node_id.write().unwrap() = new_id;
-                        consecutive_failures = 0;
-                    }
-                    Err(e) => {
-                        consecutive_failures += 1;
-                        error!(
-                            error = %e,
-                            consecutive_failures,
-                            "re-registration failed"
-                        );
-                    }
-                }
-            }
-            Err(HeartbeatError::Other(e)) => {
-                consecutive_failures += 1;
-                warn!(
-                    error = %e,
-                    consecutive_failures,
-                    "heartbeat failed"
-                );
-            }
-        }
-
-        // Read interval from dynamic config (may have been updated remotely)
-        let interval_secs = state.dynamic.read().unwrap().heartbeat_interval;
-
-        tokio::select! {
-            _ = tokio::time::sleep(std::time::Duration::from_secs(interval_secs)) => {}
-            _ = shutdown_rx.changed() => {
-                debug!("heartbeat task stopping");
-                break;
-            }
-        }
-    }
-}

aether-proxy/src/registration/mod.rs

@@ -1,2 +0,0 @@
-pub mod client;
-pub mod heartbeat;

aether-proxy/src/runtime.rs

@@ -1,123 +0,0 @@
-//! Runtime-mutable configuration that can be updated remotely via heartbeat.
-//!
-//! Fields in [`DynamicConfig`] are initially populated from the static
-//! [`Config`](crate::config::Config) and may be overridden by the Aether
-//! management backend through the heartbeat response.
-
-use std::collections::HashSet;
-use std::sync::{Arc, OnceLock, RwLock};
-
-use tracing::info;
-
-use crate::config::Config;
-
-/// Configuration that can be changed at runtime without restart.
-#[derive(Debug)]
-pub struct DynamicConfig {
-    pub node_name: String,
-    pub allowed_ports: HashSet<u16>,
-    pub timestamp_tolerance: u64,
-    pub log_level: String,
-    pub heartbeat_interval: u64,
-    /// Monotonically increasing version from the backend.
-    /// `0` means no remote config has ever been applied.
-    pub config_version: u64,
-}
-
-impl DynamicConfig {
-    /// Initialize from static config (startup defaults).
-    pub fn from_config(config: &Config) -> Self {
-        Self {
-            node_name: config.node_name.clone(),
-            allowed_ports: config.allowed_ports.iter().copied().collect(),
-            timestamp_tolerance: config.timestamp_tolerance,
-            log_level: config.log_level.clone(),
-            heartbeat_interval: config.heartbeat_interval,
-            config_version: 0,
-        }
-    }
-}
-
-/// Shared dynamic config handle.
-pub type SharedDynamicConfig = Arc<RwLock<DynamicConfig>>;
-
-// ── Log-level hot-reload ─────────────────────────────────────────────────────
-
-/// Global log-level reloader function, set during tracing init.
-type LogReloader = Box<dyn Fn(&str) + Send + Sync>;
-
-static LOG_RELOADER: OnceLock<LogReloader> = OnceLock::new();
-
-/// Register the log-level reload function (called once from `init_tracing`).
-pub fn set_log_reloader(f: LogReloader) {
-    let _ = LOG_RELOADER.set(f);
-}
-
-/// Apply a remote config update to the dynamic config.
-///
-/// Returns `true` if the config was actually changed.
-pub fn apply_remote_config(
-    dynamic: &SharedDynamicConfig,
-    remote: &crate::registration::client::RemoteConfig,
-    version: u64,
-) -> bool {
-    let mut cfg = dynamic.write().unwrap();
-
-    if version <= cfg.config_version {
-        return false;
-    }
-
-    let mut changed = Vec::new();
-
-    if let Some(ref name) = remote.node_name {
-        if *name != cfg.node_name {
-            changed.push(format!("node_name → {}", name));
-            cfg.node_name = name.clone();
-        }
-    }
-
-    if let Some(ref ports) = remote.allowed_ports {
-        let new_set: HashSet<u16> = ports.iter().copied().collect();
-        if new_set != cfg.allowed_ports {
-            changed.push(format!("allowed_ports → {:?}", ports));
-            cfg.allowed_ports = new_set;
-        }
-    }
-
-    if let Some(tol) = remote.timestamp_tolerance {
-        if tol != cfg.timestamp_tolerance {
-            changed.push(format!("timestamp_tolerance → {}", tol));
-            cfg.timestamp_tolerance = tol;
-        }
-    }
-
-    if let Some(interval) = remote.heartbeat_interval {
-        if interval != cfg.heartbeat_interval {
-            changed.push(format!("heartbeat_interval → {}s", interval));
-            cfg.heartbeat_interval = interval;
-        }
-    }
-
-    if let Some(ref level) = remote.log_level {
-        if *level != cfg.log_level {
-            changed.push(format!("log_level → {}", level));
-            cfg.log_level = level.clone();
-            // Hot-reload tracing filter
-            if let Some(reloader) = LOG_RELOADER.get() {
-                reloader(level);
-            }
-        }
-    }
-
-    cfg.config_version = version;
-
-    if !changed.is_empty() {
-        info!(
-            version,
-            changes = %changed.join(", "),
-            "remote config applied"
-        );
-    }
-
-    !changed.is_empty()
-}

aether-proxy/src/setup/service.rs

@@ -1,255 +0,0 @@
-//! Systemd service installation for aether-proxy.
-//!
-//! Called from the setup TUI when the user enables "Install Service".
-//! The unit file points to the binary and config at their current
-//! absolute paths -- no files are copied.
-
-use std::path::Path;
-use std::process::Command;
-
-const UNIT_PATH: &str = "/etc/systemd/system/aether-proxy.service";
-const SERVICE_NAME: &str = "aether-proxy";
-
-/// Whether systemd service installation is possible (systemd present + root).
-pub fn is_available() -> bool {
-    is_systemd_available() && is_root()
-}
-
-/// Install aether-proxy as a systemd service.  Must be run as root.
-pub fn install_service(config_path: &Path) -> anyhow::Result<()> {
-    if !is_systemd_available() {
-        anyhow::bail!("systemd not available");
-    }
-    if !is_root() {
-        anyhow::bail!("root required, use: sudo aether-proxy setup");
-    }
-
-    let exe_path = std::env::current_exe()?.canonicalize()?;
-    let exe_str = exe_path
-        .to_str()
-        .ok_or_else(|| anyhow::anyhow!("binary path contains invalid UTF-8"))?;
-
-    let config_abs = std::fs::canonicalize(config_path)?;
-    let config_str = config_abs
-        .to_str()
-        .ok_or_else(|| anyhow::anyhow!("config path contains invalid UTF-8"))?;
-
-    let working_dir = config_abs
-        .parent()
-        .unwrap_or_else(|| Path::new("/"))
-        .to_str()
-        .unwrap_or("/");
-
-    // Stop existing service if running (ignore errors)
-    if Path::new(UNIT_PATH).exists() {
-        eprintln!("  Stopping existing service...");
-        let _ = Command::new("systemctl")
-            .args(["stop", SERVICE_NAME])
-            .status();
-    }
-
-    // Write unit file
-    eprintln!("  Generating systemd unit file...");
-    eprintln!("    Binary:  {}", exe_str);
-    eprintln!("    Config:  {}", config_str);
-    eprintln!("    WorkDir: {}", working_dir);
-
-    let unit_content = format!(
-        "[Unit]\n\
-         Description=Aether Proxy\n\
-         After=network.target\n\
-         \n\
-         [Service]\n\
-         Type=simple\n\
-         WorkingDirectory={working_dir}\n\
-         Environment=AETHER_PROXY_CONFIG={config_str}\n\
-         ExecStart={exe_str}\n\
-         Restart=on-failure\n\
-         RestartSec=5\n\
-         LimitNOFILE=65535\n\
-         \n\
-         [Install]\n\
-         WantedBy=multi-user.target\n",
-    );
-    std::fs::write(UNIT_PATH, &unit_content)?;
-
-    // Reload and enable
-    eprintln!("  Enabling and starting service...");
-    run_cmd("systemctl", &["daemon-reload"])?;
-    run_cmd("systemctl", &["enable", "--now", SERVICE_NAME])?;
-
-    // Verify
-    eprintln!();
-    let output = Command::new("systemctl")
-        .args(["is-active", SERVICE_NAME])
-        .output()?;
-    let state = String::from_utf8_lossy(&output.stdout).trim().to_string();
-
-    if state == "active" {
-        eprintln!("  Service started successfully!");
-    } else {
-        eprintln!("  Service state: {} (check logs)", state);
-    }
-
-    eprintln!();
-    eprintln!("  Commands:");
-    eprintln!("    aether-proxy status          # service status");
-    eprintln!("    aether-proxy logs            # tail logs");
-    eprintln!("    sudo aether-proxy restart    # restart");
-    eprintln!("    sudo aether-proxy stop       # stop");
-    eprintln!("    sudo aether-proxy uninstall  # remove service");
-    eprintln!();
-
-    Ok(())
-}
-
-fn is_systemd_available() -> bool {
-    Command::new("systemctl")
-        .arg("--version")
-        .stdout(std::process::Stdio::null())
-        .stderr(std::process::Stdio::null())
-        .status()
-        .map(|s| s.success())
-        .unwrap_or(false)
-}
-
-pub(crate) fn is_root() -> bool {
-    #[cfg(unix)]
-    {
-        unsafe { libc::geteuid() == 0 }
-    }
-    #[cfg(not(unix))]
-    {
-        false
-    }
-}
-
-/// Whether a systemd unit file is currently installed.
-pub fn is_installed() -> bool {
-    Path::new(UNIT_PATH).exists()
-}
-
-/// Remove the systemd service (called from setup TUI when Install Service is toggled off).
-pub fn uninstall_service() -> anyhow::Result<()> {
-    if !Path::new(UNIT_PATH).exists() {
-        return Ok(());
-    }
-
-    eprintln!("  Stopping and removing existing service...");
-    let _ = Command::new("systemctl")
-        .args(["disable", "--now", SERVICE_NAME])
-        .status();
-
-    std::fs::remove_file(UNIT_PATH)?;
-    eprintln!("  Removed {}", UNIT_PATH);
-    run_cmd("systemctl", &["daemon-reload"])?;
-    eprintln!("  Service uninstalled.");
-    eprintln!();
-
-    Ok(())
-}
-
-/// Check if the systemd service is currently active.
-pub fn is_service_active() -> bool {
-    std::path::Path::new(UNIT_PATH).exists()
-        && Command::new("systemctl")
-            .args(["is-active", "--quiet", SERVICE_NAME])
-            .stdout(std::process::Stdio::null())
-            .stderr(std::process::Stdio::null())
-            .status()
-            .map(|s| s.success())
-            .unwrap_or(false)
-}
-
-// ── CLI subcommands (systemd wrappers) ──────────────────────────────────────
-
-fn ensure_service_installed() -> anyhow::Result<()> {
-    if !std::path::Path::new(UNIT_PATH).exists() {
-        anyhow::bail!("service not installed, run `sudo aether-proxy setup` first");
-    }
-    Ok(())
-}
-
-fn ensure_root_and_service() -> anyhow::Result<()> {
-    ensure_service_installed()?;
-    if !is_root() {
-        anyhow::bail!("root required, use: sudo aether-proxy <command>");
-    }
-    Ok(())
-}
-
-/// `aether-proxy status` -- show service status.
-pub fn cmd_status() -> anyhow::Result<()> {
-    ensure_service_installed()?;
-    let status = Command::new("systemctl")
-        .args(["status", SERVICE_NAME])
-        .status()?;
-    // systemctl status returns non-zero when inactive; that's fine
-    std::process::exit(status.code().unwrap_or(1));
-}
-
-/// `aether-proxy logs` -- tail service logs.
-pub fn cmd_logs() -> anyhow::Result<()> {
-    ensure_service_installed()?;
-    let status = Command::new("journalctl")
-        .args(["-u", SERVICE_NAME, "-f", "--no-pager", "-n", "100"])
-        .status()?;
-    std::process::exit(status.code().unwrap_or(1));
-}
-
-/// `aether-proxy start` -- start the service.
-pub fn cmd_start() -> anyhow::Result<()> {
-    ensure_root_and_service()?;
-    run_cmd("systemctl", &["start", SERVICE_NAME])?;
-    eprintln!("  Service started.");
-    Ok(())
-}
-
-/// `aether-proxy restart` -- restart the service.
-pub fn cmd_restart() -> anyhow::Result<()> {
-    ensure_root_and_service()?;
-    run_cmd("systemctl", &["restart", SERVICE_NAME])?;
-    eprintln!("  Service restarted.");
-    Ok(())
-}
-
-/// `aether-proxy stop` -- stop the service.
-pub fn cmd_stop() -> anyhow::Result<()> {
-    ensure_root_and_service()?;
-    run_cmd("systemctl", &["stop", SERVICE_NAME])?;
-    eprintln!("  Service stopped.");
-    Ok(())
-}
-
-/// `aether-proxy uninstall` -- disable and remove the systemd service.
-pub fn cmd_uninstall() -> anyhow::Result<()> {
-    ensure_root_and_service()?;
-
-    eprintln!("  Stopping and disabling service...");
-    let _ = Command::new("systemctl")
-        .args(["disable", "--now", SERVICE_NAME])
-        .status();
-
-    if std::path::Path::new(UNIT_PATH).exists() {
-        std::fs::remove_file(UNIT_PATH)?;
-        eprintln!("  Removed {}", UNIT_PATH);
-    }
-
-    run_cmd("systemctl", &["daemon-reload"])?;
-    eprintln!("  Service uninstalled.");
-    eprintln!();
-    eprintln!("  Config file and TLS certs are preserved. Remove manually if needed.");
-
-    Ok(())
-}
-
-pub(crate) fn run_cmd(program: &str, args: &[&str]) -> anyhow::Result<()> {
-    let display = format!("{} {}", program, args.join(" "));
-    eprintln!("  > {}", display);
-
-    let status = Command::new(program).args(args).status()?;
-    if !status.success() {
-        anyhow::bail!("command failed: {}", display);
-    }
-    Ok(())
-}

aether-proxy/src/setup/tui.rs

@@ -1,695 +0,0 @@
-//! Interactive TUI for configuring aether-proxy.
-//!
-//! Launched via `aether-proxy setup [path]`.  Presents a full-screen form
-//! backed by ratatui where the user can navigate fields, edit values, and
-//! save to a TOML config file.
-
-use std::io;
-use std::path::PathBuf;
-use std::time::{Duration, Instant};
-
-use crossterm::event::{self, Event, KeyCode, KeyEvent, KeyEventKind, KeyModifiers};
-use crossterm::execute;
-use crossterm::terminal::{self, EnterAlternateScreen, LeaveAlternateScreen};
-use ratatui::backend::CrosstermBackend;
-use ratatui::layout::{Constraint, Layout, Rect};
-use ratatui::style::{Color, Modifier, Style};
-use ratatui::text::{Line, Span};
-use ratatui::widgets::{Block, Borders, Paragraph};
-use ratatui::Frame;
-use ratatui::Terminal;
-
-use crate::config::ConfigFile;
-
-/// Outcome of the setup wizard, returned to the caller.
-pub enum SetupOutcome {
-    /// Config saved; systemd service installed and started.
-    ServiceInstalled,
-    /// Config saved; no service — caller should start the proxy directly.
-    ReadyToRun(PathBuf),
-    /// User quit without saving.
-    Cancelled,
-}
-
-/// Column width reserved for the field label (chars).
-const LABEL_WIDTH: usize = 22;
-
-// ── Field types ──────────────────────────────────────────────────────────────
-
-#[derive(Clone, Copy, PartialEq)]
-enum FieldKind {
-    Text,
-    Secret,
-    Number,
-    Bool,
-    LogLevel,
-}
-
-struct Field {
-    label: &'static str,
-    key: &'static str,
-    value: String,
-    kind: FieldKind,
-    required: bool,
-    help: &'static str,
-}
-
-// ── App state ────────────────────────────────────────────────────────────────
-
-#[derive(PartialEq)]
-enum Mode {
-    Normal,
-    Editing,
-}
-
-struct App {
-    fields: Vec<Field>,
-    selected: usize,
-    mode: Mode,
-    edit_buffer: String,
-    edit_cursor: usize, // char index
-    config_path: PathBuf,
-    modified: bool,
-    message: Option<(String, Instant, bool)>, // (text, when, is_error)
-    scroll_offset: usize,
-    saved_once: bool,
-    pending_quit: bool, // true after first q/Esc with unsaved changes
-}
-
-impl App {
-    fn new(config_path: PathBuf) -> Self {
-        Self {
-            fields: vec![
-                Field {
-                    label: "Aether URL",
-                    key: "aether_url",
-                    value: String::new(),
-                    kind: FieldKind::Text,
-                    required: true,
-                    help: "Aether 服务器 URL (如 https://aether.example.com)",
-                },
-                Field {
-                    label: "Management Token",
-                    key: "management_token",
-                    value: String::new(),
-                    kind: FieldKind::Secret,
-                    required: true,
-                    help: "Aether 管理 API Token (ae_xxx)",
-                },
-                Field {
-                    label: "HMAC Key",
-                    key: "hmac_key",
-                    value: String::new(),
-                    kind: FieldKind::Secret,
-                    required: true,
-                    help: "HMAC-SHA256 签名密钥，用于代理请求认证",
-                },
-                Field {
-                    label: "Listen Port",
-                    key: "listen_port",
-                    value: "18080".into(),
-                    kind: FieldKind::Number,
-                    required: true,
-                    help: "代理服务监听端口",
-                },
-                Field {
-                    label: "Node Name",
-                    key: "node_name",
-                    value: "proxy-01".into(),
-                    kind: FieldKind::Text,
-                    required: true,
-                    help: "节点名称，用于在 Aether 后台识别",
-                },
-                Field {
-                    label: "Log Level",
-                    key: "log_level",
-                    value: "info".into(),
-                    kind: FieldKind::LogLevel,
-                    required: true,
-                    help: "日志级别 -- Enter 切换: trace / debug / info / warn / error",
-                },
-                Field {
-                    label: "Log JSON",
-                    key: "log_json",
-                    value: "false".into(),
-                    kind: FieldKind::Bool,
-                    required: true,
-                    help: "是否以 JSON 格式输出日志 -- Enter 切换",
-                },
-                Field {
-                    label: "Install Service",
-                    key: "install_service",
-                    value: if super::service::is_available() {
-                        "true"
-                    } else {
-                        "false"
-                    }
-                    .into(),
-                    kind: FieldKind::Bool,
-                    required: true,
-                    help: "注册为 systemd 开机启动服务 (需要 root 权限) -- Enter 切换",
-                },
-            ],
-            selected: 0,
-            mode: Mode::Normal,
-            edit_buffer: String::new(),
-            edit_cursor: 0,
-            config_path,
-            modified: false,
-            message: None,
-            scroll_offset: 0,
-            saved_once: false,
-            pending_quit: false,
-        }
-    }
-
-    // ── Config ↔ fields ──────────────────────────────────────────────────
-
-    fn load_from_file(&mut self) {
-        if let Ok(cfg) = ConfigFile::load(&self.config_path) {
-            self.apply_config(&cfg);
-        }
-    }
-
-    fn apply_config(&mut self, cfg: &ConfigFile) {
-        for field in &mut self.fields {
-            let val: Option<String> = match field.key {
-                "aether_url" => cfg.aether_url.clone(),
-                "management_token" => cfg.management_token.clone(),
-                "hmac_key" => cfg.hmac_key.clone(),
-                "listen_port" => cfg.listen_port.map(|v| v.to_string()),
-                "node_name" => cfg.node_name.clone(),
-                "log_level" => cfg.log_level.clone(),
-                "log_json" => cfg.log_json.map(|v| v.to_string()),
-                _ => None,
-            };
-            if let Some(v) = val {
-                field.value = v;
-            }
-        }
-    }
-
-    fn to_config(&self) -> ConfigFile {
-        let get = |key: &str| -> Option<String> {
-            self.fields
-                .iter()
-                .find(|f| f.key == key)
-                .map(|f| f.value.clone())
-                .filter(|v| !v.is_empty())
-        };
-
-        ConfigFile {
-            aether_url: get("aether_url"),
-            management_token: get("management_token"),
-            hmac_key: get("hmac_key"),
-            listen_port: get("listen_port").and_then(|v| v.parse().ok()),
-            public_ip: None,
-            node_name: get("node_name"),
-            node_region: None,
-            heartbeat_interval: None,
-            allowed_ports: None,
-            timestamp_tolerance: None,
-            aether_request_timeout_secs: None,
-            aether_connect_timeout_secs: None,
-            aether_pool_max_idle_per_host: None,
-            aether_pool_idle_timeout_secs: None,
-            aether_tcp_keepalive_secs: None,
-            aether_tcp_nodelay: None,
-            aether_http2: None,
-            aether_retry_max_attempts: None,
-            aether_retry_base_delay_ms: None,
-            aether_retry_max_delay_ms: None,
-            max_concurrent_connections: None,
-            connect_timeout_secs: None,
-            tls_handshake_timeout_secs: None,
-            dns_cache_ttl_secs: None,
-            dns_cache_capacity: None,
-            delegate_connect_timeout_secs: None,
-            delegate_pool_max_idle_per_host: None,
-            delegate_pool_idle_timeout_secs: None,
-            delegate_tcp_keepalive_secs: None,
-            delegate_tcp_nodelay: None,
-            log_level: get("log_level"),
-            log_json: get("log_json").and_then(|v| v.parse().ok()),
-            enable_tls: None,
-            tls_cert: None,
-            tls_key: None,
-        }
-    }
-
-    fn save(&mut self) -> anyhow::Result<()> {
-        let cfg = self.to_config();
-        cfg.save(&self.config_path)?;
-        self.modified = false;
-        self.saved_once = true;
-        self.message = Some((
-            format!("saved to {}", self.config_path.display()),
-            Instant::now(),
-            false,
-        ));
-        Ok(())
-    }
-
-    // ── Scrolling ────────────────────────────────────────────────────────
-
-    fn ensure_visible(&mut self, visible_rows: usize) {
-        if visible_rows == 0 {
-            return;
-        }
-        if self.selected < self.scroll_offset {
-            self.scroll_offset = self.selected;
-        } else if self.selected >= self.scroll_offset + visible_rows {
-            self.scroll_offset = self.selected - visible_rows + 1;
-        }
-    }
-
-    // ── Key handling ─────────────────────────────────────────────────────
-
-    /// Returns `true` when the app should exit.
-    fn handle_key(&mut self, key: KeyEvent) -> bool {
-        // Expire old messages (but keep quit-confirmation messages alive)
-        if let Some((_, when, _)) = &self.message {
-            if !self.pending_quit && when.elapsed() > Duration::from_secs(4) {
-                self.message = None;
-            }
-        }
-
-        match self.mode {
-            Mode::Normal => self.handle_normal(key),
-            Mode::Editing => {
-                self.handle_edit(key);
-                false
-            }
-        }
-    }
-
-    fn handle_normal(&mut self, key: KeyEvent) -> bool {
-        // ── Quit handling (with unsaved-changes confirmation) ─────────
-        let is_quit_key = matches!(key.code, KeyCode::Char('q') | KeyCode::Esc);
-
-        if is_quit_key {
-            if !self.modified || self.pending_quit {
-                return true;
-            }
-            self.pending_quit = true;
-            self.message = Some((
-                "unsaved changes! q again to discard, ^S to save".into(),
-                Instant::now(),
-                true,
-            ));
-            return false;
-        }
-
-        // Any other key cancels the pending quit
-        if self.pending_quit {
-            self.pending_quit = false;
-            self.message = None;
-        }
-
-        match key.code {
-            KeyCode::Char('s') if key.modifiers.contains(KeyModifiers::CONTROL) => {
-                if let Err(e) = self.save() {
-                    self.message = Some((format!("error: {}", e), Instant::now(), true));
-                }
-            }
-            KeyCode::Up | KeyCode::Char('k') => {
-                self.selected = self.selected.saturating_sub(1);
-            }
-            KeyCode::Down | KeyCode::Char('j') => {
-                if self.selected + 1 < self.fields.len() {
-                    self.selected += 1;
-                }
-            }
-            KeyCode::Home => self.selected = 0,
-            KeyCode::End => self.selected = self.fields.len() - 1,
-            KeyCode::Enter | KeyCode::Char(' ') => {
-                let field = &self.fields[self.selected];
-                match field.kind {
-                    FieldKind::Bool => {
-                        let toggled = if field.value == "true" {
-                            "false"
-                        } else {
-                            "true"
-                        };
-                        // Block enabling service install without root/systemd
-                        if field.key == "install_service"
-                            && toggled == "true"
-                            && !super::service::is_available()
-                        {
-                            self.message = Some((
-                                "requires root with systemd, use: sudo aether-proxy setup".into(),
-                                Instant::now(),
-                                true,
-                            ));
-                        } else {
-                            self.fields[self.selected].value = toggled.into();
-                            self.modified = true;
-                        }
-                    }
-                    FieldKind::LogLevel => {
-                        const LEVELS: &[&str] = &["trace", "debug", "info", "warn", "error"];
-                        let idx = LEVELS.iter().position(|l| *l == field.value).unwrap_or(2);
-                        self.fields[self.selected].value = LEVELS[(idx + 1) % LEVELS.len()].into();
-                        self.modified = true;
-                    }
-                    _ => {
-                        self.edit_buffer = field.value.clone();
-                        self.edit_cursor = self.edit_buffer.chars().count();
-                        self.mode = Mode::Editing;
-                    }
-                }
-            }
-            KeyCode::Tab => {
-                // Quick save shortcut
-                if let Err(e) = self.save() {
-                    self.message = Some((format!("error: {}", e), Instant::now(), true));
-                }
-            }
-            _ => {}
-        }
-        false
-    }
-
-    fn handle_edit(&mut self, key: KeyEvent) {
-        match key.code {
-            KeyCode::Esc => {
-                // Cancel -- discard changes to this field
-                self.mode = Mode::Normal;
-            }
-            KeyCode::Enter => {
-                if self.validate_edit() {
-                    self.fields[self.selected].value = self.edit_buffer.clone();
-                    self.modified = true;
-                    self.mode = Mode::Normal;
-                } else {
-                    self.message = Some(("invalid format".into(), Instant::now(), true));
-                }
-            }
-            KeyCode::Backspace => {
-                if self.edit_cursor > 0 {
-                    self.edit_cursor -= 1;
-                    let byte = self.char_byte_pos(self.edit_cursor);
-                    self.edit_buffer.remove(byte);
-                }
-            }
-            KeyCode::Delete => {
-                if self.edit_cursor < self.edit_buffer.chars().count() {
-                    let byte = self.char_byte_pos(self.edit_cursor);
-                    self.edit_buffer.remove(byte);
-                }
-            }
-            KeyCode::Left => {
-                self.edit_cursor = self.edit_cursor.saturating_sub(1);
-            }
-            KeyCode::Right => {
-                let len = self.edit_buffer.chars().count();
-                if self.edit_cursor < len {
-                    self.edit_cursor += 1;
-                }
-            }
-            KeyCode::Home => self.edit_cursor = 0,
-            KeyCode::End => self.edit_cursor = self.edit_buffer.chars().count(),
-            KeyCode::Char(c) => {
-                let byte = self.char_byte_pos(self.edit_cursor);
-                self.edit_buffer.insert(byte, c);
-                self.edit_cursor += 1;
-            }
-            _ => {}
-        }
-    }
-
-    fn validate_edit(&self) -> bool {
-        let kind = self.fields[self.selected].kind;
-        let buf = &self.edit_buffer;
-        match kind {
-            FieldKind::Number => buf.is_empty() || buf.parse::<u64>().is_ok(),
-            _ => true,
-        }
-    }
-
-    /// Byte offset of the char at `char_idx`.
-    fn char_byte_pos(&self, char_idx: usize) -> usize {
-        self.edit_buffer
-            .char_indices()
-            .nth(char_idx)
-            .map(|(i, _)| i)
-            .unwrap_or(self.edit_buffer.len())
-    }
-}
-
-// ── Rendering ────────────────────────────────────────────────────────────────
-
-fn ui(f: &mut Frame, app: &mut App) {
-    let area = f.area();
-
-    // Outer block
-    let title = if app.modified {
-        " Aether Proxy Setup [*] "
-    } else {
-        " Aether Proxy Setup "
-    };
-
-    let outer = Block::default()
-        .borders(Borders::ALL)
-        .title(title)
-        .title_alignment(ratatui::layout::Alignment::Center)
-        .border_style(Style::default().fg(Color::Cyan));
-
-    let inner = outer.inner(area);
-    f.render_widget(outer, area);
-
-    // Split: fields | footer
-    let chunks = Layout::vertical([Constraint::Min(1), Constraint::Length(4)]).split(inner);
-
-    let fields_area = chunks[0];
-    let footer_area = chunks[1];
-
-    render_fields(f, app, fields_area);
-    render_footer(f, app, footer_area);
-}
-
-fn render_fields(f: &mut Frame, app: &mut App, area: Rect) {
-    let visible = area.height as usize;
-    app.ensure_visible(visible);
-
-    let mut lines: Vec<Line> = Vec::new();
-
-    for (i, field) in app.fields.iter().enumerate() {
-        if i < app.scroll_offset || i >= app.scroll_offset + visible {
-            continue;
-        }
-
-        let selected = i == app.selected;
-        let indicator = if selected { " > " } else { "   " };
-
-        let label_style = if selected {
-            Style::default()
-                .fg(Color::Cyan)
-                .add_modifier(Modifier::BOLD)
-        } else {
-            Style::default().fg(Color::DarkGray)
-        };
-
-        let padded_label = format!("{:<width$}", field.label, width = LABEL_WIDTH);
-
-        // Value display
-        let (value_text, value_style) = if app.mode == Mode::Editing && selected {
-            (app.edit_buffer.clone(), Style::default().fg(Color::Yellow))
-        } else {
-            field_display(field)
-        };
-
-        lines.push(Line::from(vec![
-            Span::styled(indicator, label_style),
-            Span::styled(padded_label, label_style),
-            Span::raw("  "),
-            Span::styled(value_text, value_style),
-        ]));
-    }
-
-    let paragraph = Paragraph::new(lines);
-    f.render_widget(paragraph, area);
-
-    // Cursor position while editing
-    if app.mode == Mode::Editing {
-        let row_in_view = app.selected - app.scroll_offset;
-        // prefix: 3 (indicator) + LABEL_WIDTH + 2 (gap) = 27
-        let prefix: u16 = 3 + LABEL_WIDTH as u16 + 2;
-        let cx = area.x + prefix + app.edit_cursor as u16;
-        let cy = area.y + row_in_view as u16;
-        if cx < area.x + area.width && cy < area.y + area.height {
-            f.set_cursor_position((cx, cy));
-        }
-    }
-}
-
-/// Returns (display_text, style) for a field in normal mode.
-fn field_display(field: &Field) -> (String, Style) {
-    if field.value.is_empty() {
-        let text = if field.required {
-            "(required)".into()
-        } else {
-            "-".into()
-        };
-        let color = if field.required {
-            Color::Red
-        } else {
-            Color::DarkGray
-        };
-        return (text, Style::default().fg(color));
-    }
-
-    match field.kind {
-        FieldKind::Secret => (
-            "*".repeat(field.value.len().min(20)),
-            Style::default().fg(Color::White),
-        ),
-        FieldKind::Bool => {
-            if field.value == "true" {
-                ("[x] on".into(), Style::default().fg(Color::Green))
-            } else {
-                ("[ ] off".into(), Style::default().fg(Color::DarkGray))
-            }
-        }
-        FieldKind::LogLevel => {
-            let color = match field.value.as_str() {
-                "trace" => Color::Magenta,
-                "debug" => Color::Blue,
-                "info" => Color::Green,
-                "warn" => Color::Yellow,
-                "error" => Color::Red,
-                _ => Color::White,
-            };
-            (field.value.clone(), Style::default().fg(color))
-        }
-        _ => (field.value.clone(), Style::default().fg(Color::White)),
-    }
-}
-
-fn render_footer(f: &mut Frame, app: &App, area: Rect) {
-    let help = app.fields[app.selected].help;
-
-    let keybindings = if app.mode == Mode::Editing {
-        "Enter confirm  Esc cancel"
-    } else {
-        "Up/Down select  Enter edit  ^S save  q quit"
-    };
-
-    let mut status_spans: Vec<Span> = vec![Span::styled(
-        keybindings,
-        Style::default().fg(Color::DarkGray),
-    )];
-
-    if let Some((msg, _, is_err)) = &app.message {
-        let color = if *is_err { Color::Red } else { Color::Green };
-        status_spans.push(Span::raw("    "));
-        status_spans.push(Span::styled(msg.clone(), Style::default().fg(color)));
-    }
-
-    let footer_text = vec![
-        Line::raw(""),
-        Line::from(Span::styled(
-            format!(" {}", help),
-            Style::default().fg(Color::DarkGray),
-        )),
-        Line::from(
-            status_spans
-                .into_iter()
-                .map(|mut s| {
-                    // add left padding to first span
-                    if s.content.as_ref() == keybindings {
-                        s.content = format!(" {}", s.content).into();
-                    }
-                    s
-                })
-                .collect::<Vec<_>>(),
-        ),
-    ];
-
-    let footer = Paragraph::new(footer_text).block(
-        Block::default()
-            .borders(Borders::TOP)
-            .border_style(Style::default().fg(Color::DarkGray)),
-    );
-
-    f.render_widget(footer, area);
-}
-
-// ── Entry point ──────────────────────────────────────────────────────────────
-
-pub fn run(config_path: PathBuf) -> anyhow::Result<SetupOutcome> {
-    // Setup terminal
-    terminal::enable_raw_mode()?;
-    let mut stdout = io::stdout();
-    execute!(stdout, EnterAlternateScreen)?;
-    let backend = CrosstermBackend::new(stdout);
-    let mut terminal = Terminal::new(backend)?;
-
-    let mut app = App::new(config_path.clone());
-    app.load_from_file();
-
-    let result = event_loop(&mut terminal, &mut app);
-
-    // Restore terminal
-    terminal::disable_raw_mode()?;
-    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
-    terminal.show_cursor()?;
-
-    result?;
-
-    // ── Post-TUI: decide outcome ─────────────────────────────────────
-
-    if !app.saved_once {
-        return Ok(SetupOutcome::Cancelled);
-    }
-
-    eprintln!();
-    eprintln!("  Config saved to {}", config_path.display());
-    eprintln!();
-
-    let wants_service = app
-        .fields
-        .iter()
-        .find(|f| f.key == "install_service")
-        .map(|f| f.value == "true")
-        .unwrap_or(false);
-
-    if wants_service {
-        match super::service::install_service(&config_path) {
-            Ok(()) => return Ok(SetupOutcome::ServiceInstalled),
-            Err(e) => {
-                eprintln!("  Service install failed: {}", e);
-                eprintln!("  Starting proxy directly instead.\n");
-            }
-        }
-    } else {
-        // Uninstall service if it was previously installed but toggled off
-        if super::service::is_installed() {
-            if let Err(e) = super::service::uninstall_service() {
-                eprintln!("  Service uninstall failed: {}", e);
-                eprintln!();
-            }
-        }
-    }
-
-    Ok(SetupOutcome::ReadyToRun(config_path))
-}
-
-fn event_loop(
-    terminal: &mut Terminal<CrosstermBackend<io::Stdout>>,
-    app: &mut App,
-) -> anyhow::Result<()> {
-    loop {
-        terminal.draw(|f| ui(f, app))?;
-
-        if event::poll(Duration::from_millis(200))? {
-            if let Event::Key(key) = event::read()? {
-                // Only handle Press events (ignore Release on Windows)
-                if key.kind == KeyEventKind::Press && app.handle_key(key) {
-                    break;
-                }
-            }
-        }
-    }
-    Ok(())
-}

aether-proxy/src/setup/upgrade.rs

@@ -1,366 +0,0 @@
-//! Self-upgrade for aether-proxy.
-//!
-//! Downloads a release from GitHub, verifies SHA256 checksum, and atomically
-//! replaces the running binary.  Restarts the systemd service if active.
-
-use std::path::{Path, PathBuf};
-
-use sha2::{Digest, Sha256};
-
-const GITHUB_API_BASE: &str = "https://api.github.com";
-const GITHUB_REPO: &str = "fawney19/Aether";
-const CURRENT_VERSION: &str = env!("CARGO_PKG_VERSION");
-
-// ── GitHub API types ─────────────────────────────────────────────────────────
-
-#[derive(serde::Deserialize)]
-struct GithubRelease {
-    tag_name: String,
-    name: String,
-}
-
-// ── Platform detection ───────────────────────────────────────────────────────
-
-fn detect_platform() -> &'static str {
-    if cfg!(target_os = "linux") && cfg!(target_arch = "x86_64") {
-        "linux-amd64"
-    } else if cfg!(target_os = "linux") && cfg!(target_arch = "aarch64") {
-        "linux-arm64"
-    } else if cfg!(target_os = "macos") && cfg!(target_arch = "x86_64") {
-        "macos-amd64"
-    } else if cfg!(target_os = "macos") && cfg!(target_arch = "aarch64") {
-        "macos-arm64"
-    } else if cfg!(target_os = "windows") && cfg!(target_arch = "x86_64") {
-        "windows-amd64"
-    } else {
-        // All supported targets are covered above; this is unreachable for
-        // any platform we actually build for.
-        panic!("unsupported platform: compile-time target not in the supported matrix")
-    }
-}
-
-// ── GitHub HTTP client ───────────────────────────────────────────────────────
-
-fn build_github_client() -> anyhow::Result<reqwest::Client> {
-    let mut headers = reqwest::header::HeaderMap::new();
-
-    if let Ok(token) = std::env::var("GITHUB_TOKEN") {
-        headers.insert(
-            reqwest::header::AUTHORIZATION,
-            reqwest::header::HeaderValue::from_str(&format!("Bearer {}", token))?,
-        );
-    }
-
-    headers.insert(
-        reqwest::header::ACCEPT,
-        reqwest::header::HeaderValue::from_static("application/vnd.github+json"),
-    );
-
-    Ok(reqwest::Client::builder()
-        .timeout(std::time::Duration::from_secs(300))
-        .user_agent(format!("aether-proxy/{}", CURRENT_VERSION))
-        .default_headers(headers)
-        .build()?)
-}
-
-// ── Release fetching ─────────────────────────────────────────────────────────
-
-async fn fetch_release(
-    client: &reqwest::Client,
-    version: Option<&str>,
-) -> anyhow::Result<GithubRelease> {
-    match version {
-        Some(ver) => {
-            // Accept both "proxy-v0.2.0" and bare "0.2.0"
-            let tag = if ver.starts_with("proxy-v") {
-                ver.to_string()
-            } else {
-                format!("proxy-v{}", ver)
-            };
-            let url = format!(
-                "{}/repos/{}/releases/tags/{}",
-                GITHUB_API_BASE, GITHUB_REPO, tag
-            );
-            let resp = client.get(&url).send().await?;
-            if !resp.status().is_success() {
-                let status = resp.status();
-                let body = resp.text().await.unwrap_or_default();
-                anyhow::bail!("release '{}' not found (HTTP {}): {}", tag, status, body);
-            }
-            Ok(resp.json().await?)
-        }
-        None => {
-            // List releases and find the latest proxy-v* tag
-            let url = format!(
-                "{}/repos/{}/releases?per_page=20",
-                GITHUB_API_BASE, GITHUB_REPO
-            );
-            let resp = client.get(&url).send().await?;
-            if !resp.status().is_success() {
-                let status = resp.status();
-                let body = resp.text().await.unwrap_or_default();
-                anyhow::bail!("failed to list releases (HTTP {}): {}", status, body);
-            }
-            let releases: Vec<GithubRelease> = resp.json().await?;
-            releases
-                .into_iter()
-                .find(|r| r.tag_name.starts_with("proxy-v"))
-                .ok_or_else(|| anyhow::anyhow!("no proxy-v* release found"))
-        }
-    }
-}
-
-// ── Download via GitHub release direct links ─────────────────────────────────
-
-/// Download a release asset via the public direct download URL:
-/// `https://github.com/{repo}/releases/download/{tag}/{filename}`
-async fn download_release_file(
-    client: &reqwest::Client,
-    tag: &str,
-    filename: &str,
-) -> anyhow::Result<Vec<u8>> {
-    let url = format!(
-        "https://github.com/{}/releases/download/{}/{}",
-        GITHUB_REPO, tag, filename
-    );
-    let resp = client
-        .get(&url)
-        .header(reqwest::header::ACCEPT, "application/octet-stream")
-        .send()
-        .await?;
-    if !resp.status().is_success() {
-        anyhow::bail!(
-            "download failed for '{}' (HTTP {})",
-            filename,
-            resp.status(),
-        );
-    }
-    Ok(resp.bytes().await?.to_vec())
-}
-
-fn parse_checksum(sums_text: &str, filename: &str) -> anyhow::Result<String> {
-    for line in sums_text.lines() {
-        // Format: "<hash>  <filename>" (GNU coreutils convention)
-        let mut parts = line.split_ascii_whitespace();
-        let (Some(hash), Some(name)) = (parts.next(), parts.next()) else {
-            continue;
-        };
-        if name == filename || name.ends_with(filename) {
-            return Ok(hash.to_lowercase());
-        }
-    }
-    anyhow::bail!("checksum for '{}' not found in SHA256SUMS.txt", filename);
-}
-
-async fn download_and_verify(
-    client: &reqwest::Client,
-    tag: &str,
-    platform: &str,
-    dest: &Path,
-) -> anyhow::Result<()> {
-    let archive_name = format!("aether-proxy-{}.tar.gz", platform);
-
-    eprintln!("  Downloading {}...", archive_name);
-    let (archive_bytes, checksum_bytes) = tokio::try_join!(
-        download_release_file(client, tag, &archive_name),
-        download_release_file(client, tag, "SHA256SUMS.txt"),
-    )?;
-    let checksum_text = String::from_utf8(checksum_bytes)?;
-
-    eprintln!(
-        "  Downloaded {} ({} bytes)",
-        archive_name,
-        archive_bytes.len()
-    );
-
-    // Verify SHA256
-    let expected_hash = parse_checksum(&checksum_text, &archive_name)?;
-    let mut hasher = Sha256::new();
-    hasher.update(&archive_bytes);
-    let actual_hash = hex::encode(hasher.finalize());
-
-    if actual_hash != expected_hash {
-        anyhow::bail!(
-            "SHA256 mismatch for {}:\n  expected: {}\n  actual:   {}",
-            archive_name,
-            expected_hash,
-            actual_hash
-        );
-    }
-    eprintln!("  SHA256 verified: {}", &actual_hash[..16]);
-
-    extract_binary(&archive_bytes, dest)?;
-
-    Ok(())
-}
-
-// ── Archive extraction ───────────────────────────────────────────────────────
-
-fn extract_binary(archive_bytes: &[u8], dest: &Path) -> anyhow::Result<()> {
-    use flate2::read::GzDecoder;
-    use tar::Archive;
-
-    // Guard against decompression bombs
-    const MAX_BINARY_SIZE: u64 = 100 * 1024 * 1024; // 100 MB
-
-    let decoder = GzDecoder::new(archive_bytes);
-    let mut archive = Archive::new(decoder);
-
-    let binary_name = if cfg!(target_os = "windows") {
-        "aether-proxy.exe"
-    } else {
-        "aether-proxy"
-    };
-
-    for entry in archive.entries()? {
-        let mut entry = entry?;
-        // Only accept regular files -- reject symlinks to prevent write-through attacks
-        if entry.header().entry_type() != tar::EntryType::Regular {
-            continue;
-        }
-        let path = entry.path()?;
-        if path.file_name().and_then(|n| n.to_str()) == Some(binary_name) {
-            let size = entry.header().size()?;
-            if size > MAX_BINARY_SIZE {
-                anyhow::bail!(
-                    "binary too large ({} bytes, max {} bytes)",
-                    size,
-                    MAX_BINARY_SIZE
-                );
-            }
-            let mut file = std::fs::File::create(dest)?;
-            std::io::copy(&mut entry, &mut file)?;
-
-            #[cfg(unix)]
-            {
-                use std::os::unix::fs::PermissionsExt;
-                std::fs::set_permissions(dest, std::fs::Permissions::from_mode(0o755))?;
-            }
-
-            return Ok(());
-        }
-    }
-
-    anyhow::bail!("'{}' not found in archive", binary_name);
-}
-
-// ── Atomic binary replacement ────────────────────────────────────────────────
-
-fn atomic_replace(new_binary: &Path) -> anyhow::Result<PathBuf> {
-    let current_exe = std::env::current_exe()?.canonicalize()?;
-    let backup_path = current_exe.with_extension("bak");
-
-    // Remove stale backup
-    let _ = std::fs::remove_file(&backup_path);
-
-    // current -> .bak
-    std::fs::rename(&current_exe, &backup_path).map_err(|e| {
-        anyhow::anyhow!(
-            "failed to backup current binary '{}' -> '{}': {}",
-            current_exe.display(),
-            backup_path.display(),
-            e
-        )
-    })?;
-
-    // new -> current
-    if let Err(e) = std::fs::rename(new_binary, &current_exe) {
-        eprintln!("  ERROR: failed to place new binary, rolling back...");
-        let _ = std::fs::rename(&backup_path, &current_exe);
-        anyhow::bail!(
-            "failed to install new binary '{}' -> '{}': {}",
-            new_binary.display(),
-            current_exe.display(),
-            e
-        );
-    }
-
-    eprintln!("  Binary replaced: {}", current_exe.display());
-    Ok(backup_path)
-}
-
-// ── Public entry point ───────────────────────────────────────────────────────
-
-/// `aether-proxy upgrade [version]` -- self-upgrade from GitHub releases.
-pub async fn cmd_upgrade(version: Option<String>) -> anyhow::Result<()> {
-    // Resolve exe path once; reuse throughout the function
-    let current_exe = std::env::current_exe()?.canonicalize()?;
-    let exe_dir = current_exe
-        .parent()
-        .ok_or_else(|| anyhow::anyhow!("cannot determine binary directory"))?;
-    let temp_path = exe_dir.join(".aether-proxy.upgrade.tmp");
-
-    // Check write permission to binary directory
-    if !super::service::is_root() {
-        let test_path = exe_dir.join(".aether-proxy.write-test");
-        match std::fs::File::create(&test_path) {
-            Ok(_) => {
-                let _ = std::fs::remove_file(&test_path);
-            }
-            Err(_) => {
-                anyhow::bail!(
-                    "no write access to {}. Use: sudo aether-proxy upgrade",
-                    exe_dir.display()
-                );
-            }
-        }
-    }
-
-    let platform = detect_platform();
-    eprintln!("  Platform: {}", platform);
-    eprintln!("  Current version: {}", CURRENT_VERSION);
-
-    let client = build_github_client()?;
-    let release = fetch_release(&client, version.as_deref()).await?;
-    let target_tag = &release.tag_name;
-    let target_semver = target_tag.strip_prefix("proxy-v").unwrap_or(target_tag);
-
-    eprintln!("  Target version: {} ({})", target_tag, release.name);
-
-    if target_semver == CURRENT_VERSION {
-        eprintln!(
-            "  Already running version {}, nothing to do.",
-            CURRENT_VERSION
-        );
-        return Ok(());
-    }
-
-    eprintln!();
-    eprintln!("  Upgrading: {} -> {}", CURRENT_VERSION, target_semver);
-    eprintln!();
-
-    if let Err(e) = download_and_verify(&client, target_tag, platform, &temp_path).await {
-        let _ = std::fs::remove_file(&temp_path);
-        return Err(e);
-    }
-    let backup_path = match atomic_replace(&temp_path) {
-        Ok(backup) => backup,
-        Err(e) => {
-            let _ = std::fs::remove_file(&temp_path);
-            return Err(e);
-        }
-    };
-
-    // Restart systemd service if running
-    if super::service::is_service_active() {
-        if super::service::is_root() {
-            eprintln!("  Restarting systemd service...");
-            super::service::run_cmd("systemctl", &["restart", "aether-proxy"])?;
-            eprintln!("  Service restarted.");
-        } else {
-            eprintln!("  Systemd service is active, but restart requires root.");
-            eprintln!("  Run: sudo aether-proxy restart");
-            eprintln!("  Skipping restart.");
-        }
-    } else {
-        eprintln!("  No active systemd service detected, skipping restart.");
-    }
-
-    eprintln!();
-    eprintln!("  Upgrade complete!");
-    eprintln!(
-        "  Backup kept at: {} (will be cleaned up on next upgrade)",
-        backup_path.display()
-    );
-    Ok(())
-}

aether-proxy/src/state.rs

@@ -1,61 +0,0 @@
-//! Shared application state passed to all subsystems.
-//!
-//! Consolidates the multiple `Arc<...>` parameters that were previously
-//! threaded individually through proxy server, heartbeat, and handlers.
-
-use std::sync::atomic::{AtomicU64, Ordering};
-use std::sync::{Arc, RwLock};
-use std::time::Duration;
-
-use tokio::sync::Semaphore;
-use tokio_rustls::TlsAcceptor;
-
-use crate::config::Config;
-use crate::hardware::HardwareInfo;
-use crate::proxy::delegate_client::DelegateClient;
-use crate::proxy::target_filter::DnsCache;
-use crate::registration::client::AetherClient;
-use crate::runtime::SharedDynamicConfig;
-
-/// Central application state shared across all tasks.
-pub struct AppState {
-    pub config: Arc<Config>,
-    pub node_id: Arc<RwLock<String>>,
-    pub dynamic: SharedDynamicConfig,
-    pub aether_client: Arc<AetherClient>,
-    pub hardware_info: Arc<HardwareInfo>,
-    pub public_ip: String,
-    pub tls_fingerprint: Option<String>,
-    pub tls_acceptor: Option<TlsAcceptor>,
-    /// Shared delegate client for proxy-initiated upstream requests.
-    pub delegate_client: DelegateClient,
-    /// Active connection count for metrics reporting.
-    pub active_connections: Arc<AtomicU64>,
-    /// Connection concurrency limiter.
-    pub connection_semaphore: Arc<Semaphore>,
-    /// DNS cache for upstream target resolution.
-    pub dns_cache: Arc<DnsCache>,
-    /// Request/latency metrics for heartbeat.
-    pub metrics: Arc<ProxyMetrics>,
-}
-
-/// Aggregate metrics for reporting to Aether.
-pub struct ProxyMetrics {
-    pub total_requests: AtomicU64,
-    pub total_latency_ns: AtomicU64,
-}
-
-impl ProxyMetrics {
-    pub fn new() -> Self {
-        Self {
-            total_requests: AtomicU64::new(0),
-            total_latency_ns: AtomicU64::new(0),
-        }
-    }
-
-    pub fn record_request(&self, elapsed: Duration) {
-        let nanos = u64::try_from(elapsed.as_nanos()).unwrap_or(u64::MAX);
-        self.total_requests.fetch_add(1, Ordering::Relaxed);
-        self.total_latency_ns.fetch_add(nanos, Ordering::Relaxed);
-    }
-}

aether-vscodex/.dockerignore

@@ -0,0 +1,10 @@
+.git
+.github
+node_modules
+test
+fixtures
+vscode-extension
+*.vsix
+coverage
+data
+.DS_Store

aether-vscodex/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+vscode-extension/node_modules/
+vscode-extension/dist/
+data/
+coverage/
+*.vsix
+.DS_Store
+*.log

aether-vscodex/Dockerfile

@@ -0,0 +1,26 @@
+FROM node:22-alpine
+
+ENV NODE_ENV=production \
+    HOST=0.0.0.0 \
+    PORT=8788 \
+    AETHER_VSCODEX_DATA_DIR=/var/lib/aether-vscodex
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev && npm cache clean --force
+
+COPY cloud ./cloud
+COPY relay ./relay
+COPY public ./public
+
+RUN mkdir -p /var/lib/aether-vscodex && chown -R node:node /var/lib/aether-vscodex /app
+
+USER node
+
+EXPOSE 8788
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
+  CMD node -e "fetch('http://127.0.0.1:8788/healthz').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))"
+
+CMD ["node", "cloud/server.js"]

aether-vscodex/README.md

@@ -0,0 +1,283 @@
+# aether-vscodex
+
+这个项目让浏览器从本机 URL 或 Aether 云端查看、输入并处理 Codex 会话，提供两种
+可随时切换的控制模式。默认的**同步模式**通过官方扩展使用的本机 IPC socket，严格
+跟随 VS Code Codex 面板当前会话，不启动另一个 `codex` 进程；**异步模式**由伴随扩展
+启动独立 app-server，网页可以自行列出、恢复、新建和切换会话。
+
+同一个伴随扩展可同时连接两个互不替代的通道：本机 loopback 控制台和部署在
+Aether 中的云端控制台。本机通道默认免密码且只能从本机访问；云端通道使用
+Aether 登录鉴权、一次性浏览器票据和独立设备凭据；父页面不会通过协议把 Aether JWT
+传给 iframe 或 Node sidecar。iframe 是随 Aether 一起发布的同源受信代码，不应被视为
+隔离不受信内容的安全边界。
+
+`vscode-extension/codex-remote-collab-0.4.0.vsix` 安装到 VS Code 后，会作为官方
+`openai.chatgpt` Codex 扩展的伴随扩展，并自动托管只监听本机的 relay。开发时仍可
+单独运行 `relay/server.js`。不要卸载或替换官方 Codex 扩展。
+
+## 工作方式
+
+```text
+官方 VS Code Codex 会话
+        │  本机私有 IPC（只在 VS Code 所在机器上）
+        ▼
+                                ┌── 本机 relay ── http://127.0.0.1:8787
+VS Code aether-vscodex 扩展 ────┤
+                                └── Aether gateway ── 用户/设备隔离的云端 relay
+```
+
+控制模式与传输通道是两个独立维度：切换同步/异步不会重连本地或云端 relay。本机和
+Aether 控制页连接到同一台 VS Code 主机时，会看到同一个当前模式。
+
+| 控制模式 | 会话所有者 | 网页会话导航 |
+| --- | --- | --- |
+| 同步 | 官方 VS Code Codex 面板 | 禁止网页自行切换；自动跟随 VS Code |
+| 异步 | 扩展启动的独立 app-server | 可列出、恢复、新建和切换会话 |
+
+浏览器的 `operator` 可以发送任务、继续/中断当前 turn，并处理 Codex 的审批、
+用户输入和 MCP elicitation；`viewer` 只能查看事件和输出。远程浏览器不接触
+VS Code 的 SecretStorage，也不直接连接 IPC socket。
+
+## 前端结构
+
+Aether 页面使用仓库既有的 Vue 3、TypeScript、Vite 和 i18n。独立控制台也提供
+Vue/Vite 源码入口，但当前高保真的会话渲染与协议状态机作为兼容运行时保留，构建到
+`public/` 后同时供本机 URL 和 Aether 同源 iframe 使用。这样不需要一次性重写并丢失
+命令展开、滚动锚点、思考状态、Markdown、子代理、模型和权限菜单等已有行为。
+
+界面支持 `zh-CN` 与 `en-US`。Aether 的语言和深浅色主题会通过经过来源校验的
+`postMessage` 同步给 iframe；VS Code 命令与设置说明使用 `package.nls` 本地化。
+
+## Aether 云端部署
+
+云端模式由 Aether gateway 和独立 Node sidecar 组成。sidecar 只在 Compose 内网暴露
+8788，公网的 HTTP、配对交换和 WebSocket 都经 Aether gateway：
+
+```text
+GET    /api/users/me/vscodex/devices
+POST   /api/users/me/vscodex/pairings
+DELETE /api/users/me/vscodex/devices/:device_id
+POST   /api/users/me/vscodex/ws-tickets
+POST   /api/vscodex/pair
+WS     /api/vscodex/ws
+```
+
+生成至少 32 字节的内部令牌，并按 Aether 的公开 HTTPS 地址设置变量：
+
+```sh
+export AETHER_VSCODEX_INTERNAL_TOKEN="$(openssl rand -base64 32)"
+export AETHER_VSCODEX_PUBLIC_WS_URL="wss://aether.example.com/api/vscodex/ws"
+export AETHER_VSCODEX_ALLOWED_ORIGINS="https://aether.example.com"
+
+docker compose \
+  -f docker-compose.yml \
+  -f docker-compose.local.yml \
+  -f aether-vscodex/docker-compose.aether.yml \
+  up -d --build
+```
+
+源码部署必须包含 `docker-compose.local.yml`，以保证 gateway、前端和 sidecar 来自同一份
+checkout。使用发布镜像时可以去掉该文件，但 `APP_IMAGE` 必须固定为包含相同
+`aether-vscodex` 协议版本的 Aether 镜像，不能把当前 sidecar 与旧的 `latest` gateway 混用。
+
+首次使用源码 Compose 前先构建控制台；正式 Aether 发布流程与 Dockerfile 已自动执行
+同一步骤：
+
+```sh
+npm --prefix aether-vscodex/web ci
+npm --prefix aether-vscodex/web run build
+```
+
+第一阶段 sidecar 是有状态单副本：设备凭据的 scrypt 哈希保存在
+`vscodex_data`，短期配对码、60 秒一次性浏览器票据和在线房间保存在内存。不要在未引入
+共享连接目录前横向扩容 sidecar。
+
+登录 Aether 后打开“远程控制”，生成一次性配对码。然后在 VS Code 命令面板执行
+**Codex Remote: Pair with Aether**，填写 Aether 地址和配对码。插件会把设备凭据写入
+VS Code SecretStorage，并同时保持本机控制台连接。
+
+## 快速开始
+
+前提：Node.js 20+；官方 `openai.chatgpt` VS Code 扩展已安装并登录；目标会话
+已经在 VS Code 的 Codex 面板中打开。VS Code 和 relay 必须以同一个操作系统用户
+运行，因为 IPC socket 是本机文件。
+
+1. 安装依赖并构建伴随扩展：
+
+   ```sh
+   npm --prefix vscode-extension install
+   npm --prefix vscode-extension run build
+   ```
+
+   本机 `ws://` 地址会由扩展自动启动 relay；loopback 模式默认不需要 token，且
+   `host` 模式不会启动 `codex app-server`。
+
+2. 安装 `vscode-extension/codex-remote-collab-0.4.0.vsix`（或在扩展目录先
+   `npm run build` 再用 `npx --yes @vscode/vsce package` 打包），然后在 VS Code
+   执行 **Developer: Reload Window**。
+
+3. 在 VS Code 设置中填写：
+
+   ```json
+   {
+     "codexRemoteCollab.localRelayUrl": "ws://127.0.0.1:8787/v1/connect",
+     "codexRemoteCollab.controlMode": "sync",
+     "codexRemoteCollab.autoDiscoverThread": true,
+     "codexRemoteCollab.autoStart": true
+   }
+   ```
+
+4. 执行一次 **Developer: Reload Window** 后，扩展会自动找到最近的、仍由官方
+   VS Code Codex owner 持有的会话，并把已有输出同步到 relay；如果没有自动启动，
+   无需手动启动或断开。右下角状态项只用于显示状态并打开 Web。需要精确指定会话时，执行
+   **Codex Remote: Set Existing Thread ID**；留空则恢复自动发现。
+   官方 Codex 面板切换会话时，Web 默认会在新会话快照就绪后自动跟随；正在执行或等待
+   授权的旧会话会先保持附着，结束后再安全切换。
+
+5. 浏览器打开 `http://127.0.0.1:8787`，页面会自动以本机 operator 身份连接，
+   不需要输入密码。
+
+如果页面显示“等待 VS Code 主机连接”，先确认 relay 地址与扩展设置的端口完全一致，
+然后在 VS Code 执行一次 **Developer: Reload Window**。同步模式必须在官方 Codex
+面板已经打开至少一个会话后才能发现 owner；通常不需要手工填写
+`codexRemoteCollab.threadId`，留空会自动选择最近的可用会话。若之前填写过已经关闭的
+thread ID，清空该设置后再重载窗口。
+
+### 发布与下载插件
+
+正式发布时不需要用户在本地编译。仓库的 `.github/workflows/release.yml` 在推送
+`vX.Y.Z`、`vX.Y.Z-beta.N` 或 `vX.Y.Z-rc.N` 标签时，会在 GitHub Actions 中完成 Web
+前端构建、扩展编译和 VSIX 打包，并把
+`aether-vscodex-<extension-version>.vsix` 附加到对应的 GitHub Release。用户从 Release
+页面下载该 VSIX，在 VS Code 的扩展视图中选择“从 VSIX 安装...”即可；安装后执行一次
+**Developer: Reload Window**。
+
+手动运行该 workflow 时，VSIX 会作为 `aether-vscodex-vsix` Actions artifact 提供下载，
+但不会创建 GitHub Release。源码目录中的 VSIX 只用于本地开发验证，不是用户发布渠道。
+
+如果命令面板提示 `command 'codexRemoteCollab.start' not found`，通常是旧版
+VSIX 激活失败（旧包可能没有包含 `ws` 运行依赖）。请安装当前的
+`codex-remote-collab-0.4.0.vsix` 并使用 `--force` 覆盖旧版本，然后执行一次
+**Developer: Reload Window**：
+
+```sh
+code --install-extension vscode-extension/codex-remote-collab-0.4.0.vsix --force
+```
+
+也可以在 **Output → Codex Remote Collaboration** 中确认没有
+`Cannot find module 'ws'`；出现该错误时，说明扩展尚未成功激活。
+
+网页现在按官方 Codex Webview 的会话模型展示：历史和实时输出在中间消息流，用户、
+助手、reasoning、命令输出分别投影为对应的消息项；助手内容支持安全的 Markdown、
+代码块和复制操作，reasoning/命令活动可折叠。底部 composer 使用可编辑富文本区域，
+回车发送、Shift+Enter 换行；审批和用户输入会以内嵌 card 出现在会话流中，支持风险
+标记、输入控件、授权范围和明确的允许/拒绝动作。附着适配器会额外发送可选的
+`messages` 角色投影，旧版 host 没有该字段时网页仍回退到纯文本快照。
+
+页面打开后自动连接并在断线后重连，不再需要手动点击“连接”或“断开”。同步模式下
+会话列表、返回历史和新建入口会被禁用，所有输入都发送到 VS Code 当前会话。这里复刻的是从本机已安装
+官方 bundle 审计出的布局、状态和交互；官方 bundle 依赖 VS Code 私有 Webview API，
+不能安全地直接作为 iframe 嵌入浏览器。
+
+底部的“同步 / 异步”分段控件发送 `control/mode/set`。当前 turn 正在执行或存在待处理
+授权、用户输入时，主机拒绝切换；候选适配器启动失败时保留原模式和原会话。切入异步
+模式后，页面顶部会恢复会话历史、新建和选择入口；`session/list` 映射到
+`thread/list`，选择会话使用 `thread/resume` 并水合完整历史，新建会话使用
+`thread/start`。切回同步模式会关闭独立 app-server，并重新以 VS Code 面板为唯一
+会话导航来源。
+
+### 认证（可选）
+
+如果以后需要保护 relay，可显式开启认证；本机流程默认不需要这些变量：
+
+```sh
+CODEX_REMOTE_AUTH=required \
+CODEX_REMOTE_HOST_TOKEN='host-only-secret' \
+CODEX_REMOTE_TOKEN='browser-operator-secret' \
+CODEX_REMOTE_VIEW_TOKEN='browser-viewer-secret' \
+CODEX_REMOTE_MODE=host npm start
+```
+
+认证开启后，Host token 填在 VS Code 扩展中，Operator/Viewer token 填在浏览器中。
+
+## `spawn codex ENOENT` 是什么
+
+这个错误只表示某处正在尝试启动**独立**的 `codex app-server`，但 VS Code 图形
+进程的 `PATH` 找不到可执行文件。对于本项目默认的同步模式，不会调用
+`spawn codex`，因此不需要通过设置 `codexCommand` 来修复它。
+
+只有切换到异步模式（或仍使用旧版兼容设置）才需要独立可执行文件：
+
+```json
+"codexRemoteCollab.controlMode": "async"
+```
+
+扩展会优先解析 `codexRemoteCollab.codexCommand`，并可回退到官方 Codex 扩展内置的
+可执行文件；`codexRemoteCollab.codexArgs` 默认是 `["app-server", "--stdio"]`。
+旧 `mode=attach/spawn` 会分别迁移为 `sync/async`。
+
+## Relay 模式
+
+### `host`（推荐）
+
+relay 只负责认证、事件缓存和转发；VS Code 扩展通过私有 IPC 附着官方 Codex
+会话。必须先打开目标会话；本机 loopback 默认不需要 host token，只有显式开启认证时
+才把 host token 提供给扩展。
+
+### `embedded`（旧的独立进程模式）
+
+只有显式设置 `CODEX_REMOTE_MODE=embedded` 时，relay 才会启动自己的
+`codex app-server --stdio`，适合测试页面和公开 app-server 协议；它与 VS Code
+当前会话无关：
+
+```sh
+CODEX_REMOTE_MODE=embedded CODEX_CWD="$PWD" npm start
+```
+
+`CODEX_BIN` 可指定独立进程的可执行文件；`CODEX_ARGS_JSON` 可覆盖其参数。不要
+把这些设置误认为 attach 模式的必要配置。
+
+## HTTP API
+
+认证开启时，除 `/api/health` 外的 `/api/*` 都需要
+`Authorization: Bearer <operator-or-viewer-token>` 或 `X-Codex-Token`；本机免认证
+模式下 loopback 请求直接作为 operator 处理。
+
+```text
+GET  /api/health
+GET  /api/state
+GET  /api/events?fromSeq=0
+POST /api/command   {"commandId":"...","method":"turn/start","params":{...}}
+POST /api/respond   {"requestId":"...","result":{...}}
+```
+
+host 模式下，同步控制会拒绝 `thread/start` 和网页会话导航；异步控制会把它们转给
+独立 app-server。浏览器使用 `threadId` 发送 `turn/start`、`turn/steer` 或
+`turn/interrupt`。认证开启时写操作和
+响应请求必须使用 operator token；本机免认证模式下 loopback operator 可直接操作。
+
+## 私有协议和限制
+
+- IPC follower 协议是官方 VS Code 扩展的私有、带版本号实现，不是公开 API；官方
+  扩展升级后可能需要同步适配。启用 `codexRemoteCollab.ipcStrictVersions`
+  时，未知 stream 版本会让连接报错而不是猜测执行。
+- 自动发现只把本地 rollout 元数据当作候选，最终仍通过 IPC owner discovery
+  验证；生产或多会话场景建议设置明确的 `threadId`。
+- relay 默认只监听 loopback，且 loopback 默认免认证；这意味着同一台机器上能访问
+  loopback 的本地进程都可能控制会话，不要把它反向代理或暴露到外部。如果开启 token
+  认证，token 是 bearer secret。高风险授权默认被 host policy 拒绝，只有显式设置
+  `codexRemoteCollab.allowHighRiskApprovals=true` 才允许。
+- 输出会做常见 token/密码脱敏，但不能识别所有秘密；不要把凭据发送给 Codex。
+- 当前 UI 控制一个 host 会话，不提供多人同时编辑或文件同步。
+
+## 测试
+
+根目录测试使用假的 stdio app-server，不会向真实 Codex 发送任务：
+
+```sh
+npm test
+cd vscode-extension && npm run check && npm run build
+```
+
+要验证真实附着，只读地打开官方 VS Code 会话后启动 bridge；不要在验证脚本中
+调用 `turn/start`，除非你确实要向该会话发送任务。

aether-vscodex/cloud/server.js

@@ -0,0 +1,727 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const http = require("node:http");
+const net = require("node:net");
+const path = require("node:path");
+const { URL } = require("node:url");
+const { WebSocket, WebSocketServer } = require("ws");
+
+const { CodexRelay } = require("../relay/server.js");
+
+const MAX_JSON_BYTES = 64 * 1024;
+const MAX_WS_BYTES = 16 * 1024 * 1024;
+const DEFAULT_PAIRING_TTL_MS = 10 * 60 * 1000;
+const DEFAULT_TICKET_TTL_MS = 60 * 1000;
+const DEFAULT_ROOM_IDLE_MS = 30 * 60 * 1000;
+
+class DeviceStore {
+  constructor(filePath) {
+    this.filePath = filePath;
+    this.data = { version: 1, devices: [] };
+    this.load();
+  }
+
+  load() {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(this.filePath, "utf8"));
+      if (parsed?.version !== 1 || !Array.isArray(parsed.devices)) throw new Error("unsupported device store format");
+      this.data = parsed;
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      fs.mkdirSync(path.dirname(this.filePath), { recursive: true, mode: 0o700 });
+      this.persist();
+    }
+  }
+
+  list(userId, connectedDeviceIds = new Set()) {
+    return this.data.devices
+      .filter((device) => device.user_id === userId && !device.revoked_at)
+      .map((device) => publicDevice(device, connectedDeviceIds.has(device.id)));
+  }
+
+  create(userId, name) {
+    const id = crypto.randomUUID();
+    const secret = crypto.randomBytes(32).toString("base64url");
+    const salt = crypto.randomBytes(16).toString("base64url");
+    const now = new Date().toISOString();
+    const device = {
+      id,
+      user_id: userId,
+      name: normalizeName(name),
+      secret_salt: salt,
+      secret_hash: deriveSecret(secret, salt),
+      created_at: now,
+      last_seen_at: null,
+      revoked_at: null,
+    };
+    this.data.devices.push(device);
+    this.persist();
+    return { device: publicDevice(device, false), token: `avx1.${id}.${secret}` };
+  }
+
+  authenticate(token) {
+    const parsed = parseDeviceToken(token);
+    if (!parsed) return null;
+    const device = this.data.devices.find((candidate) => candidate.id === parsed.id && !candidate.revoked_at);
+    if (!device) return null;
+    const actual = Buffer.from(deriveSecret(parsed.secret, device.secret_salt), "base64url");
+    const expected = Buffer.from(device.secret_hash, "base64url");
+    if (actual.length !== expected.length || !crypto.timingSafeEqual(actual, expected)) return null;
+    return device;
+  }
+
+  get(userId, deviceId) {
+    return this.data.devices.find((device) => device.user_id === userId && device.id === deviceId && !device.revoked_at) || null;
+  }
+
+  touch(deviceId) {
+    const device = this.data.devices.find((candidate) => candidate.id === deviceId && !candidate.revoked_at);
+    if (!device) return;
+    device.last_seen_at = new Date().toISOString();
+    this.persist();
+  }
+
+  revoke(userId, deviceId) {
+    const device = this.get(userId, deviceId);
+    if (!device) return false;
+    device.revoked_at = new Date().toISOString();
+    this.persist();
+    return true;
+  }
+
+  persist() {
+    fs.mkdirSync(path.dirname(this.filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${this.filePath}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(this.data, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, this.filePath);
+  }
+}
+
+class EphemeralCredentials {
+  constructor(options = {}) {
+    this.pairingTtlMs = options.pairingTtlMs || DEFAULT_PAIRING_TTL_MS;
+    this.ticketTtlMs = options.ticketTtlMs || DEFAULT_TICKET_TTL_MS;
+    this.pairings = new Map();
+    this.tickets = new Map();
+  }
+
+  createPairing(userId, requestedName) {
+    const code = pairingCode();
+    const record = {
+      id: crypto.randomUUID(),
+      code,
+      user_id: userId,
+      requested_name: normalizeName(requestedName),
+      expires_at_ms: Date.now() + this.pairingTtlMs,
+    };
+    this.pairings.set(normalizePairingCode(code), record);
+    return record;
+  }
+
+  consumePairing(code) {
+    const key = normalizePairingCode(code);
+    const record = this.pairings.get(key);
+    this.pairings.delete(key);
+    if (!record || record.expires_at_ms <= Date.now()) return null;
+    return record;
+  }
+
+  createTicket(userId, deviceId) {
+    const ticket = `avt1.${crypto.randomBytes(32).toString("base64url")}`;
+    this.tickets.set(ticket, {
+      user_id: userId,
+      device_id: deviceId,
+      expires_at_ms: Date.now() + this.ticketTtlMs,
+    });
+    return ticket;
+  }
+
+  consumeTicket(ticket) {
+    const record = this.tickets.get(ticket);
+    this.tickets.delete(ticket);
+    if (!record || record.expires_at_ms <= Date.now()) return null;
+    return record;
+  }
+
+  cleanup() {
+    const now = Date.now();
+    for (const [key, record] of this.pairings) if (record.expires_at_ms <= now) this.pairings.delete(key);
+    for (const [key, record] of this.tickets) if (record.expires_at_ms <= now) this.tickets.delete(key);
+  }
+}
+
+class RoomManager {
+  constructor(options = {}) {
+    this.rooms = new Map();
+    this.pendingRooms = new Map();
+    this.revokedRoomKeys = new Set();
+    this.idleMs = options.idleMs || DEFAULT_ROOM_IDLE_MS;
+  }
+
+  key(userId, deviceId) {
+    return `${encodeURIComponent(userId)}:${deviceId}`;
+  }
+
+  async get(userId, deviceId) {
+    const key = this.key(userId, deviceId);
+    if (this.revokedRoomKeys.has(key)) throw httpError(401, "device revoked");
+    let room = this.rooms.get(key);
+    if (!room && this.pendingRooms.has(key)) room = await this.pendingRooms.get(key);
+    if (!room) {
+      const creating = this.createRoom(key, userId, deviceId);
+      this.pendingRooms.set(key, creating);
+      try {
+        room = await creating;
+      } finally {
+        this.pendingRooms.delete(key);
+      }
+    }
+    if (this.revokedRoomKeys.has(key)) throw httpError(401, "device revoked");
+    room.lastActiveMs = Date.now();
+    return room;
+  }
+
+  async createRoom(key, userId, deviceId) {
+      const hostToken = randomToken();
+      const operatorToken = randomToken();
+      const relay = new CodexRelay({
+        host: "127.0.0.1",
+        port: 0,
+        mode: "host",
+        authRequired: true,
+        hostToken,
+        operatorToken,
+        viewerToken: randomToken(),
+      });
+      await relay.start();
+      if (this.revokedRoomKeys.has(key)) {
+        await relay.stop().catch(() => undefined);
+        throw httpError(401, "device revoked");
+      }
+      const address = relay.address();
+      const room = {
+        key,
+        userId,
+        deviceId,
+        relay,
+        hostToken,
+        operatorToken,
+        baseUrl: `ws://127.0.0.1:${address.port}`,
+        connections: 0,
+        lastActiveMs: Date.now(),
+      };
+      this.rooms.set(key, room);
+    return room;
+  }
+
+  connectedDeviceIds(userId) {
+    return new Set([...this.rooms.values()]
+      .filter((room) => room.userId === userId && room.relay.state.hostConnected)
+      .map((room) => room.deviceId));
+  }
+
+  retain(room) {
+    room.connections += 1;
+    room.lastActiveMs = Date.now();
+  }
+
+  release(room) {
+    room.connections = Math.max(0, room.connections - 1);
+    room.lastActiveMs = Date.now();
+  }
+
+  async cleanup() {
+    const now = Date.now();
+    for (const [key, room] of this.rooms) {
+      if (room.connections > 0 || now - room.lastActiveMs < this.idleMs) continue;
+      this.rooms.delete(key);
+      await room.relay.stop();
+    }
+  }
+
+  async revoke(userId, deviceId) {
+    const key = this.key(userId, deviceId);
+    this.revokedRoomKeys.add(key);
+    const pending = this.pendingRooms.get(key);
+    if (pending) await pending.catch(() => undefined);
+    const room = this.rooms.get(key);
+    if (!room) return;
+    this.rooms.delete(key);
+    await room.relay.stop();
+  }
+
+  async stop() {
+    await Promise.allSettled([...this.pendingRooms.values()]);
+    this.pendingRooms.clear();
+    const rooms = [...this.rooms.values()];
+    this.rooms.clear();
+    this.revokedRoomKeys.clear();
+    await Promise.allSettled(rooms.map((room) => room.relay.stop()));
+  }
+}
+
+class AetherVscodexCloudServer {
+  constructor(options = {}) {
+    this.host = options.host || process.env.HOST || "127.0.0.1";
+    this.port = parsePort(options.port ?? process.env.PORT, 8788);
+    this.internalToken = options.internalToken || process.env.AETHER_VSCODEX_INTERNAL_TOKEN || "";
+    this.publicWsUrl = options.publicWsUrl || process.env.AETHER_VSCODEX_PUBLIC_WS_URL || "";
+    this.allowedOrigins = normalizeOrigins(options.allowedOrigins ?? process.env.AETHER_VSCODEX_ALLOWED_ORIGINS);
+    const dataDir = options.dataDir || process.env.AETHER_VSCODEX_DATA_DIR || path.join(process.cwd(), "data");
+    this.store = options.store || new DeviceStore(path.join(dataDir, "devices.json"));
+    this.credentials = options.credentials || new EphemeralCredentials(options);
+    this.rooms = options.rooms || new RoomManager(options);
+    this.exchangeAttempts = new Map();
+    this.httpServer = null;
+    this.wsServer = null;
+    this.cleanupTimer = null;
+  }
+
+  async start() {
+    if (!this.internalToken) throw new Error("AETHER_VSCODEX_INTERNAL_TOKEN is required");
+    if (Buffer.byteLength(this.internalToken, "utf8") < 24) throw new Error("AETHER_VSCODEX_INTERNAL_TOKEN must contain at least 24 bytes");
+    if (!this.publicWsUrl) throw new Error("AETHER_VSCODEX_PUBLIC_WS_URL is required");
+    validatePublicWsUrl(this.publicWsUrl);
+    if (!isLoopbackHost(this.host) && this.allowedOrigins.size === 0) {
+      throw new Error("AETHER_VSCODEX_ALLOWED_ORIGINS is required when binding outside loopback");
+    }
+    this.httpServer = http.createServer((request, response) => {
+      void this.handleHttp(request, response).catch((error) => {
+        jsonResponse(response, error.statusCode || 500, { error: error.expose ? error.message : "internal server error" });
+      });
+    });
+    this.wsServer = new WebSocketServer({ noServer: true, maxPayload: MAX_WS_BYTES });
+    this.httpServer.on("upgrade", (request, socket, head) => this.handleUpgrade(request, socket, head));
+    this.cleanupTimer = setInterval(() => {
+      this.credentials.cleanup();
+      this.cleanupExchangeAttempts();
+      void this.rooms.cleanup();
+    }, 30_000);
+    this.cleanupTimer.unref();
+    await new Promise((resolve, reject) => {
+      const onError = (error) => reject(error);
+      this.httpServer.once("error", onError);
+      this.httpServer.listen(this.port, this.host, () => {
+        this.httpServer.off("error", onError);
+        resolve();
+      });
+    });
+    return this.address();
+  }
+
+  address() {
+    const address = this.httpServer.address();
+    if (!address || typeof address === "string") return { host: this.host, port: this.port };
+    return { host: address.address, port: address.port };
+  }
+
+  async stop() {
+    if (this.cleanupTimer) clearInterval(this.cleanupTimer);
+    this.cleanupTimer = null;
+    if (this.wsServer) {
+      for (const client of this.wsServer.clients) client.close(1001, "server shutting down");
+      await new Promise((resolve) => this.wsServer.close(() => resolve()));
+    }
+    if (this.httpServer) await new Promise((resolve) => this.httpServer.close(() => resolve()));
+    this.wsServer = null;
+    this.httpServer = null;
+    await this.rooms.stop();
+  }
+
+  async handleHttp(request, response) {
+    const requestUrl = new URL(request.url || "/", "http://sidecar.local");
+    if (request.method === "GET" && requestUrl.pathname === "/healthz") {
+      jsonResponse(response, 200, { ok: true, service: "aether-vscodex", mode: "single-replica" });
+      return;
+    }
+    if (request.method === "POST" && requestUrl.pathname === "/v1/pairings/exchange") {
+      this.enforceExchangeRate(request);
+      const body = await readJson(request);
+      const pairing = this.credentials.consumePairing(body.code);
+      if (!pairing) throw httpError(400, "invalid or expired pairing code");
+      const created = this.store.create(pairing.user_id, body.name || pairing.requested_name);
+      jsonResponse(response, 201, {
+        device_id: created.device.id,
+        device_name: created.device.name,
+        device_token: created.token,
+        ws_url: this.publicWsUrl,
+      });
+      return;
+    }
+
+    const match = requestUrl.pathname.match(/^\/internal\/v1\/users\/([^/]+)\/(devices|pairings|ws-tickets)(?:\/([^/]+))?$/);
+    if (!match) {
+      jsonResponse(response, 404, { error: "not found" });
+      return;
+    }
+    this.requireInternalAuth(request);
+    const userId = decodeURIComponent(match[1]);
+    const resource = match[2];
+    const resourceId = match[3] ? decodeURIComponent(match[3]) : null;
+    if (!userId || userId.length > 256) throw httpError(400, "invalid user id");
+
+    if (request.method === "GET" && resource === "devices" && !resourceId) {
+      jsonResponse(response, 200, { devices: this.store.list(userId, this.rooms.connectedDeviceIds(userId)) });
+      return;
+    }
+    if (request.method === "POST" && resource === "pairings" && !resourceId) {
+      const body = await readJson(request);
+      const pairing = this.credentials.createPairing(userId, body.name);
+      jsonResponse(response, 201, {
+        pairing_id: pairing.id,
+        code: pairing.code,
+        expires_at: new Date(pairing.expires_at_ms).toISOString(),
+      });
+      return;
+    }
+    if (request.method === "DELETE" && resource === "devices" && resourceId) {
+      if (!this.store.revoke(userId, resourceId)) throw httpError(404, "device not found");
+      await this.rooms.revoke(userId, resourceId);
+      response.writeHead(204, { "Cache-Control": "no-store" });
+      response.end();
+      return;
+    }
+    if (request.method === "POST" && resource === "ws-tickets" && !resourceId) {
+      const body = await readJson(request);
+      const deviceId = typeof body.device_id === "string" ? body.device_id : "";
+      if (!deviceId || !this.store.get(userId, deviceId)) throw httpError(404, "device not found");
+      jsonResponse(response, 201, {
+        ticket: this.credentials.createTicket(userId, deviceId),
+        ws_url: "/api/vscodex/ws",
+        expires_in: Math.floor(this.credentials.ticketTtlMs / 1000),
+      });
+      return;
+    }
+    jsonResponse(response, 405, { error: "method not allowed" }, { Allow: allowedMethod(resource, resourceId) });
+  }
+
+  requireInternalAuth(request) {
+    if (!this.hasInternalAuth(request)) throw httpError(401, "unauthorized");
+  }
+
+  hasInternalAuth(request) {
+    const authorization = String(request.headers.authorization || "");
+    const token = authorization.startsWith("Bearer ") ? authorization.slice(7) : "";
+    return secureEqual(token, this.internalToken);
+  }
+
+  enforceExchangeRate(request) {
+    const address = this.exchangeRateAddress(request);
+    const now = Date.now();
+    const attempts = (this.exchangeAttempts.get(address) || []).filter((time) => now - time < 60_000);
+    if (attempts.length >= 10) throw httpError(429, "too many pairing attempts");
+    attempts.push(now);
+    this.exchangeAttempts.set(address, attempts);
+  }
+
+  exchangeRateAddress(request) {
+    if (this.hasInternalAuth(request)) {
+      const forwardedAddress = singleHeaderValue(request, "x-aether-client-ip")?.trim();
+      if (forwardedAddress && net.isIP(forwardedAddress)) return forwardedAddress;
+    }
+    return request.socket.remoteAddress || "unknown";
+  }
+
+  cleanupExchangeAttempts() {
+    const now = Date.now();
+    for (const [address, attempts] of this.exchangeAttempts) {
+      const active = attempts.filter((time) => now - time < 60_000);
+      if (active.length) this.exchangeAttempts.set(address, active);
+      else this.exchangeAttempts.delete(address);
+    }
+  }
+
+  handleUpgrade(request, socket, head) {
+    const requestUrl = new URL(request.url || "/", "http://sidecar.local");
+    if (requestUrl.pathname !== "/api/vscodex/ws" && requestUrl.pathname !== "/v1/connect") {
+      rejectUpgrade(socket, 404, "Not Found");
+      return;
+    }
+    const origin = request.headers.origin;
+    if (origin && this.allowedOrigins.size > 0 && !this.allowedOrigins.has(normalizeOrigin(origin))) {
+      rejectUpgrade(socket, 403, "Forbidden");
+      return;
+    }
+    this.wsServer.handleUpgrade(request, socket, head, (webSocket) => {
+      this.wsServer.emit("connection", webSocket, request);
+      this.handleWebSocket(webSocket, request);
+    });
+  }
+
+  handleWebSocket(socket, request) {
+    let hello = null;
+    let token = "";
+    let upstream = null;
+    let authenticating = false;
+    let room = null;
+    const queued = [];
+    const authTimer = setTimeout(() => socket.close(1008, "authentication required"), 10_000);
+    authTimer.unref();
+
+    const connectUpstream = async () => {
+      if (authenticating || upstream || !hello || !token) return;
+      authenticating = true;
+      let identity;
+      let upstreamToken;
+      if (hello.clientType === "host") {
+        const device = this.store.authenticate(token);
+        if (!device) throw httpError(401, "invalid device credential");
+        identity = { userId: device.user_id, deviceId: device.id };
+        room = await this.rooms.get(identity.userId, identity.deviceId);
+        upstreamToken = room.hostToken;
+        this.store.touch(device.id);
+      } else {
+        const ticket = this.credentials.consumeTicket(token);
+        if (!ticket || !this.store.get(ticket.user_id, ticket.device_id)) throw httpError(401, "invalid or expired browser ticket");
+        identity = { userId: ticket.user_id, deviceId: ticket.device_id };
+        room = await this.rooms.get(identity.userId, identity.deviceId);
+        upstreamToken = room.operatorToken;
+      }
+      this.rooms.retain(room);
+      upstream = new WebSocket(`${room.baseUrl}${hello.clientType === "host" ? "/v1/connect" : "/ws"}`, {
+        maxPayload: MAX_WS_BYTES,
+      });
+      upstream.once("open", () => {
+        if (socket.readyState !== WebSocket.OPEN) {
+          upstream.close();
+          return;
+        }
+        upstream.send(JSON.stringify(hello));
+        upstream.send(JSON.stringify(hello.clientType === "host"
+          ? { v: 1, kind: "auth", accessToken: upstreamToken }
+          : { type: "auth", token: upstreamToken }));
+        for (const frame of queued.splice(0)) upstream.send(frame);
+      });
+      upstream.on("message", (data, isBinary) => {
+        if (socket.readyState === WebSocket.OPEN) socket.send(data, { binary: isBinary });
+      });
+      upstream.on("close", (code, reason) => {
+        if (socket.readyState === WebSocket.OPEN) socket.close(validCloseCode(code) ? code : 1011, reason.toString().slice(0, 120) || "relay closed");
+      });
+      upstream.on("error", () => {
+        if (socket.readyState === WebSocket.OPEN) socket.close(1011, "relay unavailable");
+      });
+      clearTimeout(authTimer);
+    };
+
+    socket.on("message", (data, isBinary) => {
+      if (isBinary) {
+        socket.close(1003, "JSON text frames only");
+        return;
+      }
+      if (upstream) {
+        const text = data.toString("utf8");
+        if (upstream.readyState === WebSocket.OPEN) upstream.send(text);
+        else queued.push(text);
+        return;
+      }
+      let message;
+      try {
+        message = JSON.parse(data.toString("utf8"));
+      } catch {
+        socket.close(1007, "invalid JSON");
+        return;
+      }
+      if (message?.kind === "hello") {
+        if (Number(message.protocol || 1) !== 1) {
+          socket.close(1002, "unsupported protocol");
+          return;
+        }
+        hello = {
+          v: 1,
+          kind: "hello",
+          clientType: message.clientType === "host" ? "host" : "web",
+          protocol: 1,
+          ...(typeof message.sessionId === "string" ? { sessionId: message.sessionId } : {}),
+          ...(Number.isFinite(Number(message.lastSeq)) ? { lastSeq: Number(message.lastSeq) } : {}),
+        };
+      } else if (message?.kind === "auth" || message?.type === "auth") {
+        token = typeof message.accessToken === "string" ? message.accessToken : typeof message.token === "string" ? message.token : "";
+      } else {
+        socket.close(1002, "hello and auth required");
+        return;
+      }
+      void connectUpstream().catch(() => socket.close(1008, "authentication failed"));
+    });
+    socket.on("close", () => {
+      clearTimeout(authTimer);
+      if (upstream && upstream.readyState < WebSocket.CLOSING) upstream.close();
+      if (room) this.rooms.release(room);
+    });
+    socket.on("error", () => {});
+  }
+}
+
+function parseDeviceToken(token) {
+  const match = /^avx1\.([0-9a-f-]{36})\.([A-Za-z0-9_-]{32,})$/.exec(String(token || ""));
+  return match ? { id: match[1], secret: match[2] } : null;
+}
+
+function deriveSecret(secret, salt) {
+  return crypto.scryptSync(secret, Buffer.from(salt, "base64url"), 32).toString("base64url");
+}
+
+function publicDevice(device, connected) {
+  return {
+    id: device.id,
+    name: device.name,
+    connected,
+    created_at: device.created_at,
+    last_seen_at: device.last_seen_at,
+  };
+}
+
+function normalizeName(value) {
+  const name = typeof value === "string" ? value.trim().replace(/\s+/g, " ").slice(0, 80) : "";
+  return name || "VS Code";
+}
+
+function pairingCode() {
+  const alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+  const bytes = crypto.randomBytes(8);
+  let result = "";
+  for (let index = 0; index < 8; index += 1) result += alphabet[bytes[index] % alphabet.length];
+  return `${result.slice(0, 4)}-${result.slice(4)}`;
+}
+
+function normalizePairingCode(value) {
+  return String(value || "").toUpperCase().replace(/[^A-Z2-9]/g, "");
+}
+
+function randomToken() {
+  return crypto.randomBytes(32).toString("base64url");
+}
+
+function secureEqual(left, right) {
+  const a = Buffer.from(String(left || ""));
+  const b = Buffer.from(String(right || ""));
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+function singleHeaderValue(request, name) {
+  const distinctValues = request.headersDistinct?.[name];
+  if (Array.isArray(distinctValues)) return distinctValues.length === 1 ? distinctValues[0] : null;
+  const value = request.headers[name];
+  return typeof value === "string" ? value : null;
+}
+
+function parsePort(value, fallback) {
+  const parsed = Number(value ?? fallback);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) throw new Error("invalid port");
+  return parsed;
+}
+
+function normalizeOrigins(value) {
+  const values = Array.isArray(value) ? value : String(value || "").split(",");
+  return new Set(values.map(normalizeOrigin).filter(Boolean));
+}
+
+function normalizeOrigin(value) {
+  try {
+    return new URL(String(value).trim()).origin.toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+function validatePublicWsUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("AETHER_VSCODEX_PUBLIC_WS_URL must be an absolute WebSocket URL");
+  }
+  if (url.protocol !== "wss:" && !(url.protocol === "ws:" && isLoopbackHost(url.hostname))) {
+    throw new Error("AETHER_VSCODEX_PUBLIC_WS_URL must use wss:// outside loopback");
+  }
+}
+
+function isLoopbackHost(value) {
+  const host = String(value || "").replace(/^\[|\]$/g, "").toLowerCase();
+  return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+
+function validCloseCode(code) {
+  return code === 1000 || (code >= 1001 && code <= 1014 && ![1004, 1005, 1006].includes(code)) || (code >= 3000 && code <= 4999);
+}
+
+function readJson(request) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    request.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_JSON_BYTES) {
+        reject(httpError(413, "request body too large"));
+        request.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    request.on("end", () => {
+      try {
+        const value = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+        if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error();
+        resolve(value);
+      } catch {
+        reject(httpError(400, "invalid JSON body"));
+      }
+    });
+    request.on("error", reject);
+  });
+}
+
+function jsonResponse(response, statusCode, body, extraHeaders = {}) {
+  if (response.headersSent) return;
+  const payload = Buffer.from(JSON.stringify(body));
+  response.writeHead(statusCode, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Content-Length": payload.length,
+    "Cache-Control": "no-store",
+    ...extraHeaders,
+  });
+  response.end(payload);
+}
+
+function rejectUpgrade(socket, status, reason) {
+  socket.write(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\n\r\n`);
+  socket.destroy();
+}
+
+function httpError(statusCode, message) {
+  return Object.assign(new Error(message), { statusCode, expose: statusCode < 500 });
+}
+
+function allowedMethod(resource, resourceId) {
+  if (resource === "devices" && resourceId) return "DELETE";
+  if (resource === "devices") return "GET";
+  return "POST";
+}
+
+async function main() {
+  const server = new AetherVscodexCloudServer();
+  const address = await server.start();
+  process.stdout.write(`Aether VS Codex sidecar listening on ${address.host}:${address.port}\n`);
+  const shutdown = async () => {
+    await server.stop();
+    process.exit(0);
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    process.stderr.write(`${error.stack || error}\n`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  AetherVscodexCloudServer,
+  DeviceStore,
+  EphemeralCredentials,
+  RoomManager,
+};

aether-vscodex/docker-compose.aether.yml

@@ -0,0 +1,37 @@
+services:
+  app:
+    environment:
+      AETHER_VSCODEX_ENABLED: "true"
+      AETHER_VSCODEX_INTERNAL_URL: http://vscodex:8788
+      AETHER_VSCODEX_INTERNAL_TOKEN: ${AETHER_VSCODEX_INTERNAL_TOKEN:?set AETHER_VSCODEX_INTERNAL_TOKEN}
+      AETHER_VSCODEX_PUBLIC_WS_URL: ${AETHER_VSCODEX_PUBLIC_WS_URL:?set AETHER_VSCODEX_PUBLIC_WS_URL}
+    depends_on:
+      vscodex:
+        condition: service_healthy
+    volumes:
+      - ./aether-vscodex/web/dist:/opt/aether/releases/image/frontend/aether-vscodex:ro
+
+  vscodex:
+    build:
+      context: ./aether-vscodex
+    image: ${AETHER_VSCODEX_IMAGE:-aether-vscodex:local}
+    environment:
+      HOST: 0.0.0.0
+      PORT: 8788
+      AETHER_VSCODEX_INTERNAL_TOKEN: ${AETHER_VSCODEX_INTERNAL_TOKEN:?set AETHER_VSCODEX_INTERNAL_TOKEN}
+      AETHER_VSCODEX_PUBLIC_WS_URL: ${AETHER_VSCODEX_PUBLIC_WS_URL:?set AETHER_VSCODEX_PUBLIC_WS_URL}
+      AETHER_VSCODEX_ALLOWED_ORIGINS: ${AETHER_VSCODEX_ALLOWED_ORIGINS:?set AETHER_VSCODEX_ALLOWED_ORIGINS}
+      AETHER_VSCODEX_DATA_DIR: /var/lib/aether-vscodex
+    expose:
+      - "8788"
+    volumes:
+      - vscodex_data:/var/lib/aether-vscodex
+    logging:
+      driver: local
+      options:
+        max-size: "50m"
+        max-file: "3"
+    restart: unless-stopped
+
+volumes:
+  vscodex_data:

aether-vscodex/docs/cloud-security.md

@@ -0,0 +1,20 @@
+# Cloud security model
+
+## Trust boundaries
+
+- Aether authenticates browser HTTP requests and resolves the user ID. The client never supplies a trusted user ID.
+- The Node sidecar never receives an Aether access token or JWT signing key.
+- A VS Code installation receives one revocable device credential. Only its scrypt hash is persisted.
+- An iframe receives a random, one-time WebSocket ticket with a 60-second lifetime. Tickets are sent in an auth frame, never in a URL.
+- The embedded UI is trusted, same-origin Aether code. `allow-same-origin` is required by the current integration, so the iframe is not a sandbox boundary for untrusted content even though the parent does not post its JWT into the frame.
+- Relay state is isolated by `(user_id, device_id)`. A browser ticket and host credential must resolve to the same room.
+
+## Network boundary
+
+Run the sidecar on the private Compose network. Do not publish port 8788. Aether gateway is the only public HTTP and WebSocket entry point and authenticates internal API calls with `AETHER_VSCODEX_INTERNAL_TOKEN`.
+
+`AETHER_VSCODEX_ALLOWED_ORIGINS` must contain the exact public Aether origin when the sidecar binds outside loopback. Public deployments must use HTTPS/WSS.
+
+## Current scaling limit
+
+The first release intentionally runs one sidecar replica. Pairing codes, browser tickets, and the live connection directory are process-local. Before adding replicas, move those records to a shared atomic store and add sticky or distributed WebSocket room routing.

aether-vscodex/fixtures/fake-app-server.cjs

@@ -0,0 +1,59 @@
+"use strict";
+
+const readline = require("node:readline");
+
+let threadNumber = 0;
+let turnNumber = 0;
+let activeThread = null;
+let activeTurn = null;
+
+function send(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+const input = readline.createInterface({ input: process.stdin });
+input.on("line", (line) => {
+  let request;
+  try { request = JSON.parse(line); } catch { return; }
+  if (request.method === "initialize") {
+    send({ id: request.id, result: { userAgent: "fake", codexHome: "/tmp/codex" } });
+    send({ method: "remoteControl/status/changed", params: { status: "disabled" } });
+    return;
+  }
+  if (request.method === "thread/start") {
+    activeThread = `thread-${++threadNumber}`;
+    send({ id: request.id, result: { thread: { id: activeThread }, cwd: request.params?.cwd || "/tmp" } });
+    send({ method: "thread/started", params: { thread: { id: activeThread } } });
+    return;
+  }
+  if (request.method === "turn/start") {
+    activeTurn = `turn-${++turnNumber}`;
+    send({ id: request.id, result: { turn: { id: activeTurn } } });
+    send({ method: "turn/started", params: { threadId: request.params.threadId, turn: { id: activeTurn } } });
+    const text = request.params.input?.[0]?.text || "";
+    send({ method: "item/agentMessage/delta", params: { threadId: request.params.threadId, turnId: activeTurn, itemId: "item-1", delta: `echo: ${text}` } });
+    if (text.includes("approve")) {
+      send({ id: 9001, method: "item/commandExecution/requestApproval", params: { threadId: request.params.threadId, turnId: activeTurn, itemId: "item-2", command: "echo approval" } });
+    } else {
+      send({ method: "turn/completed", params: { threadId: request.params.threadId, turn: { id: activeTurn } } });
+      activeTurn = null;
+    }
+    return;
+  }
+  if (request.method === "turn/steer") {
+    send({ id: request.id, result: { turn: { id: activeTurn } } });
+    send({ method: "item/agentMessage/delta", params: { delta: `steered: ${request.params.input?.[0]?.text || ""}` } });
+    return;
+  }
+  if (request.method === "turn/interrupt") {
+    send({ id: request.id, result: {} });
+    send({ method: "turn/completed", params: { threadId: request.params.threadId, turn: { id: request.params.turnId } } });
+    activeTurn = null;
+    return;
+  }
+  if (request.id === 9001 && (request.result || request.error)) {
+    send({ method: "item/agentMessage/delta", params: { delta: `approval response: ${JSON.stringify(request.result || request.error)}` } });
+    send({ method: "turn/completed", params: { threadId: activeThread, turn: { id: activeTurn } } });
+    activeTurn = null;
+  }
+});

aether-vscodex/package-lock.json

@@ -0,0 +1,39 @@
+{
+  "name": "aether-vscodex",
+  "version": "0.4.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "aether-vscodex",
+      "version": "0.4.0",
+      "dependencies": {
+        "ws": "^8.18.3"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/ws": {
+      "version": "8.21.3",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.3.tgz",
+      "integrity": "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    }
+  }
+}

aether-vscodex/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "aether-vscodex",
+  "version": "0.4.0",
+  "private": true,
+  "description": "Synchronous VS Code Codex mirroring and asynchronous Codex control for local Web and Aether",
+  "type": "commonjs",
+  "main": "relay/server.js",
+  "scripts": {
+    "start": "node relay/server.js",
+    "start:cloud": "node cloud/server.js",
+    "build:web": "npm --prefix web run build",
+    "build:extension": "npm --prefix vscode-extension run build",
+    "build": "npm run build:web && npm run build:extension",
+    "test": "node --test test/*.test.js",
+    "test:web": "npm --prefix web test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "ws": "^8.18.3"
+  }
+}

aether-vscodex/public/embed-bridge.js

@@ -0,0 +1,112 @@
+(function (root, factory) {
+  "use strict";
+
+  const api = factory();
+  if (typeof module === "object" && module.exports) module.exports = api;
+  if (!root || !root.document) return;
+
+  const bridge = api.createAetherEmbedBridge(root);
+  root.AetherVscodexEmbed = bridge;
+  if (bridge.active) bridge.start();
+})(typeof window === "object" ? window : undefined, function () {
+  "use strict";
+
+  const VERSION = 1;
+  const PREFIX = "aether-vscodex/";
+  const INBOUND_TYPES = new Set(["connect", "context", "disconnect", "error"]);
+
+  function isAetherEmbed(locationLike) {
+    try {
+      return new URLSearchParams(locationLike?.search || "").get("embed") === "aether";
+    } catch {
+      return false;
+    }
+  }
+
+  function normalizeTheme(value) {
+    const theme = String(value || "").trim().toLowerCase();
+    return theme === "dark" || theme === "light" ? theme : "system";
+  }
+
+  function createAetherEmbedBridge(windowLike) {
+    const active = isAetherEmbed(windowLike.location);
+    const listeners = new Map();
+    const pending = new Map();
+    let started = false;
+
+    const emit = (name, payload) => {
+      for (const listener of listeners.get(name) || []) listener(payload);
+    };
+
+    const post = (type, payload = {}) => {
+      if (!active || windowLike.parent === windowLike) return false;
+      windowLike.parent.postMessage({ v: VERSION, type: `${PREFIX}${type}`, ...payload }, windowLike.location.origin);
+      return true;
+    };
+
+    const applyContext = (payload) => {
+      if (payload.locale && windowLike.VscodexI18n?.setLocale) {
+        windowLike.VscodexI18n.setLocale(payload.locale, { persist: false });
+      }
+      const theme = normalizeTheme(payload.theme);
+      const documentElement = windowLike.document?.documentElement;
+      if (documentElement) {
+        if (theme === "system") delete documentElement.dataset.theme;
+        else documentElement.dataset.theme = theme;
+        documentElement.style.colorScheme = theme === "system" ? "" : theme;
+      }
+    };
+
+    const handleMessage = (event) => {
+      if (!active || event.origin !== windowLike.location.origin || event.source !== windowLike.parent) return;
+      const message = event.data;
+      if (!message || typeof message !== "object" || message.v !== VERSION || typeof message.type !== "string") return;
+      if (!message.type.startsWith(PREFIX)) return;
+      const name = message.type.slice(PREFIX.length);
+      if (!INBOUND_TYPES.has(name)) return;
+      if (name === "connect" || name === "context") applyContext(message);
+      if (!(listeners.get(name)?.size)) pending.set(name, message);
+      emit(name, message);
+    };
+
+    return {
+      active,
+      version: VERSION,
+      start() {
+        if (!active || started) return;
+        started = true;
+        windowLike.document.body?.classList.add("embed-aether");
+        windowLike.addEventListener("message", handleMessage);
+        post("ready");
+      },
+      stop() {
+        if (!started) return;
+        started = false;
+        windowLike.removeEventListener("message", handleMessage);
+        listeners.clear();
+        pending.clear();
+      },
+      on(name, listener) {
+        if (!INBOUND_TYPES.has(name) || typeof listener !== "function") return () => undefined;
+        if (!listeners.has(name)) listeners.set(name, new Set());
+        listeners.get(name).add(listener);
+        if (pending.has(name)) {
+          const message = pending.get(name);
+          pending.delete(name);
+          listener(message);
+        }
+        return () => listeners.get(name)?.delete(listener);
+      },
+      post,
+      requestTicket(payload = {}) {
+        return post("request-ticket", payload);
+      },
+      reportState(state, payload = {}) {
+        return post("state", { state, ...payload });
+      },
+      _handleMessage: handleMessage,
+    };
+  }
+
+  return { createAetherEmbedBridge, isAetherEmbed, normalizeTheme };
+});

aether-vscodex/public/i18n.js

@@ -0,0 +1,541 @@
+(function (root, factory) {
+  "use strict";
+
+  const api = factory(root);
+  if (typeof module === "object" && module.exports) module.exports = api;
+  if (root?.document) root.VscodexI18n = api;
+})(typeof window === "object" ? window : undefined, function (root) {
+  "use strict";
+
+  const STORAGE_KEY = "aether-vscodex.locale";
+  const SUPPORTED = new Set(["zh-CN", "en-US"]);
+  const EN = Object.freeze({
+    "本地模式": "Local mode",
+    "独立模式": "Standalone mode",
+    "云端模式": "Cloud mode",
+    "控制模式": "Control mode",
+    "同步": "Sync",
+    "异步": "Async",
+    "同步模式跟随 VS Code 当前会话": "Sync mode follows the current VS Code conversation",
+    "异步模式可独立管理会话": "Async mode manages conversations independently",
+    "正在切换控制模式": "Switching control mode",
+    "控制模式已切换": "Control mode switched",
+    "控制模式切换失败": "Unable to switch control mode",
+    "当前任务或请求完成后才能切换控制模式": "The control mode can be changed after the current task or request finishes",
+    "同步模式下会话管理由 VS Code 控制": "VS Code controls conversation navigation in sync mode",
+    "当前模式不支持修改会话设置": "The current mode does not support changing conversation settings",
+    "本机连接（无需 token）": "Local connection (no token required)",
+    "本机模式无需填写；认证模式再填写": "No token is needed locally; enter one only for authenticated mode",
+    "访问 token（认证模式）": "Access token (authenticated mode)",
+    "粘贴 relay 启动时打印的 token": "Paste the token printed when the relay started",
+    "本地连接无需 token": "No token is needed for a local connection",
+    "编辑外部文件和联网时始终询问": "Always ask before editing external files or using the network",
+    "不限制联网或文件访问": "Allow unrestricted network and file access",
+    "查看请求数据": "View request data",
+    "查看上下文用量": "View context usage",
+    "创建新会话": "New conversation",
+    "打开会话历史": "Open conversation history",
+    "待处理的 Codex 请求": "Pending Codex requests",
+    "当前会话": "Current conversation",
+    "当前模型": "Current model",
+    "切换模型": "Change model",
+    "等待 VS Code 主机": "Waiting for VS Code host",
+    "等待连接": "Waiting for connection",
+    "对话内容": "Conversation",
+    "发送 JSON": "Send JSON",
+    "发送后续指令": "Send follow-up",
+    "发送消息": "Send message",
+    "返回会话列表": "Back to conversations",
+    "返回模型强度": "Back to model effort",
+    "高级": "Advanced",
+    "简洁": "Simple",
+    "更多操作": "More actions",
+    "更高效": "More efficient",
+    "更智能": "More capable",
+    "工作目录": "Working directory",
+    "工作区": "Workspace",
+    "工作区写入": "Workspace write",
+    "回到最新消息": "Jump to latest message",
+    "正在工作，回到最新消息": "Working, jump to latest message",
+    "会话历史": "Conversation history",
+    "会话设置": "Conversation settings",
+    "仅本次 turn": "This turn only",
+    "仅查看文件，不修改工作区": "View files without changing the workspace",
+    "仅对可能不安全的操作询问": "Ask only for potentially unsafe actions",
+    "拒绝": "Deny",
+    "可用会话": "Available conversations",
+    "连接设置": "Connection settings",
+    "留空使用默认模型": "Leave empty to use the default model",
+    "模式": "Mode",
+    "模型": "Model",
+    "模型与推理强度": "Model and reasoning effort",
+    "默认": "Default",
+    "启动新 thread": "Start new thread",
+    "强度": "Effort",
+    "切换模型与推理强度": "Change model and reasoning effort",
+    "清除搜索": "Clear search",
+    "清空当前输出": "Clear current output",
+    "清空对话": "Clear conversation",
+    "取消": "Cancel",
+    "权限设置": "Permission settings",
+    "确认": "Confirm",
+    "确认完全访问": "Confirm full access",
+    "沙箱": "Sandbox",
+    "上下文用量": "Context usage",
+    "设置": "Settings",
+    "审批策略": "Approval policy",
+    "使用 config.toml 中的权限": "Use permissions from config.toml",
+    "使用左右方向键调整强度": "Use the left and right arrow keys to adjust effort",
+    "授权范围": "Authorization scope",
+    "授权与输入": "Approvals and input",
+    "刷新会话列表": "Refresh conversations",
+    "搜索最近会话": "Search recent conversations",
+    "提交后续变更要求": "Ask for follow-up changes",
+    "添加工作区上下文": "Add workspace context",
+    "添加文件": "Add files",
+    "添加文件及更多内容": "Add files and more",
+    "添加照片": "Add photos",
+    "推理强度": "Reasoning effort",
+    "完全访问": "Full access",
+    "完全访问允许 Codex 执行命令、访问互联网并编辑工作区之外的文件。": "Full access lets Codex run commands, use the internet, and edit files outside the workspace.",
+    "网页搜索": "Web search",
+    "未认证": "Unauthenticated",
+    "显示 Codex": "Show Codex",
+    "修改权限": "Change permissions",
+    "需要时询问": "Ask when needed",
+    "已附着当前会话": "Attached to current conversation",
+    "隐藏面板": "Hide panel",
+    "由 Codex 审批": "Let Codex decide",
+    "允许": "Allow",
+    "允许一次": "Allow once",
+    "暂无待处理请求": "No pending requests",
+    "暂无用量数据": "No usage data",
+    "展开面板": "Expand panel",
+    "正在连接": "Connecting",
+    "只读": "Read only",
+    "中断当前 turn": "Interrupt current turn",
+    "重新同步": "Resync",
+    "子代理": "Subagent",
+    "自定义": "Custom",
+    "最近会话": "Recent conversations",
+    "Codex 消息": "Codex messages",
+    "JSON 响应": "JSON response",
+    "语言": "Language",
+    "中文": "Chinese",
+    "跟随浏览器": "Use browser language",
+    "正在连接云端会话": "Connecting to cloud conversation",
+    "正在等待云端连接": "Waiting for cloud connection",
+    "云端连接已断开": "Cloud connection disconnected",
+    "云端连接配置无效": "Invalid cloud connection configuration",
+    "云端连接地址必须与当前页面同源": "The cloud connection URL must be same-origin",
+    "正在获取新的连接凭证": "Requesting new connection credentials",
+    "父页面已断开连接": "Disconnected by the parent page",
+    "当前 relay 需要 token": "This relay requires a token",
+    "WebSocket 未连接": "WebSocket is not connected",
+    "连接中": "Connecting",
+    "同步中": "Syncing",
+    "已连接": "Connected",
+    "认证失败，准备重连": "Authentication failed; preparing to reconnect",
+    "准备重连": "Preparing to reconnect",
+    "重连中": "Reconnecting",
+    "收到无法解析的 relay 消息": "Received an unreadable relay message",
+    "等待 relay 连接": "Waiting for relay connection",
+    "等待 VS Code 主机连接": "Waiting for VS Code host",
+    "VS Code 主机未连接": "VS Code host is disconnected",
+    "等待 VS Code 伴随扩展连接": "Waiting for the VS Code companion extension",
+    "VS Code 伴随扩展未连接": "VS Code companion extension is disconnected",
+    "等待在 VS Code 中打开 Codex 会话": "Open a Codex conversation in VS Code to continue",
+    "会话已关闭": "Conversation closed",
+    "VS Code 会话已关闭": "VS Code conversation closed",
+    "会话操作失败": "Conversation operation failed",
+    "当前任务结束或请求处理后才能切换": "You can switch after the current task or request finishes",
+    "目标会话没有返回 VS Code 快照，请先在官方 Codex 面板打开它": "The target conversation did not return a VS Code snapshot. Open it in the official Codex panel first.",
+    "当前 relay 版本不支持此会话操作，请重启 relay": "This relay version does not support the conversation action. Restart the relay.",
+    "正在读取会话…": "Loading conversations...",
+    "正在切换会话…": "Switching conversation...",
+    "无法读取会话": "Unable to load conversations",
+    "没有匹配的会话": "No matching conversations",
+    "没有可附加的会话": "No attachable conversations",
+    "没有可控制的会话": "No controllable conversations",
+    "正在切换": "Switching",
+    "未打开": "Not open",
+    "当前": "Current",
+    "可切换": "Available",
+    "会话": "Conversation",
+    "当前角色不能创建会话": "Your current role cannot create conversations",
+    "正在创建新会话": "Creating a new conversation",
+    "无法创建新会话": "Unable to create a new conversation",
+    "当前任务仍在运行或等待授权，暂不能切换": "The current task is running or awaiting approval, so it cannot be switched yet",
+    "会话切换失败": "Conversation switch failed",
+    "正在确认会话": "Confirming conversation",
+    "正在加载会话": "Loading conversation",
+    "会话已切换": "Conversation switched",
+    "正在更新模型设置": "Updating model settings",
+    "模型设置已更新": "Model settings updated",
+    "无法更新模型设置": "Unable to update model settings",
+    "已停止": "Stopped",
+    "成功": "Succeeded",
+    "无输出": "No output",
+    "等待输出…": "Waiting for output...",
+    "执行步骤": "Action",
+    "正在读取文件": "Reading files",
+    "读取完成": "Finished reading",
+    "已读取文件运行了命令": "Read files and ran a command",
+    "已读取文件": "Read files",
+    "编辑了文件": "Edited files",
+    "已完成计划": "Completed plan",
+    "读取文件失败": "Failed to read files",
+    "已停止读取文件": "Stopped reading files",
+    "读取文件": "Read files",
+    "已运行命令": "Ran command",
+    "正在运行命令": "Running command",
+    "正在思考": "Thinking",
+    "正在制定计划": "Creating a plan",
+    "正在编辑文件": "Editing files",
+    "正在处理": "Working",
+    "已完成思考": "Finished thinking",
+    "计划完成": "Plan completed",
+    "文件编辑完成": "Finished editing files",
+    "工作说明": "Progress update",
+    "计划": "Plan",
+    "文件变更": "File changes",
+    "等待授权": "Waiting for approval",
+    "正在生成": "Generating",
+    "已中断": "Interrupted",
+    "失败": "Failed",
+    "已完成": "Completed",
+    "正在工作": "Working",
+    "正在等待你的回答": "Waiting for your answer",
+    "正在搜索网页": "Searching the web",
+    "执行失败": "Action failed",
+    "处理中": "Working",
+    "思考": "Reasoning",
+    "编辑文件": "Edit files",
+    "思考中": "Thinking",
+    "编辑中": "Editing",
+    "进行中": "In progress",
+    "异常": "Error",
+    "未读": "Unread",
+    "本地会话": "Local conversation",
+    "默认拒绝，请明确允许": "Denied by default; allow explicitly",
+    "需要远程确认或输入": "Remote confirmation or input is required",
+    "允许运行命令？": "Allow this command?",
+    "允许修改文件？": "Allow file changes?",
+    "需要扩大权限": "Additional permissions required",
+    "Codex 需要你的回答": "Codex needs your answer",
+    "需要外部服务确认": "External service confirmation required",
+    "Codex 请求确认": "Codex requests confirmation",
+    "高风险": "High risk",
+    "低风险": "Low risk",
+    "需确认": "Confirmation required",
+    "请输入": "Enter a response",
+    "提交回答": "Submit answer",
+    "发送自定义响应": "Send custom response",
+    "自定义响应不是有效 JSON": "The custom response is not valid JSON",
+    "响应不是有效 JSON": "The response is not valid JSON",
+    "远程参与者拒绝": "Denied by remote participant",
+    "状态": "Status",
+    "命令": "Command",
+    "详情": "Details",
+    "复制消息": "Copy message",
+    "复制命令": "Copy command",
+    "复制输出": "Copy output",
+    "未知": "Unknown",
+    "未知错误": "Unknown error",
+    "已附着 VS Code 当前 Codex 会话；输入、输出和授权都回到同一个会话。": "Attached to the current VS Code Codex conversation. Messages, output, and approvals all return to that conversation.",
+    "当前为独立 app-server 模式。": "Currently using standalone app-server mode.",
+    "已附着现有会话": "Attached to existing conversation",
+    "通用 Codex 模型": "General-purpose Codex model",
+    "平衡速度与推理": "Balanced speed and reasoning",
+    "可用模型": "Available model",
+    "极低": "Minimal",
+    "轻度": "Low",
+    "标准": "Medium",
+    "深度": "High",
+    "极高": "Extra high",
+    "最大": "Maximum",
+    "此模型使用默认推理强度": "This model uses its default reasoning effort",
+    "返回简洁模型选择": "Return to simple model selection",
+    "显示高级模型选项": "Show advanced model options",
+    "自定义权限由 config.toml 管理": "Custom permissions are managed by config.toml",
+    "正在等待指示": "Waiting for instructions",
+    "正在工作": "Working",
+    "命令输出": "Command output",
+    "工具输出": "Tool output",
+    "发送 Steer": "Send steer",
+    "会话切换失败，已恢复原会话": "Conversation switch failed; restored the previous conversation",
+    "(空消息)": "(empty message)",
+    "今天": "Today",
+    "昨天": "Yesterday",
+    "未完成": "Not completed",
+    "步骤": "Step",
+    "查看图像": "View image",
+    "等待输入": "Waiting for input",
+    "读取文件运行命令失败": "Failed to read files and run a command",
+    "发送输入": "Send input",
+    "工具": "Tool",
+    "工具失败": "Tool failed",
+    "正在搜索": "Searching",
+    "你停止了工作": "You stopped working",
+    "关闭子代理": "Close subagent",
+    "恢复子代理": "Resume subagent",
+    "启动子代理": "Start subagent",
+    "搜索": "Search",
+    "文件": "File",
+    "新会话已在 VS Code 中打开": "The new conversation opened in VS Code",
+    "事件窗口已过期，请以当前快照为准": "The event window expired; the current snapshot is authoritative",
+    "执行状态未知，请等待主机恢复": "Execution status is unknown; wait for the host to recover",
+    "文件已截断": "File truncated",
+    "已拒绝": "Denied",
+    "已开始工作": "Started working",
+    "已添加工作区上下文": "Added workspace context",
+    "已添加网页搜索": "Added web search",
+    "运行命令": "Run command",
+    "整理上下文": "Compacting context",
+    "正在切换会话": "Switching conversation",
+    "MCP 工具": "MCP tool",
+    " · @ 可标记代理": " · @ to mention agents",
+  });
+
+  const EN_PATTERNS = Object.freeze([
+    [/^用时 1分钟(\d+)秒$/, "Worked for 1m{1}s"],
+    [/^用时 (\d+)分(\d+)秒$/, "Worked for {1}m{2}s"],
+    [/^用时 1分钟$/, "Worked for 1m"],
+    [/^用时 (\d+)分$/, "Worked for {1}m"],
+    [/^用时 (\d+)秒$/, "Worked for {1}s"],
+    [/^用时 (\d+)毫秒$/, "Worked for {1}ms"],
+    [/^用时\s+(.+)$/, "Worked for {1}"],
+    [/^已思考 1分钟(\d+)秒$/, "Thought for 1m{1}s"],
+    [/^已思考 (\d+)分(\d+)秒$/, "Thought for {1}m{2}s"],
+    [/^已思考 (\d+)秒$/, "Thought for {1}s"],
+    [/^已思考\s+(.+)$/, "Thought for {1}"],
+    [/^退出码\s+(.+)$/, "Exit code {1}"],
+    [/^正在读取\s+(.+)$/, "Reading {1}", [1]],
+    [/^已读取\s+(.+)$/, "Read {1}", [1]],
+    [/^读取失败\s*·\s*(.+)$/, "Failed to read {1}", [1]],
+    [/^已停止读取\s+(.+)$/, "Stopped reading {1}", [1]],
+    [/^读取\s+(.+)$/, "Read {1}", [1]],
+    [/^已读取这些内容\s*·\s*(\d+)\s*个文件(.*)$/, "Read these items · {1} files{2}"],
+    [/^已在\s+(.+)\s+内运行\s+(.+)$/, "Ran {2} in {1}", [2]],
+    [/^命令运行失败\s*·\s*(.+?)\s*·\s*((?:\d+毫秒|\d+秒|1分钟(?:\d+秒)?|\d+分(?:\d+秒)?))$/, "Command failed · {1} · {2}", [1]],
+    [/^命令运行失败\s*·\s*(.+)$/, "Command failed · {1}", [1]],
+    // Renderer-owned disclosure labels. Keep the captured command/model text
+    // intact; only the surrounding UI words are localized.
+    [/^命令\s*·\s*(.+)$/, "Command · {1}", [1]],
+    [/^已工具\s*·\s*(.+)$/, "Tool completed · {1}"],
+    [/^当前模型\s+(.+?)\s+(极低|轻度|标准|深度|极高|最大)，切换模型$/, "Current model: {1} {2}. Change model", [1]],
+    [/^已停止\s*(.+?)\s*·\s*((?:\d+毫秒|\d+秒|1分钟(?:\d+秒)?|\d+分(?:\d+秒)?))$/, "Stopped {1} · {2}", [1]],
+    [/^已运行\s*(.+)$/, "Ran {1}", [1]],
+    [/^命令运行失败\s*(.*)$/, "Command failed{1}", [1]],
+    [/^命令:\s*(.+?)（执行状态未知，请等待主机恢复）$/, "Command: {1} (execution status unknown; wait for the host to recover)", [1]],
+    [/^命令:\s*(.+)$/, "Command: {1}", [1]],
+    [/^已停止\s*(.+)$/, "Stopped {1}", [1]],
+    [/^正在运行\s+(.+)$/, "Running {1}", [1]],
+    [/^(.+?)\s*·\s*失败$/, "{1} · Failed"],
+    [/^(.+?)\s*·\s*已中断$/, "{1} · Interrupted"],
+    [/^(.+)\s+失败$/, "{1} failed"],
+    [/^编辑了文件\s*·\s*(.+)$/, "Edited files · {1}"],
+    [/^已完成计划\s*·\s*(.+)$/, "Completed plan · {1}"],
+    [/^(\d+)\/(\d+)\s*个会话$/, "{1}/{2} conversations"],
+    [/^(\d+)\s*个会话$/, "{1} conversations"],
+    [/^会话\s+(.+)$/, "Conversation {1}", [1]],
+    [/^工作区\s*·\s*(.+)$/, "Workspace · {1}", [1]],
+    [/^昨天\s+(.+)$/, "Yesterday {1}", [1]],
+    [/^正在切换到「(.+)」…?$/, "Switching to “{1}”...", [1]],
+    [/^你在\s+(.+)\s+后停止了$/, "You stopped after {1}"],
+    [/^执行失败\s*·\s*(.+)$/, "Action failed · {1}"],
+    [/^新会话创建失败：(.+)$/, "Unable to create a new conversation: {1}", [1]],
+    [/^模型设置更新失败：(.+)$/, "Unable to update model settings: {1}", [1]],
+    [/^(.+)（执行状态未知，请等待主机恢复）$/, "{1} (execution status unknown; wait for the host to recover)", [1]],
+    [/^(.+) 完成$/, "{1} completed", [1]],
+    [/^请求 #(.+) 已提交$/, "Request #{1} submitted"],
+    [/^请求 #(.+) 已发送，等待 VS Code 主机确认$/, "Request #{1} sent; waiting for the VS Code host"],
+    [/^无法读取 (.+)$/, "Unable to read {1}", [1]],
+    [/^\[图片附件：(.+)\]$/, "[Image attachment: {1}]", [1]],
+    [/^(.+) 已开始工作$/, "{1} started working", [1]],
+    [/^(.+) 已完成$/, "{1} completed", [1]],
+    [/^(.+) 已中断$/, "{1} interrupted", [1]],
+    [/^…（文件已截断）$/, "... (file truncated)"],
+    [/^当前模型\s+(.+)，切换模型$/, "Current model: {1}. Change model", [1]],
+    [/^切换模型（当前\s+(.+?)\s+(极低|轻度|标准|深度|极高|最大)）$/, "Change model (current: {1} {2})", [1]],
+    [/^切换模型（当前\s+(.+)）$/, "Change model (current: {1})", [1]],
+    [/^修改权限，当前为(.+)$/, "Change permissions. Current: {1}"],
+    [/^修改权限（当前：(.+)）$/, "Change permissions (current: {1})"],
+    [/^上下文已使用\s*(\d+)%（剩余\s*(\d+)%）$/, "Context used: {1}% ({2}% remaining)"],
+    [/^(\d+)%\s*已使用$/, "{1}% used"],
+    [/^剩余\s+(.+)\s+tokens$/, "{1} tokens remaining"],
+    [/^当前上下文\s+(.+)\s+tokens$/, "Current context: {1} tokens"],
+    [/^最近请求\s+(.+)\s+tokens$/, "Latest request: {1} tokens"],
+    [/^累计\s+(.+)\s+tokens$/, "Total: {1} tokens"],
+    [/^使用\s+(.+)$/, "Using {1}", [1]],
+    [/^已用时\s+(.+)$/, "Elapsed: {1}"],
+    [/^(\d+)\s*个后台代理(.*)$/, "{1} background agents{2}"],
+    [/^(\d+)毫秒$/, "{1}ms"],
+    [/^(\d+)秒$/, "{1}s"],
+    [/^1分钟(\d+)秒$/, "1m{1}s"],
+    [/^(\d+)分(\d+)秒$/, "{1}m{2}s"],
+    [/^1分钟(\d+秒)?$/, "1m{1}"],
+    [/^(\d+)分(\d+秒)?$/, "{1}m{2}"],
+  ]);
+  const ZH = Object.freeze(Object.fromEntries(Object.entries(EN).map(([source, translated]) => [translated, source])));
+
+  let currentLocale = "zh-CN";
+  let observer = null;
+  const textSources = new WeakMap();
+  const textRendered = new WeakMap();
+  const attributeSources = new WeakMap();
+  const attributeRendered = new WeakMap();
+
+  function normalizeLocale(value) {
+    const locale = String(value || "").trim().replace("_", "-").toLowerCase();
+    return locale.startsWith("zh") ? "zh-CN" : "en-US";
+  }
+
+  function embeddedMode() {
+    if (root?.AetherVscodexEmbed?.active) return true;
+    try { return new URLSearchParams(root?.location?.search || "").get("embed") === "aether"; }
+    catch { return false; }
+  }
+
+  function interpolate(template, values) {
+    return String(template).replace(/\{(\d+)\}/g, (_, index) => values[Number(index)] ?? "");
+  }
+
+  function translate(value, locale = currentLocale, depth = 0) {
+    const source = String(value ?? "");
+    if (!source) return source;
+    if (normalizeLocale(locale) === "zh-CN") return ZH[source] || source;
+    if (Object.prototype.hasOwnProperty.call(EN, source)) return EN[source];
+    for (const [pattern, template, rawIndexes] of EN_PATTERNS) {
+      const match = source.match(pattern);
+      if (match) {
+        const translatedMatch = match.map((part, index) => index === 0
+          ? part
+          : rawIndexes?.includes(index) ? part
+          : depth < 6 ? translate(part, locale, depth + 1) : (EN[part] || part));
+        return interpolate(template, translatedMatch);
+      }
+    }
+    return source;
+  }
+
+  function shouldSkipTextNode(node) {
+    const parent = node?.parentElement;
+    return Boolean(parent?.closest?.("code, pre, .message-body, .request-summary, .request-questions, .request-json, .request-command, .diff-output, .terminal-output, .session-option-title, .subagent-name, .subagent-summary-label"));
+  }
+
+  function translateTextNode(node) {
+    if (!node || shouldSkipTextNode(node)) return;
+    const current = node.nodeValue;
+    const previousRendered = textRendered.get(node);
+    if (!textSources.has(node) || current !== previousRendered) textSources.set(node, current);
+    const source = textSources.get(node);
+    const leading = source.match(/^\s*/)?.[0] || "";
+    const trailing = source.match(/\s*$/)?.[0] || "";
+    const core = source.slice(leading.length, source.length - trailing.length);
+    if (!core) return;
+    const translated = translate(core);
+    const rendered = `${leading}${translated}${trailing}`;
+    textRendered.set(node, rendered);
+    if (rendered !== current) node.nodeValue = rendered;
+  }
+
+  function translateAttributes(element) {
+    if (!element?.getAttribute || element.closest?.(".message-body, pre, code")) return;
+    let sources = attributeSources.get(element);
+    let renderedValues = attributeRendered.get(element);
+    if (!sources) { sources = new Map(); attributeSources.set(element, sources); }
+    if (!renderedValues) { renderedValues = new Map(); attributeRendered.set(element, renderedValues); }
+    for (const attribute of ["title", "aria-label", "placeholder", "data-placeholder"]) {
+      if (!element.hasAttribute(attribute)) continue;
+      const current = element.getAttribute(attribute);
+      if (!sources.has(attribute) || current !== renderedValues.get(attribute)) sources.set(attribute, current);
+      const source = sources.get(attribute);
+      const translated = translate(source);
+      renderedValues.set(attribute, translated);
+      if (translated !== current) element.setAttribute(attribute, translated);
+    }
+  }
+
+  function translateTree(node) {
+    if (!root?.document || !node) return;
+    if (node.nodeType === 3) {
+      translateTextNode(node);
+      return;
+    }
+    if (node.nodeType !== 1 && node.nodeType !== 9 && node.nodeType !== 11) return;
+    if (node.nodeType === 1) translateAttributes(node);
+    const walker = root.document.createTreeWalker(node, root.NodeFilter.SHOW_ELEMENT | root.NodeFilter.SHOW_TEXT);
+    for (let current = walker.nextNode(); current; current = walker.nextNode()) {
+      if (current.nodeType === 3) translateTextNode(current);
+      else translateAttributes(current);
+    }
+  }
+
+  function applyDocument() {
+    if (!root?.document) return;
+    root.document.documentElement.lang = currentLocale;
+    translateTree(root.document.body);
+    const selector = root.document.getElementById("localeSelect");
+    if (selector && selector.value !== currentLocale) selector.value = currentLocale;
+  }
+
+  function setLocale(value, options = {}) {
+    currentLocale = SUPPORTED.has(value) ? value : normalizeLocale(value);
+    if (options.persist !== false && root?.localStorage && !embeddedMode()) {
+      try { root.localStorage.setItem(STORAGE_KEY, currentLocale); } catch { /* storage may be disabled */ }
+    }
+    applyDocument();
+    if (root?.CustomEvent) root.dispatchEvent?.(new root.CustomEvent("aether-vscodex:locale", { detail: { locale: currentLocale } }));
+    return currentLocale;
+  }
+
+  function initialLocale() {
+    if (embeddedMode()) return normalizeLocale(root?.navigator?.language);
+    try {
+      const saved = root?.localStorage?.getItem(STORAGE_KEY);
+      if (SUPPORTED.has(saved)) return saved;
+    } catch { /* storage may be disabled */ }
+    return normalizeLocale(root?.navigator?.language);
+  }
+
+  function start() {
+    if (!root?.document) return;
+    currentLocale = initialLocale();
+    applyDocument();
+    if (typeof root.MutationObserver === "function" && !observer) {
+      observer = new root.MutationObserver((records) => {
+        if (currentLocale === "zh-CN") return;
+        for (const record of records) {
+          if (record.type === "characterData") translateTextNode(record.target);
+          else if (record.type === "attributes") translateAttributes(record.target);
+          else for (const node of record.addedNodes) translateTree(node);
+        }
+      });
+      observer.observe(root.document.documentElement, {
+        subtree: true,
+        childList: true,
+        characterData: true,
+        attributes: true,
+        attributeFilter: ["title", "aria-label", "placeholder", "data-placeholder"],
+      });
+    }
+  }
+
+  const api = {
+    locale: () => currentLocale,
+    normalizeLocale,
+    setLocale,
+    start,
+    t: (value) => translate(value),
+    translate,
+    translateTree,
+    messages: { "zh-CN": Object.freeze({}), "en-US": EN },
+  };
+
+  if (root?.document) {
+    if (root.document.readyState === "loading") root.document.addEventListener("DOMContentLoaded", start, { once: true });
+    else start();
+  }
+  return api;
+});

aether-vscodex/public/index.html

@@ -0,0 +1,303 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="dark light" />
+    <title>Codex</title>
+    <link rel="stylesheet" href="./style.css" />
+  </head>
+  <body class="codex-app local-no-auth">
+    <div class="codex-panel">
+      <div class="connection" aria-live="polite" hidden>
+        <span id="connectionDot" class="dot offline"></span>
+        <span id="connectionText">正在连接</span>
+        <span id="roleBadge" class="badge">未认证</span>
+      </div>
+      <main class="chat-shell">
+        <section class="chat-header" aria-label="当前会话">
+          <div class="thread-heading">
+            <button id="backButton" class="icon-button header-back-button" type="button" data-panel-action="back" title="返回会话列表" aria-label="返回会话列表" hidden>
+              <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M9.75 3.5 5.25 8l4.5 4.5M5.5 8h6.25" /></svg>
+            </button>
+            <button id="sessionPickerButton" class="thread-picker-button" type="button" aria-haspopup="dialog" aria-expanded="false" title="打开会话历史" aria-label="打开会话历史" disabled>
+              <h2 id="threadTitle">Codex</h2>
+            </button>
+            <span id="appState" class="status-text" aria-live="polite">等待 VS Code 主机</span>
+          </div>
+          <div class="thread-actions">
+            <button class="icon-button" type="button" data-panel-action="menu" title="更多操作" aria-label="更多操作">
+              <svg viewBox="0 0 16 16" aria-hidden="true"><circle cx="3" cy="8" r="1" /><circle cx="8" cy="8" r="1" /><circle cx="13" cy="8" r="1" /></svg>
+            </button>
+            <button id="historyButton" class="icon-button header-history-button" type="button" data-panel-action="history" title="会话历史" aria-label="会话历史" hidden>
+              <svg viewBox="0 0 20 20" aria-hidden="true"><path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8" /><path d="M3 3v5h5" /><path d="M12 7v5l4 2" /></svg>
+            </button>
+            <button class="icon-button" type="button" data-panel-action="settings" title="设置" aria-label="设置">
+              <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M6.7 2h2.6l.4 1.6c.4.2.8.4 1.2.7l1.6-.6 1.3 2.2-1.2 1.1a5 5 0 0 1 0 1.4l1.2 1.1-1.3 2.2-1.6-.6c-.4.3-.8.5-1.2.7L9.3 14H6.7l-.4-1.6a5 5 0 0 1-1.2-.7l-1.6.6-1.3-2.2 1.2-1.1a5 5 0 0 1 0-1.4L2.2 6l1.3-2.2 1.6.6c.4-.3.8-.5 1.2-.7L6.7 2Z" /><circle cx="8" cy="8" r="1.7" /></svg>
+            </button>
+            <button id="newSessionButton" class="icon-button new-session-button" type="button" data-panel-action="new-session" title="创建新会话" aria-label="创建新会话" hidden>
+              <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M3.25 3.25h5.5a1.5 1.5 0 0 1 1.5 1.5v2.5" /><path d="M3.25 3.25v9.5h6" /><path d="m8.2 11.35 4.55-4.55 1.25 1.25-4.55 4.55-2 .5Z" /></svg>
+            </button>
+          </div>
+        </section>
+        <div id="panelMenu" class="panel-popover panel-menu" hidden>
+          <button type="button" data-menu-action="sessions" hidden>最近会话</button>
+          <button type="button" data-menu-action="clear">清空当前输出</button>
+          <button type="button" data-menu-action="refresh">重新同步</button>
+          <button type="button" data-menu-action="expand">展开面板</button>
+          <button type="button" data-menu-action="close">隐藏面板</button>
+        </div>
+        <div id="detailsPopover" class="panel-popover details-popover settings-popover" hidden role="dialog" aria-label="设置">
+          <div class="popover-title">设置</div>
+          <div class="settings-shortcuts">
+            <button type="button" data-settings-action="model"><span>模型与推理强度</span><span id="settingsModelValue">默认</span></button>
+            <button type="button" data-settings-action="permission"><span>修改权限</span><span id="settingsPermissionValue">工作区写入</span></button>
+            <label id="localeSetting" class="settings-locale">
+              <span>语言</span>
+              <select id="localeSelect" aria-label="语言">
+                <option value="zh-CN">中文</option>
+                <option value="en-US">English</option>
+              </select>
+            </label>
+          </div>
+          <div class="settings-divider"></div>
+          <div class="popover-subtitle">当前会话</div>
+          <dl>
+            <dt>工作区</dt><dd id="popoverCwd">-</dd>
+            <dt>模式</dt><dd id="popoverMode">本地模式</dd>
+            <dt>thread</dt><dd id="popoverThread">-</dd>
+          </dl>
+        </div>
+        <div id="sessionPicker" class="panel-popover session-picker" hidden role="dialog" aria-label="最近会话">
+          <div class="session-picker-header">
+            <span class="popover-title">最近会话</span>
+            <button id="sessionPickerRefresh" class="session-picker-refresh" type="button" title="刷新会话列表" aria-label="刷新会话列表">
+              <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M13 5V2m0 0h-3m3 0-2.1 2.1A5 5 0 1 0 13 9" /></svg>
+            </button>
+          </div>
+          <div class="session-search">
+            <svg viewBox="0 0 16 16" aria-hidden="true"><circle cx="6.8" cy="6.8" r="3.8" /><path d="m9.7 9.7 3.2 3.2" /></svg>
+            <label class="sr-only" for="sessionSearchInput">搜索最近会话</label>
+            <input id="sessionSearchInput" type="search" autocomplete="off" spellcheck="false" placeholder="搜索最近会话" aria-label="搜索最近会话" aria-controls="sessionList" aria-expanded="false" />
+            <button id="sessionSearchClear" class="session-search-clear" type="button" title="清除搜索" aria-label="清除搜索" hidden>
+              <svg viewBox="0 0 16 16" aria-hidden="true"><path d="m4.5 4.5 7 7m0-7-7 7" /></svg>
+            </button>
+          </div>
+          <div id="sessionPickerStatus" class="session-picker-status" role="status" aria-live="polite"></div>
+          <div id="sessionList" class="session-list" role="listbox" aria-label="可用会话" tabindex="0"></div>
+        </div>
+
+        <section class="chat-panel" aria-label="对话内容">
+          <div id="output" class="output chat-scroll" tabindex="0" aria-live="polite" aria-label="Codex 消息"></div>
+          <button id="scrollToBottom" class="scroll-to-bottom" type="button" aria-label="回到最新消息" aria-hidden="true" tabindex="-1">
+            <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M8 3v9M4.5 8.5 8 12l3.5-3.5" /></svg>
+            <span class="scroll-working-dots" aria-hidden="true"><i></i><i></i><i></i></span>
+          </button>
+          <div id="inlineRequests" class="inline-requests" aria-live="polite" aria-label="待处理的 Codex 请求"></div>
+        </section>
+
+        <section id="messageForm" class="composer" aria-label="发送消息">
+          <section id="subagentsPanel" class="subagents-panel" aria-label="子代理" hidden>
+            <button id="subagentsToggle" class="subagents-toggle" type="button" aria-expanded="false">
+              <span class="subagents-title">子代理</span>
+              <span id="subagentsCount" class="subagents-count"></span>
+              <svg viewBox="0 0 16 16" aria-hidden="true"><path d="m6 3 5 5-5 5" /></svg>
+            </button>
+            <div id="subagentsList" class="subagents-list"></div>
+          </section>
+          <div id="liveActivity" class="live-activity" role="status" aria-live="polite" hidden>
+            <span class="activity-spinner" aria-hidden="true"></span>
+            <span class="activity-label"></span>
+            <span class="activity-dots" aria-hidden="true"><i></i><i></i><i></i></span>
+            <span class="activity-elapsed"></span>
+          </div>
+          <div class="composer-surface">
+            <div
+              id="messageInput"
+              class="composer-editor"
+              contenteditable="true"
+              role="textbox"
+              aria-multiline="true"
+              data-placeholder="提交后续变更要求"
+              spellcheck="true"
+            ></div>
+            <div class="composer-footer">
+              <div class="composer-hint">
+                <button id="composerPlusButton" class="composer-icon-button" type="button" aria-haspopup="menu" aria-expanded="false" title="添加文件及更多内容" aria-label="添加文件及更多内容">
+                  <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M8 3v10M3 8h10" /></svg>
+                </button>
+                <div id="composerPlusMenu" class="composer-popover composer-plus-menu" role="menu" hidden>
+                  <div class="composer-popover-heading">添加文件及更多内容</div>
+                  <button type="button" role="menuitem" data-composer-action="attach">添加文件</button>
+                  <button type="button" role="menuitem" data-composer-action="photo">添加照片</button>
+                  <button type="button" role="menuitem" data-composer-action="workspace">添加工作区上下文</button>
+                  <button type="button" role="menuitem" data-composer-action="web-search">网页搜索</button>
+                </div>
+                <input id="attachmentInput" type="file" accept=".txt,.md,.json,.js,.ts,.tsx,.jsx,.css,.html,.yml,.yaml,.xml,.py,.go,.rs,.java,.c,.cpp,.h,image/*" multiple hidden />
+                <button id="permissionChip" class="permission-chip" type="button" aria-haspopup="menu" aria-expanded="false" title="修改权限" aria-label="修改权限">
+                  <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M8 1.8 13 4v3.6c0 3-2 5.6-5 6.6-3-1-5-3.6-5-6.6V4l5-2.2Z" /><path d="m5.5 8 1.6 1.6L10.8 6" /></svg>
+                  <span id="permissionLabel">工作区写入</span>
+                  <svg class="permission-chevron" viewBox="0 0 16 16" aria-hidden="true"><path d="m4.5 6 3.5 3.5L11.5 6" /></svg>
+                </button>
+                <div id="permissionMenu" class="composer-popover permission-menu" role="menu" aria-label="权限设置" hidden>
+                  <div class="composer-popover-heading">修改权限</div>
+                  <button type="button" role="menuitemradio" data-permission-mode="ask" aria-checked="false"><span>需要时询问</span><small>编辑外部文件和联网时始终询问</small></button>
+                  <button type="button" role="menuitemradio" data-permission-mode="auto" aria-checked="false"><span>由 Codex 审批</span><small>仅对可能不安全的操作询问</small></button>
+                  <button type="button" role="menuitemradio" data-permission-mode="full" aria-checked="false"><span>完全访问</span><small>不限制联网或文件访问</small></button>
+                  <button type="button" role="menuitemradio" data-permission-mode="custom" aria-checked="false"><span>自定义</span><small>使用 config.toml 中的权限</small></button>
+                  <button type="button" role="menuitemradio" data-permission-mode="readonly" aria-checked="false"><span>只读</span><small>仅查看文件，不修改工作区</small></button>
+                </div>
+                <div id="permissionConfirm" class="permission-confirm" role="dialog" aria-modal="true" aria-labelledby="permissionConfirmTitle" hidden>
+                  <div id="permissionConfirmTitle" class="permission-confirm-title">确认完全访问</div>
+                  <p>完全访问允许 Codex 执行命令、访问互联网并编辑工作区之外的文件。</p>
+                  <div class="permission-confirm-actions">
+                    <button id="permissionConfirmCancel" type="button">取消</button>
+                    <button id="permissionConfirmAccept" class="primary" type="button">确认</button>
+                  </div>
+                </div>
+                <div id="usagePicker" class="usage-picker" hidden>
+                  <button id="usageButton" class="usage-button" type="button" aria-haspopup="dialog" aria-expanded="false" title="查看上下文用量" aria-label="查看上下文用量"><span id="usageRing" class="usage-ring" aria-hidden="true"><span id="usageLabel">0%</span></span></button>
+                  <div id="usageMenu" class="composer-popover usage-menu" role="dialog" aria-label="上下文用量" hidden>
+                    <div class="composer-popover-heading">上下文用量</div>
+                    <div id="usageSummary" class="usage-summary">暂无用量数据</div>
+                    <div class="usage-meter"><span id="usageMeterBar"></span></div>
+                    <div id="usageDetails" class="usage-details"></div>
+                  </div>
+                </div>
+                <span id="factApp" class="sr-only">-</span>
+                <span id="factClients" class="sr-only">-</span>
+                <span id="factRequests" class="sr-only">0</span>
+              </div>
+              <div class="composer-actions">
+                <div id="modelPicker" class="model-picker">
+                  <button id="modelPickerButton" class="model-picker-button" type="button" aria-haspopup="menu" aria-expanded="false" title="切换模型与推理强度" hidden>
+                    <span id="modelLabel" class="model-label"></span>
+                    <span id="modelEffortLabel" class="model-effort-label"></span>
+                    <svg viewBox="0 0 16 16" aria-hidden="true"><path d="m4.5 6 3.5 3.5L11.5 6" /></svg>
+                  </button>
+                  <div id="modelMenu" class="model-menu" role="menu" aria-label="模型与推理强度" hidden>
+                    <div id="modelPowerView" class="model-power-view">
+                      <div class="model-power-heading">
+                        <span>推理强度</span>
+                        <button id="modelAdvancedToggle" class="model-advanced-toggle" type="button">高级</button>
+                      </div>
+                      <div class="model-power-control">
+                        <span class="model-power-label">更高效</span>
+                        <input id="modelPowerSlider" class="model-power-slider" type="range" min="0" max="3" step="1" value="1" aria-label="强度" aria-describedby="modelPowerInstructions" />
+                        <span class="model-power-label">更智能</span>
+                      </div>
+                      <div id="modelPowerValue" class="model-power-value"></div>
+                      <span id="modelPowerInstructions" class="sr-only">使用左右方向键调整强度</span>
+                    </div>
+                    <div id="modelAdvancedView" class="model-advanced-view" hidden>
+                      <div class="model-advanced-toolbar">
+                        <button id="modelAdvancedBack" class="model-advanced-back" type="button" aria-label="返回模型强度">‹</button>
+                        <span>模型与推理强度</span>
+                      </div>
+                      <div class="model-menu-heading">模型</div>
+                      <div id="modelOptions" class="model-options" role="listbox" aria-label="模型"></div>
+                      <div class="model-menu-heading effort-heading">推理强度</div>
+                      <div id="effortOptions" class="effort-options" role="listbox" aria-label="推理强度"></div>
+                    </div>
+                  </div>
+                </div>
+                <button id="interruptButton" class="compact-action interrupt-action" type="button" disabled title="中断当前 turn" aria-label="中断当前 turn">
+                  <svg viewBox="0 0 16 16" aria-hidden="true"><rect x="4.5" y="4.5" width="7" height="7" rx="1" /></svg>
+                </button>
+                <button id="steerButton" class="primary compact-action steer-action" type="button" disabled title="发送后续指令" aria-label="发送后续指令">
+                  <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M8 12V4M4.5 7.5 8 4l3.5 3.5" /></svg>
+                </button>
+                <button id="startTurnButton" class="primary send-button" type="button" disabled title="发送消息" aria-label="发送消息">
+                  <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M8 12V4M4.5 7.5 8 4l3.5 3.5" /></svg>
+                </button>
+              </div>
+            </div>
+          </div>
+          <div class="mode-row">
+            <span class="connection-mode-label">
+              <svg class="mode-icon" viewBox="0 0 16 16" aria-hidden="true"><rect x="2" y="3" width="12" height="8" rx="1" /><path d="M5 13h6M8 11v2" /></svg>
+              <span id="modeLabel">本地模式</span>
+            </span>
+            <div id="controlModeSwitch" class="control-mode-switch" role="group" aria-label="控制模式" aria-busy="false" data-mode="sync" data-switching="false">
+              <button type="button" data-control-mode="sync" aria-pressed="true" title="同步模式跟随 VS Code 当前会话" disabled>同步</button>
+              <button type="button" data-control-mode="async" aria-pressed="false" title="异步模式可独立管理会话" disabled>异步</button>
+            </div>
+          </div>
+        </section>
+      </main>
+    </div>
+    <button id="restorePanel" class="restore-panel" type="button" hidden>显示 Codex</button>
+
+    <!-- Protocol compatibility state stays out of the visual shell. -->
+    <section class="compatibility-state" aria-hidden="true" hidden inert>
+      <details id="sessionSettings">
+        <summary>会话设置</summary>
+        <div class="settings-grid">
+          <label>工作目录<input id="cwdInput" type="text" /></label>
+          <label>模型<input id="modelInput" type="text" placeholder="留空使用默认模型" /></label>
+          <label>沙箱
+            <select id="sandboxInput">
+              <option value="workspace-write">workspace-write</option>
+              <option value="read-only">read-only</option>
+              <option value="danger-full-access">danger-full-access</option>
+            </select>
+          </label>
+          <label>审批策略
+            <select id="approvalInput">
+              <option value="on-request">on-request</option>
+              <option value="untrusted">untrusted</option>
+              <option value="never">never</option>
+            </select>
+          </label>
+          <button id="startThreadButton" class="secondary" type="button">启动新 thread</button>
+          <div class="ids">
+            <span>thread</span><code id="threadId">-</code>
+            <span>turn</span><code id="turnId">-</code>
+          </div>
+        </div>
+      </details>
+      <details id="connectionSettings">
+        <summary>连接设置</summary>
+        <label class="token-field">
+          <span id="tokenLabel">本机连接（无需 token）</span>
+          <input id="tokenInput" type="password" autocomplete="off" placeholder="本机模式无需填写；认证模式再填写" />
+        </label>
+      </details>
+      <span id="sessionMode">已附着当前会话</span>
+      <span id="latestSeq">seq -</span>
+      <span id="outputHint">等待连接</span>
+      <button id="clearOutputButton" type="button">清空对话</button>
+      <span id="lastEvent">-</span>
+      <details id="requestsPanel"><summary><span>授权与输入</span><span id="requestCount" class="badge warning">0</span></summary><div id="requests" class="requests empty">暂无待处理请求</div></details>
+    </section>
+
+    <template id="requestTemplate">
+      <article class="request">
+        <div class="request-title"><span class="request-icon" aria-hidden="true">!</span><strong class="request-method"></strong><span class="request-risk"></span><span class="request-id"></span></div>
+        <p class="request-summary"></p>
+        <pre class="request-command"></pre>
+        <div class="request-questions"></div>
+        <label class="request-scope-wrap" hidden>
+          <span>授权范围</span>
+          <select class="request-scope">
+            <option value="turn">仅本次 turn</option>
+            <option value="session">当前会话</option>
+          </select>
+        </label>
+        <details class="request-details">
+          <summary>查看请求数据</summary>
+          <pre class="request-json"></pre>
+        </details>
+        <textarea class="request-response" rows="4" aria-label="JSON 响应"></textarea>
+        <div class="button-row request-actions">
+          <button class="primary request-allow">允许</button>
+          <button class="secondary request-deny">拒绝</button>
+          <button class="secondary request-send">发送 JSON</button>
+        </div>
+      </article>
+    </template>
+    <script src="./embed-bridge.js" defer></script>
+    <script src="./i18n.js" defer></script>
+    <script src="./app.js" defer></script>
+  </body>
+</html>

aether-vscodex/test/adapter-safety.test.js

@@ -0,0 +1,745 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const { CodexAgentAdapter } = require("../vscode-extension/dist/codexAgentAdapter.js");
+const { RelayHost } = require("../vscode-extension/dist/relayHost.js");
+
+class FakeRpc {
+  responses = [];
+  requests = [];
+  notificationListener;
+  requestListener;
+  exitListener;
+  overrides;
+
+  constructor(overrides = {}) {
+    this.overrides = overrides;
+  }
+
+  get running() {
+    return true;
+  }
+
+  async start() {}
+
+  async request(method, params) {
+    this.requests.push({ method, params });
+    if (Object.prototype.hasOwnProperty.call(this.overrides, method)) {
+      const override = this.overrides[method];
+      return typeof override === "function" ? override(params) : override;
+    }
+    if (method === "initialize") return { userAgent: "test", codexHome: "/tmp/codex" };
+    if (method === "thread/start") return { thread: { id: "thread-test" }, cwd: "/tmp" };
+    if (method === "turn/start") return { turn: { id: "turn-test" } };
+    if (method === "turn/steer") return { turn: { id: "turn-test" } };
+    if (method === "turn/interrupt") return {};
+    throw new Error(`unexpected request ${method}`);
+  }
+
+  notify() {}
+
+  respond(id, result) {
+    this.responses.push({ id, result });
+  }
+
+  respondError(id, code, message) {
+    this.responses.push({ id, error: { code, message } });
+  }
+
+  onNotification(listener) {
+    this.notificationListener = listener;
+    return { dispose: () => undefined };
+  }
+
+  onServerRequest(listener) {
+    this.requestListener = listener;
+    return { dispose: () => undefined };
+  }
+
+  onExit(listener) {
+    this.exitListener = listener;
+    return { dispose: () => undefined };
+  }
+
+  close() {}
+
+  emitRequest(request) {
+    this.requestListener(request);
+  }
+
+  emitNotification(notification) {
+    this.notificationListener(notification);
+  }
+}
+
+class FakeRelay {
+  frames = [];
+  listeners = new Set();
+
+  async connect() {}
+
+  send(frame) {
+    this.frames.push(frame);
+  }
+
+  onMessage(listener) {
+    this.listeners.add(listener);
+    return { dispose: () => this.listeners.delete(listener) };
+  }
+
+  close() {}
+}
+
+test("CodexAgentAdapter keeps numeric and string approval ids distinct", async () => {
+  const rpc = new FakeRpc();
+  const adapter = new CodexAgentAdapter({ approvalTimeoutMs: 0 }, rpc);
+  await adapter.start();
+
+  rpc.emitRequest({
+    id: 1,
+    method: "item/commandExecution/requestApproval",
+    params: { threadId: "t", turnId: "u", itemId: "n", command: "echo number" },
+  });
+  rpc.emitRequest({
+    id: "1",
+    method: "item/commandExecution/requestApproval",
+    params: { threadId: "t", turnId: "u", itemId: "s", command: "echo string" },
+  });
+
+  const snapshot = await adapter.snapshot();
+  assert.deepEqual(snapshot.pendingApprovals.map((entry) => entry.requestId), [1, "1"]);
+  await adapter.respondApproval(1, "deny");
+  await adapter.respondApproval("1", "deny");
+  assert.deepEqual(rpc.responses.map((entry) => entry.id), [1, "1"]);
+  assert.equal((await adapter.snapshot()).pendingApprovals.length, 0);
+  await adapter.dispose();
+});
+
+test("commandActions are included in high-risk approval classification", async () => {
+  const rpc = new FakeRpc();
+  const adapter = new CodexAgentAdapter({ approvalTimeoutMs: 0 }, rpc);
+  await adapter.start();
+  rpc.emitRequest({
+    id: 2,
+    method: "item/commandExecution/requestApproval",
+    params: {
+      threadId: "t",
+      turnId: "u",
+      itemId: "actions",
+      command: null,
+      commandActions: [{ type: "unknown", command: "sudo rm -rf /" }],
+    },
+  });
+  const snapshot = await adapter.snapshot();
+  assert.equal(snapshot.pendingApprovals[0].risk, "high");
+  await adapter.respondApproval(2, "deny");
+  await adapter.dispose();
+});
+
+test("output snapshots stay redacted and interrupt clears the active turn", async () => {
+  const rpc = new FakeRpc();
+  const adapter = new CodexAgentAdapter({ approvalTimeoutMs: 0 }, rpc);
+  await adapter.start();
+  await adapter.startThread({});
+  await adapter.startTurn({ text: "hello" });
+  assert.equal((await adapter.snapshot()).turnId, "turn-test");
+
+  rpc.emitNotification({
+    method: "item/agentMessage/delta",
+    params: { delta: "credential Bearer abcdefghijklmnop" },
+  });
+  const snapshot = await adapter.snapshot();
+  assert.equal(snapshot.outputTail.includes("Bearer abcdefghijklmnop"), false);
+  assert.match(snapshot.outputTail, /\[REDACTED\]/);
+
+  await adapter.interruptTurn({});
+  const afterInterrupt = await adapter.snapshot();
+  assert.equal(afterInterrupt.turnId, null);
+  assert.equal(afterInterrupt.state, "idle");
+  await adapter.dispose();
+});
+
+test("async adapter lists app-server threads and exposes the model catalog", async () => {
+  const rpc = new FakeRpc({
+    "model/list": {
+      data: [{ id: "model-1", model: "gpt-5.6-sol", displayName: "5.6 Sol", hidden: false }],
+      nextCursor: null,
+    },
+    "thread/list": {
+      data: [
+        {
+          id: "thread-recent",
+          name: null,
+          preview: "Inspect the workspace\nwith detail",
+          cwd: "/tmp/workspace",
+          createdAt: 1_700_000_000,
+          updatedAt: 1_700_000_100,
+          status: { type: "idle" },
+          source: "vscode",
+        },
+      ],
+      nextCursor: "next-page",
+      backwardsCursor: null,
+    },
+  });
+  const adapter = new CodexAgentAdapter({ approvalTimeoutMs: 0 }, rpc);
+  await adapter.start();
+
+  const result = await adapter.listSessions({ limit: 500, query: "workspace", sortKey: "invalid" });
+  assert.equal(result.sessions[0].threadId, "thread-recent");
+  assert.equal(result.sessions[0].title, "Inspect the workspace with detail");
+  assert.equal(result.sessions[0].updatedAtMs, 1_700_000_100_000);
+  assert.equal(result.nextCursor, "next-page");
+  const listRequest = rpc.requests.find((entry) => entry.method === "thread/list");
+  assert.deepEqual(listRequest.params, {
+    limit: 100,
+    sortKey: "updated_at",
+    sortDirection: "desc",
+    searchTerm: "workspace",
+  });
+  const snapshot = await adapter.snapshot();
+  assert.equal(snapshot.metadata.mode, "async");
+  assert.equal(snapshot.metadata.availableModels[0].model, "gpt-5.6-sol");
+  await adapter.dispose();
+});
+
+test("async adapter projects live token usage notifications into metadata and snapshots", async () => {
+  const rpc = new FakeRpc({
+    "model/list": { data: [], nextCursor: null },
+  });
+  const adapter = new CodexAgentAdapter({ approvalTimeoutMs: 0 }, rpc);
+  const events = [];
+  adapter.onEvent((event) => events.push(event));
+  await adapter.start();
+  await adapter.startThread({});
+
+  rpc.emitNotification({
+    method: "thread/tokenUsage/updated",
+    params: {
+      threadId: "thread-test",
+      // A usage update may arrive after the turn has completed. It must not
+      // make the adapter report that historical turn as active again.
+      turnId: "turn-finished",
+      tokenUsage: {
+        total: {
+          totalTokens: 1_200,
+          inputTokens: 800,
+          cachedInputTokens: 100,
+          cacheWriteInputTokens: 20,
+          outputTokens: 300,
+          reasoningOutputTokens: 80,
+        },
+        last: {
+          totalTokens: 450,
+          inputTokens: 300,
+          cachedInputTokens: 40,
+          cacheWriteInputTokens: 10,
+          outputTokens: 100,
+          reasoningOutputTokens: 40,
+        },
+        modelContextWindow: 128_000,
+      },
+    },
+  });
+
+  const expected = {
+    total: {
+      totalTokens: 1_200,
+      inputTokens: 800,
+      cachedInputTokens: 100,
+      cacheWriteInputTokens: 20,
+      outputTokens: 300,
+      reasoningOutputTokens: 80,
+    },
+    last: {
+      totalTokens: 450,
+      inputTokens: 300,
+      cachedInputTokens: 40,
+      cacheWriteInputTokens: 10,
+      outputTokens: 100,
+      reasoningOutputTokens: 40,
+    },
+    modelContextWindow: 128_000,
+  };
+  const snapshot = await adapter.snapshot();
+  assert.deepEqual(snapshot.metadata.tokenUsage, expected);
+  assert.deepEqual(snapshot.metadata.latestTokenUsageInfo, expected);
+  assert.equal(snapshot.turnId, null);
+
+  const usageEvent = events.find((event) => event.raw?.method === "thread/tokenUsage/updated");
+  assert.ok(usageEvent);
+  assert.deepEqual(usageEvent.payload.tokenUsage, expected);
+  assert.deepEqual(usageEvent.payload.latestTokenUsageInfo, expected);
+  // Keep the raw diagnostic envelope redacted while exposing only the safe
+  // numeric projection to the browser.
+  assert.equal(usageEvent.raw.params.tokenUsage, "[REDACTED]");
+
+  rpc.emitNotification({
+    method: "thread/tokenUsage/updated",
+    params: {
+      threadId: "thread-test",
+      turnId: "turn-finished",
+      tokenUsage: { total: { inputTokens: -1 } },
+    },
+  });
+  assert.deepEqual((await adapter.snapshot()).metadata.tokenUsage, expected);
+  await adapter.dispose();
+});
+
+test("async adapter resumes a thread with structured history and ignores late notifications", async () => {
+  const thread = {
+    id: "thread-selected",
+    name: "Selected thread",
+    preview: "hello",
+    cwd: "/tmp/selected",
+    createdAt: 1_700_000_000,
+    updatedAt: 1_700_000_010,
+    status: { type: "idle" },
+    turns: [{
+      id: "turn-history",
+      status: "completed",
+      startedAt: 1_700_000_001,
+      completedAt: 1_700_000_004,
+      durationMs: 3_000,
+      items: [
+        { type: "userMessage", id: "user-1", clientId: null, content: [{ type: "text", text: "hello", text_elements: [] }] },
+        { type: "reasoning", id: "reason-1", summary: ["Checking files"], content: [] },
+        { type: "commandExecution", id: "command-1", command: "pwd", cwd: "/tmp/selected", status: "completed", aggregatedOutput: "/tmp/selected\n", exitCode: 0, durationMs: 50, commandActions: [] },
+        { type: "agentMessage", id: "agent-1", text: "Done", phase: "final_answer" },
+      ],
+    }],
+  };
+  const rpc = new FakeRpc({
+    "model/list": { data: [{ id: "model-1", model: "gpt-5.6-sol" }], nextCursor: null },
+    "thread/resume": {
+      thread,
+      model: "gpt-5.6-sol",
+      modelProvider: "openai",
+      serviceTier: null,
+      cwd: "/tmp/selected",
+      approvalPolicy: "on-request",
+      approvalsReviewer: "user",
+      sandbox: { type: "workspaceWrite" },
+      reasoningEffort: "high",
+    },
+  });
+  const adapter = new CodexAgentAdapter({ approvalTimeoutMs: 0 }, rpc);
+  const events = [];
+  adapter.onEvent((event) => events.push(event));
+  await adapter.start();
+
+  const result = await adapter.selectSession({ threadId: "thread-selected" });
+  assert.equal(result.threadId, "thread-selected");
+  let snapshot = await adapter.snapshot();
+  assert.equal(snapshot.messages.length, 4);
+  assert.deepEqual(snapshot.messages.map((message) => message.kind), ["user", "reasoning", "tool", "assistant"]);
+  assert.equal(snapshot.messages[2].output, "/tmp/selected\n");
+  assert.equal(snapshot.metadata.title, "Selected thread");
+  assert.equal(snapshot.metadata.threadSettings.effort, "high");
+  assert.equal(snapshot.metadata.historyComplete, true);
+  assert.equal(snapshot.status.turnStatus, "completed");
+  assert.match(snapshot.outputTail, /Done/);
+  assert.ok(events.some((event) => event.type === "output.snapshot" && event.payload.historyComplete === true));
+  const authoritative = events.find((event) => event.type === "session.snapshot");
+  assert.equal(authoritative.payload.threadId, "thread-selected");
+  assert.equal(authoritative.payload.metadata.model, "gpt-5.6-sol");
+  assert.equal(authoritative.payload.messages.length, 4);
+
+  rpc.emitNotification({
+    method: "item/completed",
+    params: {
+      threadId: "thread-old",
+      turnId: "turn-old",
+      completedAtMs: Date.now(),
+      item: { type: "agentMessage", id: "late-old", text: "wrong thread" },
+    },
+  });
+  rpc.emitNotification({
+    method: "item/completed",
+    params: {
+      threadId: "thread-selected",
+      turnId: "turn-live",
+      completedAtMs: Date.now(),
+      item: { type: "agentMessage", id: "current-item", text: "current thread" },
+    },
+  });
+  snapshot = await adapter.snapshot();
+  assert.equal(snapshot.messages.some((message) => message.itemId === "late-old"), false);
+  assert.equal(snapshot.messages.some((message) => message.itemId === "current-item"), true);
+  await adapter.dispose();
+});
+
+test("async adapter hydrates paginated turns and items into chronological complete history", async () => {
+  const threadId = "thread-paged-history";
+  const userItem = (id, text) => ({
+    type: "userMessage",
+    id,
+    clientId: null,
+    content: [{ type: "text", text, text_elements: [] }],
+  });
+  const assistantItem = (id, text) => ({
+    type: "agentMessage",
+    id,
+    text,
+    phase: "final_answer",
+  });
+  const earlyUser = userItem("early-user", "first question");
+  const rpc = new FakeRpc({
+    "model/list": { data: [], nextCursor: null },
+    "thread/resume": {
+      thread: {
+        id: threadId,
+        name: "Paged history",
+        preview: "first question",
+        cwd: "/tmp/paged",
+        createdAt: 50,
+        updatedAt: 350,
+        historyMode: "paginated",
+        status: { type: "idle" },
+        turns: [],
+      },
+      model: "gpt-5.6-sol",
+      cwd: "/tmp/paged",
+      initialTurnsPage: {
+        data: [{
+          id: "turn-late",
+          status: "completed",
+          startedAt: 300,
+          completedAt: 310,
+          itemsView: "full",
+          items: [userItem("late-user", "third question"), assistantItem("late-agent", "third answer")],
+        }],
+        nextCursor: "turn-page-2",
+        backwardsCursor: null,
+      },
+    },
+    "thread/turns/list": (params) => {
+      if (params.cursor === "turn-page-2") {
+        return {
+          data: [{
+            id: "turn-early",
+            status: "completed",
+            startedAt: 100,
+            completedAt: 110,
+            itemsView: "summary",
+            items: [earlyUser],
+          }],
+          nextCursor: "turn-page-3",
+          backwardsCursor: null,
+        };
+      }
+      assert.equal(params.cursor, "turn-page-3");
+      return {
+        data: [{
+          id: "turn-middle",
+          status: "completed",
+          startedAt: 200,
+          completedAt: 210,
+          itemsView: "full",
+          items: [userItem("middle-user", "second question"), assistantItem("middle-agent", "second answer")],
+        }],
+        nextCursor: null,
+        backwardsCursor: null,
+      };
+    },
+    "thread/items/list": (params) => {
+      assert.equal(params.turnId, "turn-early");
+      return {
+        data: [
+          // The summary row is repeated by the full item page; hydration must
+          // de-duplicate it while adding the omitted assistant response.
+          { turnId: "turn-early", item: earlyUser },
+          { turnId: "turn-early", item: assistantItem("early-agent", "first answer") },
+        ],
+        nextCursor: null,
+        backwardsCursor: null,
+      };
+    },
+  });
+  const events = [];
+  const adapter = new CodexAgentAdapter({ approvalTimeoutMs: 0 }, rpc);
+  adapter.onEvent((event) => events.push(event));
+  await adapter.start();
+  await adapter.selectSession({ threadId });
+
+  const resume = rpc.requests.find((entry) => entry.method === "thread/resume");
+  assert.deepEqual(resume.params, {
+    threadId,
+    excludeTurns: true,
+    initialTurnsPage: { limit: 100, sortDirection: "asc", itemsView: "full" },
+  });
+  const turnPages = rpc.requests.filter((entry) => entry.method === "thread/turns/list");
+  assert.deepEqual(turnPages.map((entry) => entry.params.cursor), ["turn-page-2", "turn-page-3"]);
+  assert.ok(turnPages.every((entry) => entry.params.threadId === threadId
+    && entry.params.limit === 100
+    && entry.params.sortDirection === "asc"
+    && entry.params.itemsView === "full"));
+  const itemPages = rpc.requests.filter((entry) => entry.method === "thread/items/list");
+  assert.deepEqual(itemPages.map((entry) => entry.params), [{
+    threadId,
+    turnId: "turn-early",
+    limit: 100,
+    sortDirection: "asc",
+  }]);
+  assert.equal(rpc.requests.some((entry) => entry.method === "thread/read"), false);
+
+  const snapshot = await adapter.snapshot();
+  assert.deepEqual(snapshot.messages.map((message) => [message.turnId, message.text]), [
+    ["turn-early", "first question"],
+    ["turn-early", "first answer"],
+    ["turn-middle", "second question"],
+    ["turn-middle", "second answer"],
+    ["turn-late", "third question"],
+    ["turn-late", "third answer"],
+  ]);
+  assert.equal(snapshot.metadata.historyComplete, true);
+  const outputSnapshot = events.find((event) => event.type === "output.snapshot");
+  assert.equal(outputSnapshot.payload.historyComplete, true);
+  assert.deepEqual(outputSnapshot.payload.messages.map((message) => message.text), [
+    "first question",
+    "first answer",
+    "second question",
+    "second answer",
+    "third question",
+    "third answer",
+  ]);
+  await adapter.dispose();
+});
+
+test("async adapter falls back to thread/read when resume omits existing history", async () => {
+  const metadataThread = {
+    id: "thread-paginated",
+    preview: "existing conversation",
+    cwd: "/tmp/project",
+    createdAt: 1_700_000_000,
+    updatedAt: 1_700_000_100,
+    status: { type: "idle" },
+    turns: [],
+  };
+  const rpc = new FakeRpc({
+    "model/list": { data: [], nextCursor: null },
+    "thread/resume": { thread: metadataThread, model: "gpt-5.6-sol", cwd: "/tmp/project" },
+    "thread/read": {
+      thread: {
+        ...metadataThread,
+        turns: [{
+          id: "turn-read",
+          status: "completed",
+          items: [{ type: "agentMessage", id: "read-agent", text: "hydrated history" }],
+        }],
+      },
+    },
+  });
+  const adapter = new CodexAgentAdapter({ approvalTimeoutMs: 0 }, rpc);
+  await adapter.start();
+  await adapter.selectSession({ threadId: "thread-paginated" });
+  const read = rpc.requests.find((entry) => entry.method === "thread/read");
+  assert.deepEqual(read.params, { threadId: "thread-paginated", includeTurns: true });
+  assert.equal((await adapter.snapshot()).messages[0].text, "hydrated history");
+  await adapter.dispose();
+});
+
+test("async adapter starts new sessions and sends flat durable thread settings", async () => {
+  const rpc = new FakeRpc({
+    "model/list": { data: [], nextCursor: null },
+    "thread/start": {
+      thread: { id: "thread-new", preview: "", cwd: "/tmp/new", status: { type: "idle" }, turns: [] },
+      model: "gpt-5.6-sol",
+      cwd: "/tmp/new",
+      reasoningEffort: "medium",
+    },
+    "thread/settings/update": { ok: true },
+  });
+  const adapter = new CodexAgentAdapter({ approvalTimeoutMs: 0, defaultCwd: "/tmp/default" }, rpc);
+  await adapter.start();
+  await adapter.newSession({});
+  await adapter.updateThreadSettings({
+    threadSettings: {
+      model: "gpt-5.6-terra",
+      effort: "high",
+      approvalPolicy: "on-request",
+      approvalsReviewer: "user",
+      sandboxPolicy: "workspace-write",
+      permissions: ":workspace",
+    },
+  });
+  const start = rpc.requests.find((entry) => entry.method === "thread/start");
+  assert.equal(start.params.cwd, "/tmp/default");
+  const update = rpc.requests.find((entry) => entry.method === "thread/settings/update");
+  assert.deepEqual(update.params, {
+    threadId: "thread-new",
+    model: "gpt-5.6-terra",
+    effort: "high",
+    approvalPolicy: "on-request",
+    approvalsReviewer: "user",
+    permissions: ":workspace",
+  });
+  assert.equal(Object.prototype.hasOwnProperty.call(update.params, "sandboxPolicy"), false);
+  const snapshot = await adapter.snapshot();
+  assert.equal(snapshot.metadata.model, "gpt-5.6-terra");
+  assert.equal(snapshot.metadata.latestReasoningEffort, "high");
+  assert.equal(snapshot.metadata.sandboxPolicy, "workspace-write");
+  await adapter.dispose();
+});
+
+test("thread settings updates require the send_task_input capability", async () => {
+  const rpc = new FakeRpc();
+  const adapter = new CodexAgentAdapter({ approvalTimeoutMs: 0 }, rpc);
+  await adapter.start();
+  const relay = new FakeRelay();
+  const host = new RelayHost({
+    adapter,
+    relay,
+    capabilities: ["read_output"],
+    sessionId: "test-session",
+  });
+
+  await host.handleFrame({
+    kind: "command",
+    type: "thread.settings.update",
+    commandId: "settings-without-capability",
+    actor: { role: "operator" },
+    payload: { threadSettings: { model: "gpt-5.6-sol", effort: "high" } },
+  });
+
+  const result = relay.frames.find((frame) => frame.payload?.commandId === "settings-without-capability");
+  assert.equal(result.type, "command.rejected");
+  assert.match(result.payload.error, /missing capability: send_task_input/);
+  await adapter.dispose();
+});
+
+test("RelayHost exposes session list as read-only and protects session selection", async () => {
+  const relay = new FakeRelay();
+  const calls = [];
+  const adapter = {
+    async start() {},
+    async sendInput() { return {}; },
+    async cancel() { return {}; },
+    async respondApproval() { return {}; },
+    async snapshot() { return { threadId: "thread-a", turnId: null, state: "idle", pendingApprovals: [], outputTail: "" }; },
+    onEvent() { return { dispose() {} }; },
+    async dispose() {},
+    async listSessions(params) {
+      calls.push({ method: "listSessions", params });
+      return { sessions: [{ threadId: "thread-a", title: "A", updatedAtMs: null, active: true, available: true }], activeThreadId: "thread-a" };
+    },
+    async selectSession(params) {
+      calls.push({ method: "selectSession", params });
+      return { threadId: params.threadId, previousThreadId: "thread-a", switched: true, available: true };
+    },
+    async newSession(params) {
+      calls.push({ method: "newSession", params });
+      return { opened: true, command: "chatgpt.newCodexPanel" };
+    },
+    getControlMode() { return "sync"; },
+    async setControlMode(params) {
+      calls.push({ method: "setControlMode", params });
+      return { changed: true, controlMode: params.mode, previousControlMode: "sync", modeEpoch: 1 };
+    },
+  };
+  const host = new RelayHost({
+    adapter,
+    relay,
+    capabilities: ["read_output", "send_task_input"],
+    sessionId: "test-session",
+  });
+
+  await host.handleFrame({ kind: "command", type: "session/list", commandId: "list-1", actor: { role: "viewer" }, payload: {} });
+  const listed = relay.frames.find((frame) => frame.payload?.commandId === "list-1");
+  assert.equal(listed.type, "command.accepted");
+  assert.equal(listed.payload.result.activeThreadId, "thread-a");
+  assert.equal(calls[0].method, "listSessions");
+
+  await host.handleFrame({ kind: "command", type: "session/select", commandId: "select-viewer", actor: { role: "viewer" }, payload: { threadId: "thread-b" } });
+  const denied = relay.frames.find((frame) => frame.payload?.commandId === "select-viewer");
+  assert.equal(denied.type, "command.rejected");
+
+  await host.handleFrame({ kind: "command", type: "session/select", commandId: "select-operator", actor: { role: "operator" }, payload: { threadId: "thread-b" } });
+  const selected = relay.frames.find((frame) => frame.payload?.commandId === "select-operator");
+  assert.equal(selected.type, "command.accepted");
+  assert.equal(selected.payload.result.threadId, "thread-b");
+  assert.equal(calls.at(-1).method, "selectSession");
+
+  await host.handleFrame({ kind: "command", type: "session/new", commandId: "new-viewer", actor: { role: "viewer" }, payload: {} });
+  const deniedNew = relay.frames.find((frame) => frame.payload?.commandId === "new-viewer");
+  assert.equal(deniedNew.type, "command.rejected");
+
+  await host.handleFrame({ kind: "command", type: "session/new", commandId: "new-operator", actor: { role: "operator" }, payload: {} });
+  const opened = relay.frames.find((frame) => frame.payload?.commandId === "new-operator");
+  assert.equal(opened.type, "command.accepted");
+  assert.equal(opened.payload.result.command, "chatgpt.newCodexPanel");
+  assert.equal(calls.at(-1).method, "newSession");
+
+  await host.handleFrame({ kind: "command", type: "control/mode/get", commandId: "mode-get-viewer", actor: { role: "viewer" }, payload: {} });
+  const mode = relay.frames.find((frame) => frame.payload?.commandId === "mode-get-viewer");
+  assert.equal(mode.type, "command.accepted");
+  assert.equal(mode.payload.result.mode, "sync");
+
+  await host.handleFrame({ kind: "command", type: "control/mode/set", commandId: "mode-set-viewer", actor: { role: "viewer" }, payload: { mode: "async" } });
+  const deniedMode = relay.frames.find((frame) => frame.payload?.commandId === "mode-set-viewer");
+  assert.equal(deniedMode.type, "command.rejected");
+
+  await host.handleFrame({ kind: "command", type: "control/mode/set", commandId: "mode-set-operator", actor: { role: "operator" }, payload: { mode: "async" } });
+  const changedMode = relay.frames.find((frame) => frame.payload?.commandId === "mode-set-operator");
+  assert.equal(changedMode.type, "command.accepted");
+  assert.equal(changedMode.payload.result.controlMode, "async");
+  assert.equal(calls.at(-1).method, "setControlMode");
+});
+
+test("approval decision conflicts and unknown tagged objects fail closed", async () => {
+  const rpc = new FakeRpc();
+  const adapter = new CodexAgentAdapter({ approvalTimeoutMs: 0 }, rpc);
+  await adapter.start();
+  const relay = new FakeRelay();
+  const host = new RelayHost({
+    adapter,
+    relay,
+    capabilities: ["read_output", "send_task_input", "cancel_task", "approve_low_risk"],
+    sessionId: "test-session",
+  });
+
+  rpc.emitRequest({
+    id: 3,
+    method: "execCommandApproval",
+    params: { conversationId: "thread-test", callId: "call-3", command: ["echo", "safe"] },
+  });
+  await host.handleFrame({
+    kind: "command",
+    type: "approval.respond",
+    commandId: "conflicting-response",
+    actor: { role: "operator" },
+    payload: {
+      requestId: 3,
+      decision: "deny",
+      response: { decision: "approved_mcp_policy_amendment" },
+    },
+  });
+  assert.deepEqual(rpc.responses[0], {
+    id: 3,
+    result: { decision: { denied: { rejection: "approval response implies allow, but decision is deny" } } },
+  });
+
+  rpc.emitRequest({
+    id: 4,
+    method: "item/commandExecution/requestApproval",
+    params: { threadId: "thread-test", turnId: "turn-test", itemId: "item-4", command: "echo safe" },
+  });
+  await host.handleFrame({
+    kind: "command",
+    type: "approval.respond",
+    commandId: "unknown-tagged-response",
+    actor: { role: "operator" },
+    payload: {
+      requestId: 4,
+      decision: "allow",
+      response: { decision: { futurePolicyGrant: { scope: "all" } } },
+    },
+  });
+  assert.deepEqual(rpc.responses[1], {
+    id: 4,
+    result: { decision: "decline" },
+  });
+  await adapter.dispose();
+});

aether-vscodex/test/cloud-server.test.js

@@ -0,0 +1,298 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const test = require("node:test");
+const { WebSocket } = require("ws");
+
+const { AetherVscodexCloudServer, RoomManager } = require("../cloud/server.js");
+
+const internalToken = "test-internal-token-with-enough-entropy";
+
+function internalFetch(base, pathname, options = {}) {
+  return fetch(`${base}${pathname}`, {
+    ...options,
+    headers: {
+      Authorization: `Bearer ${internalToken}`,
+      ...(options.body ? { "Content-Type": "application/json" } : {}),
+      ...(options.headers || {}),
+    },
+  });
+}
+
+function websocketClient(base, clientType, token, sessionId) {
+  const socket = new WebSocket(`${base.replace(/^http/, "ws")}/api/vscodex/ws`);
+  const messages = [];
+  const waiters = [];
+  const wait = (predicate, timeout = 5_000, label = "websocket frame") => new Promise((resolve, reject) => {
+    const existing = messages.find(predicate);
+    if (existing) return resolve(existing);
+    const timer = setTimeout(() => {
+      const index = waiters.findIndex((entry) => entry.resolve === resolve);
+      if (index >= 0) waiters.splice(index, 1);
+      reject(new Error(`timed out waiting for ${label}; received: ${JSON.stringify(messages.map((message) => ({ type: message.type, kind: message.kind, commandId: message.commandId })))}`));
+    }, timeout);
+    waiters.push({
+      predicate,
+      resolve: (message) => {
+        clearTimeout(timer);
+        resolve(message);
+      },
+    });
+  });
+  socket.on("message", (data) => {
+    const message = JSON.parse(data.toString("utf8"));
+    messages.push(message);
+    for (let index = waiters.length - 1; index >= 0; index -= 1) {
+      if (!waiters[index].predicate(message)) continue;
+      const waiter = waiters.splice(index, 1)[0];
+      waiter.resolve(message);
+    }
+  });
+  return new Promise((resolve, reject) => {
+    socket.once("open", () => {
+      socket.send(JSON.stringify({ v: 1, kind: "hello", clientType, protocol: 1, ...(sessionId ? { sessionId } : {}) }));
+      socket.send(JSON.stringify(clientType === "host"
+        ? { v: 1, kind: "auth", accessToken: token }
+        : { type: "auth", token }));
+      wait((message) => message.type === "auth.ok").then(() => resolve({ socket, wait, messages }), reject);
+    });
+    socket.once("error", reject);
+  });
+}
+
+async function pairDevice(base, userId, name) {
+  const pairingResponse = await internalFetch(base, `/internal/v1/users/${encodeURIComponent(userId)}/pairings`, {
+    method: "POST",
+    body: JSON.stringify({ name }),
+  });
+  assert.equal(pairingResponse.status, 201);
+  const pairing = await pairingResponse.json();
+  const exchangeResponse = await fetch(`${base}/v1/pairings/exchange`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ code: pairing.code, name }),
+  });
+  assert.equal(exchangeResponse.status, 201);
+  return exchangeResponse.json();
+}
+
+async function browserTicket(base, userId, deviceId) {
+  const response = await internalFetch(base, `/internal/v1/users/${encodeURIComponent(userId)}/ws-tickets`, {
+    method: "POST",
+    body: JSON.stringify({ device_id: deviceId }),
+  });
+  assert.equal(response.status, 201);
+  return response.json();
+}
+
+function exchangeAttempt(base, headers = {}) {
+  return fetch(`${base}/v1/pairings/exchange`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...headers },
+    body: JSON.stringify({ code: "INVALID-CODE" }),
+  });
+}
+
+test("pairing exchange trusts a gateway client IP only with valid internal authentication", async (t) => {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "aether-vscodex-rate-limit-"));
+  const server = new AetherVscodexCloudServer({
+    host: "127.0.0.1",
+    port: 0,
+    internalToken,
+    publicWsUrl: "wss://aether.example/api/vscodex/ws",
+    dataDir,
+  });
+  await server.start();
+  t.after(async () => {
+    await server.stop();
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  });
+  const address = server.address();
+  const base = `http://127.0.0.1:${address.port}`;
+  const trustedHeaders = (clientIp) => ({
+    Authorization: `Bearer ${internalToken}`,
+    "X-Aether-Client-IP": clientIp,
+  });
+
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    assert.equal((await exchangeAttempt(base, trustedHeaders("198.51.100.10"))).status, 400);
+  }
+  assert.equal((await exchangeAttempt(base, trustedHeaders("198.51.100.10"))).status, 429);
+  assert.equal((await exchangeAttempt(base, trustedHeaders("198.51.100.11"))).status, 400);
+  assert.equal((await exchangeAttempt(base, trustedHeaders("2001:db8::10"))).status, 400);
+
+  server.exchangeAttempts.clear();
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    assert.equal((await exchangeAttempt(base, { "X-Aether-Client-IP": `198.51.100.${20 + attempt}` })).status, 400);
+  }
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    assert.equal((await exchangeAttempt(base, {
+      Authorization: "Bearer invalid-internal-token",
+      "X-Aether-Client-IP": `198.51.100.${30 + attempt}`,
+    })).status, 400);
+  }
+  assert.equal((await exchangeAttempt(base, { "X-Aether-Client-IP": "198.51.100.99" })).status, 429);
+
+  server.exchangeAttempts.clear();
+  const invalidForwardedAddresses = ["proxy.internal", "198.51.100.40, 198.51.100.41"];
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    assert.equal((await exchangeAttempt(base, trustedHeaders(invalidForwardedAddresses[attempt % 2]))).status, 400);
+  }
+  assert.equal((await exchangeAttempt(base, trustedHeaders("198.51.100.42, 198.51.100.43"))).status, 429);
+});
+
+test("cloud sidecar pairs a device and isolates host/browser traffic by Aether user and device", async (t) => {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "aether-vscodex-test-"));
+  const server = new AetherVscodexCloudServer({
+    host: "127.0.0.1",
+    port: 0,
+    internalToken,
+    publicWsUrl: "wss://aether.example/api/vscodex/ws",
+    dataDir,
+    pairingTtlMs: 5_000,
+    ticketTtlMs: 5_000,
+  });
+  await server.start();
+  t.after(async () => {
+    await server.stop();
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  });
+  const address = server.address();
+  const base = `http://127.0.0.1:${address.port}`;
+
+  const unauthorized = await fetch(`${base}/internal/v1/users/user-a/devices`);
+  assert.equal(unauthorized.status, 401);
+
+  const paired = await pairDevice(base, "user-a", "MacBook VS Code");
+  assert.match(paired.device_token, /^avx1\./);
+  const devicesResponse = await internalFetch(base, "/internal/v1/users/user-a/devices");
+  assert.equal(devicesResponse.status, 200);
+  const devices = await devicesResponse.json();
+  assert.deepEqual(devices.devices.map((device) => ({ id: device.id, name: device.name, connected: device.connected })), [
+    { id: paired.device_id, name: "MacBook VS Code", connected: false },
+  ]);
+
+  const ticket = await browserTicket(base, "user-a", paired.device_id);
+  assert.equal(ticket.ws_url, "/api/vscodex/ws");
+  const host = await websocketClient(base, "host", paired.device_token, "host-user-a");
+  const browser = await websocketClient(base, "web", ticket.ticket);
+  t.after(() => host.socket.close());
+  t.after(() => browser.socket.close());
+  browser.socket.send(JSON.stringify({ type: "subscribe", fromSeq: 0 }));
+
+  host.socket.send(JSON.stringify({
+    v: 1,
+    kind: "event",
+    type: "connection.opened",
+    id: "connection-a",
+    sessionId: "host-user-a",
+    seq: 1,
+    ts: new Date().toISOString(),
+    payload: {},
+  }));
+  host.socket.send(JSON.stringify({
+    v: 1,
+    kind: "event",
+    type: "session.snapshot",
+    id: "snapshot-a",
+    sessionId: "host-user-a",
+    seq: 2,
+    ts: new Date().toISOString(),
+    payload: { threadId: "thread-a", state: "idle", messages: [{ kind: "assistant", text: "user-a-only" }] },
+  }));
+  const snapshot = await browser.wait((message) => message.kind === "event" && message.type === "session.snapshot", 5_000, "session snapshot");
+  assert.equal(snapshot.payload.threadId, "thread-a");
+  assert.equal(snapshot.payload.messages[0].text, "user-a-only");
+
+  browser.socket.send(JSON.stringify({ type: "command", commandId: "cmd-a", method: "session/list", params: {} }));
+  const command = await host.wait((message) => message.kind === "command" && message.commandId === "cmd-a", 5_000, "browser command");
+  assert.equal(command.type, "session/list");
+
+  const secondUser = await pairDevice(base, "user-b", "Other VS Code");
+  const secondTicket = await browserTicket(base, "user-b", secondUser.device_id);
+  const secondBrowser = await websocketClient(base, "web", secondTicket.ticket);
+  t.after(() => secondBrowser.socket.close());
+  secondBrowser.socket.send(JSON.stringify({ type: "subscribe", fromSeq: 0 }));
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  assert.equal(secondBrowser.messages.some((message) => message.payload?.threadId === "thread-a"), false);
+
+  const reusedTicket = new WebSocket(`${base.replace(/^http/, "ws")}/api/vscodex/ws`);
+  const closed = new Promise((resolve, reject) => {
+    reusedTicket.once("open", () => {
+      reusedTicket.send(JSON.stringify({ v: 1, kind: "hello", clientType: "web", protocol: 1 }));
+      reusedTicket.send(JSON.stringify({ type: "auth", token: ticket.ticket }));
+    });
+    reusedTicket.once("close", (code) => resolve(code));
+    reusedTicket.once("error", reject);
+  });
+  assert.equal(await closed, 1008, "browser tickets are one-time credentials");
+});
+
+test("device revocation closes its room and blocks future host authentication", async (t) => {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "aether-vscodex-revoke-"));
+  const server = new AetherVscodexCloudServer({
+    host: "127.0.0.1",
+    port: 0,
+    internalToken,
+    publicWsUrl: "wss://aether.example/api/vscodex/ws",
+    dataDir,
+  });
+  await server.start();
+  t.after(async () => {
+    await server.stop();
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  });
+  const address = server.address();
+  const base = `http://127.0.0.1:${address.port}`;
+  const paired = await pairDevice(base, "user-a", "Revoked device");
+  const host = await websocketClient(base, "host", paired.device_token, "revoked-host");
+
+  const response = await internalFetch(base, `/internal/v1/users/user-a/devices/${paired.device_id}`, { method: "DELETE" });
+  assert.equal(response.status, 204);
+  await new Promise((resolve) => host.socket.once("close", resolve));
+
+  const rejected = new WebSocket(`${base.replace(/^http/, "ws")}/api/vscodex/ws`);
+  const closed = new Promise((resolve, reject) => {
+    rejected.once("open", () => {
+      rejected.send(JSON.stringify({ v: 1, kind: "hello", clientType: "host", protocol: 1, sessionId: "retry" }));
+      rejected.send(JSON.stringify({ v: 1, kind: "auth", accessToken: paired.device_token }));
+    });
+    rejected.once("close", (code) => resolve(code));
+    rejected.once("error", reject);
+  });
+  assert.equal(await closed, 1008);
+});
+
+test("room revocation wins a concurrent room creation", async () => {
+  const rooms = new RoomManager();
+  let releaseCreation;
+  const creationGate = new Promise((resolve) => { releaseCreation = resolve; });
+  let stopped = false;
+  const room = {
+    key: rooms.key("user-a", "device-a"),
+    userId: "user-a",
+    deviceId: "device-a",
+    relay: { stop: async () => { stopped = true; } },
+    connections: 0,
+    lastActiveMs: Date.now(),
+  };
+  rooms.createRoom = async (key) => {
+    await creationGate;
+    rooms.rooms.set(key, room);
+    return room;
+  };
+
+  const pendingGet = rooms.get("user-a", "device-a");
+  await new Promise((resolve) => setImmediate(resolve));
+  const pendingRevoke = rooms.revoke("user-a", "device-a");
+  releaseCreation();
+
+  await assert.rejects(pendingGet, /device revoked/);
+  await pendingRevoke;
+  assert.equal(stopped, true);
+  assert.equal(rooms.rooms.has(room.key), false);
+  await assert.rejects(rooms.get("user-a", "device-a"), /device revoked/);
+});

aether-vscodex/test/codex-ipc.test.js

@@ -0,0 +1,209 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const net = require("node:net");
+const os = require("node:os");
+const path = require("node:path");
+const { mkdtempSync, rmSync } = require("node:fs");
+const test = require("node:test");
+
+const {
+  CODEX_IPC_METHOD_VERSIONS,
+  CodexIpcClient,
+  IpcFrameDecoder,
+  applyIpcPatches,
+  encodeIpcFrame,
+} = require("../vscode-extension/dist/codexIpc.js");
+
+function waitFor(predicate, timeoutMs = 2_000) {
+  const started = Date.now();
+  return new Promise((resolve, reject) => {
+    const poll = () => {
+      if (predicate()) return resolve();
+      if (Date.now() - started >= timeoutMs) return reject(new Error("timed out waiting for fixture"));
+      setTimeout(poll, 5);
+    };
+    poll();
+  });
+}
+
+test("private IPC framing handles split UTF-8 frames", () => {
+  const message = {
+    type: "broadcast",
+    method: "thread-stream-following-changed",
+    sourceClientId: "client-1",
+    version: 1,
+    params: { conversationId: "thread-1", hostId: "local", following: true, text: "中文" },
+  };
+  const frame = encodeIpcFrame(message);
+  const decoder = new IpcFrameDecoder();
+  const first = decoder.push(frame.subarray(0, 3));
+  assert.deepEqual(first, []);
+  const second = decoder.push(frame.subarray(3, frame.length - 1));
+  assert.deepEqual(second, []);
+  assert.deepEqual(decoder.push(frame.subarray(frame.length - 1)), [message]);
+});
+
+test("applyIpcPatches updates a conversation snapshot", () => {
+  const initial = { turns: [{ items: [{ text: "old" }] }], status: "idle" };
+  const next = applyIpcPatches(initial, [
+    { op: "replace", path: ["turns", 0, "items", 0, "text"], value: "new" },
+    { op: "add", path: ["turns", 0, "items", 1], value: { text: "second" } },
+    { op: "replace", path: ["status"], value: "active" },
+  ]);
+  assert.deepEqual(next, {
+    turns: [{ items: [{ text: "new" }, { text: "second" }] }],
+    status: "active",
+  });
+});
+
+test("fixture owner receives follow/start/steer/interrupt/approval requests", async () => {
+  const temp = mkdtempSync(path.join(os.tmpdir(), "codex-ipc-fixture-"));
+  const socketPath = path.join(temp, "ipc.sock");
+  const threadId = "11111111-1111-4111-8111-111111111111";
+  const ownerId = "owner-client";
+  const requests = [];
+  const followingBroadcasts = [];
+  let fixtureSocket;
+  const server = net.createServer((socket) => {
+    fixtureSocket = socket;
+    const decoder = new IpcFrameDecoder();
+    socket.on("data", (chunk) => {
+      for (const message of decoder.push(chunk)) {
+        if (message.type === "request" && message.method === "initialize") {
+          socket.write(encodeIpcFrame({
+            type: "response",
+            requestId: message.requestId,
+            resultType: "success",
+            method: "initialize",
+            handledByClientId: "fixture-client",
+            result: { clientId: "fixture-client" },
+          }));
+          continue;
+        }
+        if (message.type === "broadcast" && message.method === "thread-stream-following-changed") {
+          followingBroadcasts.push(message);
+          const target = message.sourceClientId;
+          socket.write(encodeIpcFrame({
+            type: "broadcast",
+            method: "thread-stream-state-changed",
+            sourceClientId: ownerId,
+            targetClientIds: [target],
+            version: CODEX_IPC_METHOD_VERSIONS["thread-stream-state-changed"],
+            params: {
+              conversationId: threadId,
+              hostId: "local",
+              change: {
+                type: "snapshot",
+                revision: 1,
+                conversationState: { id: threadId, title: "fixture", turns: [], requests: [] },
+              },
+            },
+          }));
+          continue;
+        }
+        if (message.type === "request") {
+          requests.push(message);
+          socket.write(encodeIpcFrame({
+            type: "response",
+            requestId: message.requestId,
+            resultType: "success",
+            method: message.method,
+            handledByClientId: ownerId,
+            result: { method: message.method, ok: true },
+          }));
+        }
+      }
+    });
+  });
+
+  try {
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(socketPath, resolve);
+    });
+    const client = new CodexIpcClient({ socketPath, autoReconnect: false });
+    const streamEvents = [];
+    client.onStreamEvent((event) => streamEvents.push(event));
+    await client.connect();
+    await client.followConversation(threadId);
+    await waitFor(() => streamEvents.some((event) => event.kind === "snapshot"));
+    assert.equal(client.getConversationState(threadId).ownerClientId, ownerId);
+    fixtureSocket.write(encodeIpcFrame({
+      type: "broadcast",
+      method: "thread-stream-following-status-requested",
+      sourceClientId: ownerId,
+      targetClientIds: ["fixture-client"],
+      version: CODEX_IPC_METHOD_VERSIONS["thread-stream-following-status-requested"],
+      params: { conversationId: threadId, hostId: "local" },
+    }));
+    await waitFor(() => followingBroadcasts.length >= 2);
+    assert.deepEqual(followingBroadcasts[1].targetClientIds, [ownerId]);
+    assert.deepEqual(followingBroadcasts[1].params, {
+      conversationId: threadId,
+      hostId: "local",
+      following: true,
+    });
+
+    await client.startTurn(threadId, "hello", { ownerClientId: ownerId });
+    await client.steerTurn(threadId, "follow-up", { ownerClientId: ownerId });
+    await client.updateThreadSettings(threadId, {
+      model: "gpt-5.6-sol",
+      effort: "ultra",
+      multiAgentMode: "explicitRequestOnly",
+    }, { ownerClientId: ownerId });
+    await client.interruptTurn(threadId, { mode: "user-stop", expectedTurnId: "turn-1", ownerClientId: ownerId });
+    await client.respondCommandApproval(threadId, 7, "decline", { ownerClientId: ownerId });
+    await client.respondFileApproval(threadId, "8", "cancel", { ownerClientId: ownerId });
+    await client.respondPermissionsApproval(threadId, 9, { permissions: {}, scope: "turn" }, { ownerClientId: ownerId });
+    await client.respondUserInput(threadId, 10, { answers: {} }, { ownerClientId: ownerId });
+    await client.respondMcpElicitation(threadId, 11, { action: "decline", content: null, _meta: null }, { ownerClientId: ownerId });
+
+    assert.deepEqual(requests.map((request) => request.method), [
+      "thread-follower-start-turn",
+      "thread-follower-steer-turn",
+      "thread-follower-update-thread-settings",
+      "thread-follower-interrupt-turn",
+      "thread-follower-command-approval-decision",
+      "thread-follower-file-approval-decision",
+      "thread-follower-permissions-request-approval-response",
+      "thread-follower-submit-user-input",
+      "thread-follower-submit-mcp-server-elicitation-response",
+    ]);
+    assert.deepEqual(requests[0].params, {
+      conversationId: threadId,
+      turnStart: {
+        request: {
+          threadId,
+          input: [{ type: "text", text: "hello", text_elements: [] }],
+        },
+        context: { inheritThreadSettings: true },
+      },
+    });
+    assert.deepEqual(requests[2].params, {
+      conversationId: threadId,
+      threadSettings: {
+        model: "gpt-5.6-sol",
+        effort: "ultra",
+        multiAgentMode: "explicitRequestOnly",
+      },
+    });
+    assert.equal(requests[2].version, 1);
+    assert.deepEqual(requests[3].params, {
+      conversationId: threadId,
+      mode: "user-stop",
+      expectedTurnId: "turn-1",
+    });
+    assert.equal(requests[3].version, 4);
+    assert.deepEqual(requests[4].params, { conversationId: threadId, requestId: 7, decision: "decline" });
+    assert.deepEqual(requests[8].params, {
+      conversationId: threadId,
+      requestId: 11,
+      response: { action: "decline", content: null, _meta: null },
+    });
+    await client.dispose();
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+    rmSync(temp, { recursive: true, force: true });
+  }
+});

aether-vscodex/test/codex-path.test.js

@@ -0,0 +1,57 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const { chmodSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const test = require("node:test");
+
+const { resolveCodexCommand } = require("../vscode-extension/dist/codexPath.js");
+const { JsonlRpcClient } = require("../vscode-extension/dist/jsonlRpc.js");
+
+function temporaryDirectory() {
+  return mkdtempSync(path.join(os.tmpdir(), "codex-remote-path-"));
+}
+
+test("resolveCodexCommand finds a bare command in PATH", () => {
+  const root = temporaryDirectory();
+  try {
+    const bin = path.join(root, "bin");
+    const executable = path.join(bin, "codex-test");
+    mkdirSync(bin);
+    writeFileSync(executable, "#!/bin/sh\nexit 0\n");
+    chmodSync(executable, 0o755);
+    assert.equal(resolveCodexCommand("codex-test", { env: { PATH: bin }, platform: process.platform }), executable);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("resolveCodexCommand falls back to a per-user ChatGPT.app install", () => {
+  const root = temporaryDirectory();
+  try {
+    const executable = path.join(root, "Applications", "ChatGPT.app", "Contents", "Resources", "codex");
+    mkdirSync(path.dirname(executable), { recursive: true });
+    writeFileSync(executable, "#!/bin/sh\nexit 0\n");
+    chmodSync(executable, 0o755);
+    assert.equal(
+      resolveCodexCommand("codex", { env: { PATH: "/usr/bin:/bin" }, homeDir: root, platform: "darwin" }),
+      executable,
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("a missing explicit command reports a full-path setting hint", () => {
+  assert.throws(
+    () => resolveCodexCommand("/definitely/missing/codex", { platform: process.platform }),
+    /Codex executable .* was not found.*codexRemoteCollab\.codexCommand.*full path/,
+  );
+});
+
+test("JsonlRpcClient turns spawn ENOENT into an actionable error", async () => {
+  const client = new JsonlRpcClient({ command: "/definitely/missing/codex", args: [] });
+  await assert.rejects(() => client.start(), /Codex executable .* was not found.*codexRemoteCollab\.codexCommand/);
+  client.close();
+});

aether-vscodex/test/composite-relay.test.js

@@ -0,0 +1,105 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const { CompositeRelayTransport } = require("../vscode-extension/dist/compositeRelay.js");
+
+class FakeRelay {
+  constructor({ connectError } = {}) {
+    this.connectError = connectError;
+    this.frames = [];
+    this.closed = false;
+    this.listeners = { message: new Set(), open: new Set(), close: new Set() };
+  }
+
+  async connect() {
+    if (this.connectError) throw this.connectError;
+    for (const listener of this.listeners.open) listener();
+  }
+
+  send(frame) { this.frames.push(frame); }
+  close() { this.closed = true; }
+  onMessage(listener) { return this.add("message", listener); }
+  onOpen(listener) { return this.add("open", listener); }
+  onClose(listener) { return this.add("close", listener); }
+  add(type, listener) {
+    this.listeners[type].add(listener);
+    return { dispose: () => this.listeners[type].delete(listener) };
+  }
+  receive(frame) { for (const listener of this.listeners.message) listener(frame); }
+  disconnect(error) { for (const listener of this.listeners.close) listener(error); }
+}
+
+test("CompositeRelayTransport keeps local control available when optional cloud connect fails", async () => {
+  const local = new FakeRelay();
+  const cloud = new FakeRelay({ connectError: new Error("cloud offline") });
+  const relay = new CompositeRelayTransport([
+    { id: "local", transport: local, required: true },
+    { id: "cloud", transport: cloud },
+  ]);
+
+  await relay.connect();
+  assert.equal(relay.isConnected("local"), true);
+  assert.equal(relay.isConnected("cloud"), false);
+  relay.send({ kind: "event", type: "session.snapshot" });
+  assert.equal(local.frames.length, 1);
+  assert.equal(cloud.frames.length, 1, "optional transport may queue events for reconnect");
+  relay.close();
+  assert.equal(local.closed, true);
+  assert.equal(cloud.closed, true);
+});
+
+test("CompositeRelayTransport forwards commands and reports offline only after every relay closes", async () => {
+  const local = new FakeRelay();
+  const cloud = new FakeRelay();
+  const relay = new CompositeRelayTransport([
+    { id: "local", transport: local, required: true },
+    { id: "cloud", transport: cloud },
+  ]);
+  const messages = [];
+  const closes = [];
+  relay.onMessage((frame) => messages.push(frame));
+  relay.onClose((error) => closes.push(error?.message));
+
+  await relay.connect();
+  assert.equal(relay.isConnected("local"), true);
+  assert.equal(relay.isConnected("cloud"), true);
+  cloud.receive({ kind: "command", type: "turn.start" });
+  assert.equal(messages.length, 1);
+  local.disconnect(new Error("local offline"));
+  assert.equal(relay.isConnected("local"), false);
+  assert.deepEqual(closes, []);
+  cloud.disconnect(new Error("cloud offline"));
+  assert.deepEqual(closes, ["cloud offline"]);
+  relay.close();
+});
+
+test("CompositeRelayTransport surfaces each member reconnect for snapshot hydration", async () => {
+  const local = new FakeRelay();
+  const cloud = new FakeRelay();
+  const relay = new CompositeRelayTransport([
+    { id: "local", transport: local, required: true },
+    { id: "cloud", transport: cloud },
+  ]);
+  let opens = 0;
+  relay.onOpen(() => { opens += 1; });
+  await relay.connect();
+  assert.equal(opens, 2);
+  cloud.disconnect(new Error("cloud offline"));
+  for (const listener of cloud.listeners.open) listener();
+  assert.equal(opens, 3, "cloud recovery must prompt RelayHost to publish a fresh snapshot");
+  relay.close();
+});
+
+test("CompositeRelayTransport fails when the required local relay cannot connect", async () => {
+  const local = new FakeRelay({ connectError: new Error("local offline") });
+  const cloud = new FakeRelay();
+  const relay = new CompositeRelayTransport([
+    { id: "local", transport: local, required: true },
+    { id: "cloud", transport: cloud },
+  ]);
+  await assert.rejects(relay.connect(), /local: local offline/);
+  assert.equal(local.closed, true);
+  assert.equal(cloud.closed, true);
+});

aether-vscodex/test/extension-i18n-build.test.js

@@ -0,0 +1,34 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const test = require("node:test");
+
+test("VS Code runtime strings have English and Simplified Chinese bundles", () => {
+  const extensionRoot = path.join(__dirname, "..", "vscode-extension");
+  const source = fs.readFileSync(path.join(extensionRoot, "src", "extension.ts"), "utf8");
+  const manifest = JSON.parse(fs.readFileSync(path.join(extensionRoot, "package.json"), "utf8"));
+  const english = JSON.parse(fs.readFileSync(path.join(extensionRoot, "l10n", "bundle.l10n.json"), "utf8"));
+  const chinese = JSON.parse(fs.readFileSync(path.join(extensionRoot, "l10n", "bundle.l10n.zh-cn.json"), "utf8"));
+  const keys = [...source.matchAll(/(?<![A-Za-z])t\("([^"]+)"/g)].map((match) => match[1]);
+
+  assert.equal(manifest.l10n, "./l10n");
+  assert.ok(keys.length > 20, "expected runtime-localized extension strings");
+  for (const key of new Set(keys)) {
+    assert.equal(english[key], key, `missing English source string: ${key}`);
+    assert.equal(typeof chinese[key], "string", `missing zh-CN translation: ${key}`);
+    assert.ok(chinese[key].length > 0, `empty zh-CN translation: ${key}`);
+  }
+});
+
+test("production copy scripts require the Vue build instead of silently falling back", () => {
+  const projectRoot = path.join(__dirname, "..");
+  const extensionSync = fs.readFileSync(path.join(projectRoot, "vscode-extension", "scripts", "sync-local-relay.cjs"), "utf8");
+  const aetherSync = fs.readFileSync(path.join(projectRoot, "..", "frontend", "scripts", "sync-vscodex.mjs"), "utf8");
+  const extensionManifest = JSON.parse(fs.readFileSync(path.join(projectRoot, "vscode-extension", "package.json"), "utf8"));
+
+  assert.match(extensionManifest.scripts["vscode:prepublish"], /build:web/);
+  assert.doesNotMatch(extensionSync, /projectRoot,\s*"public"/);
+  assert.doesNotMatch(aetherSync, /moduleRoot,\s*'public'/);
+});

aether-vscodex/test/local-relay.test.js

@@ -0,0 +1,120 @@
+const assert = require("node:assert/strict");
+const http = require("node:http");
+const path = require("node:path");
+const test = require("node:test");
+
+const {
+  LocalRelayController,
+  localRelayTarget,
+  relayHealthAvailable,
+} = require("../vscode-extension/dist/localRelay.js");
+
+test("local relay target accepts only loopback ws URLs", () => {
+  assert.deepEqual(localRelayTarget("ws://localhost:8898/v1/connect"), {
+    host: "127.0.0.1",
+    port: 8898,
+    healthUrl: "http://127.0.0.1:8898/api/health",
+    webUrl: "http://127.0.0.1:8898/",
+  });
+  assert.equal(localRelayTarget("wss://127.0.0.1:8898/v1/connect"), undefined);
+  assert.equal(localRelayTarget("ws://192.168.1.10:8898/v1/connect"), undefined);
+  assert.equal(localRelayTarget("not a url"), undefined);
+});
+
+test("local relay health probe recognizes a responding HTTP service", async (t) => {
+  const server = http.createServer((request, response) => {
+    if (request.url === "/api/health") {
+      response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ ok: true }));
+    } else if (request.url === "/aborted") {
+      response.writeHead(200, { "content-type": "application/json" });
+      response.write('{"ok":');
+      response.destroy();
+    } else if (request.url === "/drip") {
+      response.writeHead(200, { "content-type": "application/json" });
+      const interval = setInterval(() => response.write(" "), 10);
+      response.on("close", () => clearInterval(interval));
+    } else {
+      response.writeHead(404).end();
+    }
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  t.after(() => new Promise((resolve) => server.close(resolve)));
+  const address = server.address();
+  assert.equal(await relayHealthAvailable(`http://127.0.0.1:${address.port}/api/health`), true);
+  assert.equal(await relayHealthAvailable(`http://127.0.0.1:${address.port}/missing`), false);
+  assert.equal(await relayHealthAvailable(`http://127.0.0.1:${address.port}/aborted`, 100), false);
+  const startedAt = Date.now();
+  assert.equal(await relayHealthAvailable(`http://127.0.0.1:${address.port}/drip`, 50), false);
+  assert.ok(Date.now() - startedAt < 500);
+});
+
+test("local relay controller starts and stops a bundled loopback relay", async () => {
+  let starts = 0;
+  let stops = 0;
+  class FakeRelay {
+    async start() { starts += 1; return { host: "127.0.0.1", port: 65534 }; }
+    async stop() { stops += 1; }
+  }
+  const controller = new LocalRelayController({
+    extensionPath: path.resolve(__dirname, "../vscode-extension"),
+    probeTimeoutMs: 20,
+    loadRelayModule: () => ({ CodexRelay: FakeRelay }),
+  });
+  assert.equal(await controller.ensureRunning("ws://127.0.0.1:65534/v1/connect"), true);
+  assert.equal(starts, 1);
+  await controller.stop();
+  assert.equal(stops, 1);
+});
+
+test("local relay controller does not leak a relay when stopped during startup", async () => {
+  let releaseStart;
+  const startGate = new Promise((resolve) => { releaseStart = resolve; });
+  let startEntered;
+  const entered = new Promise((resolve) => { startEntered = resolve; });
+  let stops = 0;
+  class SlowRelay {
+    async start() {
+      startEntered();
+      await startGate;
+      return { host: "127.0.0.1", port: 65533 };
+    }
+    async stop() { stops += 1; }
+  }
+  const controller = new LocalRelayController({
+    extensionPath: path.resolve(__dirname, "../vscode-extension"),
+    probeTimeoutMs: 20,
+    loadRelayModule: () => ({ CodexRelay: SlowRelay }),
+  });
+  const starting = controller.ensureRunning("ws://127.0.0.1:65533/v1/connect");
+  await entered;
+  const stopping = controller.stop();
+  releaseStart();
+  await Promise.all([starting, stopping]);
+  assert.equal(stops, 1);
+});
+
+test("local relay controller does not start after stop wins an in-flight health probe", async () => {
+  let resolveProbe;
+  const probe = new Promise((resolve) => { resolveProbe = resolve; });
+  let probeEntered;
+  const entered = new Promise((resolve) => { probeEntered = resolve; });
+  let starts = 0;
+  class FakeRelay {
+    async start() { starts += 1; return { host: "127.0.0.1", port: 65532 }; }
+    async stop() {}
+  }
+  const controller = new LocalRelayController({
+    extensionPath: path.resolve(__dirname, "../vscode-extension"),
+    loadRelayModule: () => ({ CodexRelay: FakeRelay }),
+    probeRelayHealth: async () => {
+      probeEntered();
+      return probe;
+    },
+  });
+  const ensuring = controller.ensureRunning("ws://127.0.0.1:65532/v1/connect");
+  await entered;
+  await controller.stop();
+  resolveProbe(false);
+  assert.equal(await ensuring, false);
+  assert.equal(starts, 0);
+});

aether-vscodex/test/public-embed-i18n.test.js

@@ -0,0 +1,194 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const test = require("node:test");
+
+const { createAetherEmbedBridge, isAetherEmbed } = require("../public/embed-bridge.js");
+const i18n = require("../public/i18n.js");
+
+function embeddedWindow() {
+  const listeners = new Map();
+  const posts = [];
+  const parent = { postMessage: (message, origin) => posts.push({ message, origin }) };
+  const bodyClasses = new Set();
+  const documentElement = { dataset: {}, style: {} };
+  const windowLike = {
+    location: { search: "?embed=aether", origin: "https://aether.example" },
+    parent,
+    document: {
+      body: { classList: { add: (value) => bodyClasses.add(value) } },
+      documentElement,
+    },
+    addEventListener: (name, listener) => listeners.set(name, listener),
+    removeEventListener: (name, listener) => {
+      if (listeners.get(name) === listener) listeners.delete(name);
+    },
+  };
+  return { bodyClasses, documentElement, listeners, parent, posts, windowLike };
+}
+
+test("Aether embed mode is opt-in and announces readiness only to the same-origin parent", () => {
+  assert.equal(isAetherEmbed({ search: "" }), false);
+  assert.equal(isAetherEmbed({ search: "?embed=other" }), false);
+  assert.equal(isAetherEmbed({ search: "?embed=aether" }), true);
+
+  const fixture = embeddedWindow();
+  const bridge = createAetherEmbedBridge(fixture.windowLike);
+  assert.equal(bridge.active, true);
+  bridge.start();
+  assert.equal(fixture.bodyClasses.has("embed-aether"), true);
+  assert.deepEqual(fixture.posts, [{
+    message: { v: 1, type: "aether-vscodex/ready" },
+    origin: "https://aether.example",
+  }]);
+});
+
+test("Aether embed bridge rejects cross-origin and non-parent messages and buffers an early connect", () => {
+  const fixture = embeddedWindow();
+  const bridge = createAetherEmbedBridge(fixture.windowLike);
+  bridge.start();
+  const dispatch = fixture.listeners.get("message");
+  const connect = {
+    v: 1,
+    type: "aether-vscodex/connect",
+    ticket: "one-time-ticket",
+    wsUrl: "/api/vscodex/ws",
+    locale: "en-US",
+    theme: "dark",
+  };
+
+  dispatch({ origin: "https://attacker.example", source: fixture.parent, data: connect });
+  dispatch({ origin: "https://aether.example", source: {}, data: connect });
+  let received = null;
+  bridge.on("connect", (message) => { received = message; });
+  assert.equal(received, null);
+
+  dispatch({ origin: "https://aether.example", source: fixture.parent, data: connect });
+  assert.equal(received.ticket, "one-time-ticket");
+  assert.equal(fixture.documentElement.dataset.theme, "dark");
+
+  const second = embeddedWindow();
+  const bufferedBridge = createAetherEmbedBridge(second.windowLike);
+  bufferedBridge.start();
+  second.listeners.get("message")({ origin: "https://aether.example", source: second.parent, data: connect });
+  let buffered = null;
+  bufferedBridge.on("connect", (message) => { buffered = message; });
+  assert.equal(buffered.ticket, "one-time-ticket");
+});
+
+test("bridge ticket requests never place the ticket in a URL", () => {
+  const fixture = embeddedWindow();
+  const bridge = createAetherEmbedBridge(fixture.windowLike);
+  bridge.start();
+  bridge.requestTicket({ reason: "disconnected", deviceId: "device-1" });
+  assert.deepEqual(fixture.posts.at(-1), {
+    message: {
+      v: 1,
+      type: "aether-vscodex/request-ticket",
+      reason: "disconnected",
+      deviceId: "device-1",
+    },
+    origin: "https://aether.example",
+  });
+});
+
+test("locale dictionary covers static shell and core dynamic status text", () => {
+  assert.equal(i18n.translate("设置", "en-US"), "Settings");
+  assert.equal(i18n.translate("中文", "en-US"), "Chinese");
+  assert.equal(i18n.translate("正在思考", "en-US"), "Thinking");
+  assert.equal(i18n.translate("已读取这些内容 · 4 个文件", "en-US"), "Read these items · 4 files");
+  assert.equal(i18n.translate("用时 3分45秒", "en-US"), "Worked for 3m45s");
+  assert.equal(i18n.translate("修改权限，当前为需要时询问", "en-US"), "Change permissions. Current: Ask when needed");
+  assert.equal(i18n.translate("模型设置更新失败：timeout", "en-US"), "Unable to update model settings: timeout");
+  assert.equal(i18n.translate("请求 #17 已发送，等待 VS Code 主机确认", "en-US"), "Request #17 sent; waiting for the VS Code host");
+  assert.equal(i18n.translate("无法读取 notes.md", "en-US"), "Unable to read notes.md");
+  assert.equal(i18n.translate("命令: timed out", "en-US"), "Command: timed out");
+  assert.equal(i18n.translate("命令: timed out（执行状态未知，请等待主机恢复）", "en-US"), "Command: timed out (execution status unknown; wait for the host to recover)");
+  assert.equal(i18n.translate("子代理 失败", "en-US"), "Subagent failed");
+  assert.equal(i18n.translate("已在 2秒 内运行 echo hi", "en-US"), "Ran echo hi in 2s");
+  assert.equal(i18n.translate("命令运行失败 · echo hi · 2秒", "en-US"), "Command failed · echo hi · 2s");
+  assert.equal(i18n.translate("命令运行失败 · echo hi", "en-US"), "Command failed · echo hi");
+  assert.equal(i18n.translate("已停止 echo hi · 2秒", "en-US"), "Stopped echo hi · 2s");
+  assert.equal(i18n.translate("文件变更 · 失败", "en-US"), "File changes · Failed");
+  assert.equal(i18n.translate("文件变更 · 已中断", "en-US"), "File changes · Interrupted");
+  assert.equal(i18n.translate("命令 · echo hi", "en-US"), "Command · echo hi");
+  assert.equal(i18n.translate("命令 · 设置", "en-US"), "Command · 设置");
+  assert.equal(i18n.translate("正在读取 设置", "en-US"), "Reading 设置");
+  assert.equal(i18n.translate("已在 2秒 内运行 设置", "en-US"), "Ran 设置 in 2s");
+  assert.equal(i18n.translate("正在切换到「设置」…", "en-US"), "Switching to “设置”...");
+  assert.equal(i18n.translate("你停止了工作", "en-US"), "You stopped working");
+  assert.equal(i18n.translate("工具失败", "en-US"), "Tool failed");
+  assert.equal(i18n.translate("正在搜索", "en-US"), "Searching");
+  assert.equal(i18n.translate("已工具 · 2秒", "en-US"), "Tool completed · 2s");
+  assert.equal(i18n.translate("当前模型 5.6 Sol 标准，切换模型", "en-US"), "Current model: 5.6 Sol Medium. Change model");
+  assert.equal(i18n.translate("编辑了文件", "en-US"), "Edited files");
+  assert.equal(i18n.translate("编辑了文件 · 2秒", "en-US"), "Edited files · 2s");
+  assert.equal(i18n.translate("已完成计划", "en-US"), "Completed plan");
+  assert.equal(i18n.translate("已完成计划 · 2秒", "en-US"), "Completed plan · 2s");
+  assert.equal(i18n.translate("…（文件已截断）", "en-US"), "... (file truncated)");
+  assert.equal(i18n.translate("事件窗口已过期，请以当前快照为准", "en-US"), "The event window expired; the current snapshot is authoritative");
+  assert.equal(i18n.translate("控制模式", "en-US"), "Control mode");
+  assert.equal(i18n.translate("同步模式跟随 VS Code 当前会话", "en-US"), "Sync mode follows the current VS Code conversation");
+  assert.equal(i18n.translate("异步模式可独立管理会话", "en-US"), "Async mode manages conversations independently");
+  assert.equal(i18n.translate("当前任务或请求完成后才能切换控制模式", "en-US"), "The control mode can be changed after the current task or request finishes");
+  assert.equal(i18n.translate("Settings", "zh-CN"), "设置");
+  assert.equal(i18n.normalizeLocale("zh-Hans"), "zh-CN");
+  assert.equal(i18n.normalizeLocale("en-GB"), "en-US");
+});
+
+test("renderer-owned dynamic labels have English fallbacks without translating host values", () => {
+  assert.equal(i18n.translate("命令 · echo hi", "en-US"), "Command · echo hi");
+  assert.equal(i18n.translate("你停止了工作", "en-US"), "You stopped working");
+  assert.equal(i18n.translate("工具失败", "en-US"), "Tool failed");
+  assert.equal(i18n.translate("正在搜索", "en-US"), "Searching");
+  assert.equal(i18n.translate("当前模型 5.6 Sol 标准，切换模型", "en-US"), "Current model: 5.6 Sol Medium. Change model");
+
+  const app = fs.readFileSync(path.join(__dirname, "..", "public", "app.js"), "utf8");
+  // Command/path/title values are appended after a locale-specific prefix;
+  // they are never passed through the translator as a whole.
+  assert.match(app, /uiWithRaw\("正在运行 ", "Running ",/);
+  assert.match(app, /uiWithRaw\("已读取 ", "Read ",/);
+  assert.match(app, /uiLocale\(\) === "en-US" \? `Switching to/);
+});
+
+test("public shell uses relative assets and embedded startup skips the health probe", () => {
+  const publicRoot = path.join(__dirname, "..", "public");
+  const html = fs.readFileSync(path.join(publicRoot, "index.html"), "utf8");
+  const app = fs.readFileSync(path.join(publicRoot, "app.js"), "utf8");
+  assert.match(html, /href="\.\/style\.css"/);
+  assert.match(html, /src="\.\/embed-bridge\.js"/);
+  assert.match(html, /src="\.\/i18n\.js"/);
+  assert.match(html, /src="\.\/app\.js"/);
+  assert.match(app, /if \(embeddedInAether\)[\s\S]+else \{[\s\S]+fetch\("\.\/api\/health"/);
+  assert.doesNotMatch(app, /ticket=.*state\.embedTicket/);
+  assert.match(app, /empty\.textContent = t\(activity\.status === "inProgress" \? "正在读取文件" : "读取完成"\)/);
+  assert.match(app, /outputContent\.textContent = t\("无输出"\)/);
+  assert.match(app, /button\.title = t\(title\)/);
+  assert.match(app, /activity\.action === "spawnAgent" \? t\("启动子代理"\)/);
+  assert.match(app, /return t\("需要远程确认或输入"\)/);
+  assert.match(app, /questionPrompt === undefined \|\| questionPrompt === null \? t\("请输入"\)/);
+  assert.match(app, /checkbox\.setAttribute\("aria-label", t\(checkbox\.checked \? "已完成" : "未完成"\)\)/);
+  assert.match(app, /window\.addEventListener\("aether-vscodex:locale", \(\) => \{[\s\S]+state\.activities\.values\(\)[\s\S]+renderRequests\(\)/);
+});
+
+test("control mode is snapshot-authoritative and gates independent session actions", () => {
+  const publicRoot = path.join(__dirname, "..", "public");
+  const html = fs.readFileSync(path.join(publicRoot, "index.html"), "utf8");
+  const app = fs.readFileSync(path.join(publicRoot, "app.js"), "utf8");
+
+  assert.match(html, /id="controlModeSwitch"[\s\S]+data-control-mode="sync"[\s\S]+data-control-mode="async"/);
+  assert.match(app, /command\("control\/mode\/set", \{ mode \}\)/);
+  assert.match(app, /applyControlModeSnapshot\(payload\.metadata\)/);
+  assert.match(app, /const controlMetadata = \{[\s\S]+snapshot\.metadata[\s\S]+appState\.sessionMetadata[\s\S]+applyControlModeSnapshot\(controlMetadata\)/);
+  assert.match(app, /sessionList: source\.sessionList === true/);
+  assert.match(app, /Boolean\(state\.sessionListCommandId\)/);
+  assert.match(app, /mode_switch_pending.*return "正在切换控制模式"/);
+  assert.match(app, /mode_busy\|cannot switch control mode.*return "当前任务或请求完成后才能切换控制模式"/);
+  assert.match(app, /setConversationStatus\(sessionErrorMessage\(message, "控制模式切换失败"\), "warning"\)/);
+  assert.match(app, /if \(!sessionControlAllowed\("sessionList"\)\) return;/);
+  assert.match(app, /if \(!sessionControlAllowed\("sessionSelect"\)\)/);
+  assert.match(app, /if \(!sessionControlAllowed\("sessionCreate"\)\)/);
+  assert.match(app, /sessionPickerButton\.disabled = !listAllowed/);
+});

aether-vscodex/test/relay-client.test.js

@@ -0,0 +1,206 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const { EventEmitter } = require("node:events");
+const test = require("node:test");
+
+const { RelayClient } = require("../vscode-extension/dist/relayClient.js");
+
+class FakeWebSocket extends EventEmitter {
+  static instances = [];
+
+  constructor(url) {
+    super();
+    this.url = url;
+    this.readyState = 0;
+    this.sent = [];
+    FakeWebSocket.instances.push(this);
+  }
+
+  open() {
+    this.readyState = 1;
+    this.emit("open");
+  }
+
+  receive(frame) {
+    this.emit("message", Buffer.from(JSON.stringify(frame)));
+  }
+
+  send(data) {
+    this.sent.push(JSON.parse(data));
+  }
+
+  close() {
+    if (this.readyState === 3) return;
+    this.readyState = 3;
+    this.emit("close");
+  }
+}
+
+test("RelayClient queues application frames until auth.ok on initial connect and reconnect", async (t) => {
+  FakeWebSocket.instances.length = 0;
+  const client = new RelayClient({
+    url: "ws://relay.invalid/v1/connect",
+    accessToken: "host-token",
+    reconnect: false,
+    webSocket: FakeWebSocket,
+  });
+  t.after(() => client.close());
+
+  const firstConnect = client.connect();
+  const first = FakeWebSocket.instances[0];
+  first.open();
+  assert.deepEqual(first.sent.map((frame) => frame.kind), ["hello", "auth"]);
+
+  client.send({ v: 1, kind: "event", type: "output.chunk", id: "event-1", sessionId: "session-1", payload: { text: "queued" } });
+  assert.equal(first.sent.length, 2, "application event must not be sent before authentication");
+  first.receive({ type: "auth.ok", role: "host", clientType: "host" });
+  await firstConnect;
+  assert.equal(first.sent.length, 3);
+  assert.equal(first.sent[2].id, "event-1");
+
+  first.close();
+  const secondConnect = client.connect();
+  const second = FakeWebSocket.instances[1];
+  second.open();
+  assert.deepEqual(second.sent.map((frame) => frame.kind), ["hello", "auth"]);
+
+  client.send({ v: 1, kind: "event", type: "output.chunk", id: "event-2", sessionId: "session-1", payload: { text: "queued during reconnect" } });
+  assert.equal(second.sent.length, 2, "reconnect window must remain auth-gated");
+  second.receive({ type: "auth.ok", role: "host", clientType: "host" });
+  await secondConnect;
+  assert.equal(second.sent.length, 3);
+  assert.equal(second.sent[2].id, "event-2");
+});
+
+test("RelayClient coalesces queued transcript projections within a byte budget", async (t) => {
+  FakeWebSocket.instances.length = 0;
+  const client = new RelayClient({
+    url: "ws://relay.invalid/v1/connect",
+    accessToken: "host-token",
+    reconnect: false,
+    maxFrameBytes: 4_096,
+    maxQueuedBytes: 4_096,
+    webSocket: FakeWebSocket,
+  });
+  t.after(() => client.close());
+
+  const connecting = client.connect();
+  const socket = FakeWebSocket.instances[0];
+  socket.open();
+  client.send({ v: 1, kind: "event", type: "approval.requested", id: "approval", sessionId: "session-1", payload: { text: "a".repeat(700) } });
+  client.send({ v: 1, kind: "event", type: "output.snapshot", id: "old-projection", sessionId: "session-1", payload: { text: "x".repeat(1_200) } });
+  client.send({ v: 1, kind: "event", type: "output.chunk", id: "new-projection", sessionId: "session-1", payload: { text: "y".repeat(1_200) } });
+  client.send({ v: 1, kind: "event", type: "command.result", id: "command", sessionId: "session-1", payload: { text: "c".repeat(700) } });
+
+  assert.ok(client.queueBytes <= 4_096);
+  socket.receive({ type: "auth.ok", role: "host", clientType: "host" });
+  await connecting;
+  const queuedIds = socket.sent.slice(2).map((frame) => frame.id);
+  assert.deepEqual(queuedIds, ["approval", "new-projection", "command"]);
+});
+
+test("RelayClient evicts reconstructible projections before queued control events", async (t) => {
+  FakeWebSocket.instances.length = 0;
+  const client = new RelayClient({
+    url: "ws://relay.invalid/v1/connect",
+    accessToken: "host-token",
+    reconnect: false,
+    maxFrameBytes: 4_096,
+    maxQueuedBytes: 2_500,
+    webSocket: FakeWebSocket,
+  });
+  t.after(() => client.close());
+
+  const connecting = client.connect();
+  const socket = FakeWebSocket.instances[0];
+  socket.open();
+  client.send({ v: 1, kind: "event", type: "approval.requested", id: "approval", sessionId: "session-1", payload: { text: "a".repeat(850) } });
+  client.send({ v: 1, kind: "event", type: "output.chunk", id: "projection", sessionId: "session-1", payload: { text: "x".repeat(900) } });
+  client.send({ v: 1, kind: "event", type: "command.result", id: "command", sessionId: "session-1", payload: { text: "c".repeat(850) } });
+
+  assert.ok(client.queueBytes <= 2_500);
+  socket.receive({ type: "auth.ok", role: "host", clientType: "host" });
+  await connecting;
+  const queuedIds = socket.sent.slice(2).map((frame) => frame.id);
+  assert.deepEqual(queuedIds, ["approval", "command"]);
+});
+
+test("RelayClient supports a tokenless local handshake", async (t) => {
+  FakeWebSocket.instances.length = 0;
+  const client = new RelayClient({
+    url: "ws://127.0.0.1:8787/v1/connect",
+    reconnect: false,
+    webSocket: FakeWebSocket,
+  });
+  t.after(() => client.close());
+
+  const connecting = client.connect();
+  const socket = FakeWebSocket.instances[0];
+  socket.open();
+  assert.deepEqual(socket.sent.map((frame) => frame.kind), ["hello"]);
+  socket.receive({ type: "auth.ok", role: "host", clientType: "host", authRequired: false });
+  await connecting;
+
+  client.send({ v: 1, kind: "event", type: "connection.opened", id: "event-local", sessionId: "session-local", payload: {} });
+  assert.equal(socket.sent.length, 2);
+  assert.equal(socket.sent[1].type, "connection.opened");
+});
+
+test("RelayClient accepts structured history snapshots larger than the old 256 KiB limit", async (t) => {
+  FakeWebSocket.instances.length = 0;
+  const client = new RelayClient({
+    url: "ws://127.0.0.1:8787/v1/connect",
+    reconnect: false,
+    webSocket: FakeWebSocket,
+  });
+  t.after(() => client.close());
+
+  const connecting = client.connect();
+  const socket = FakeWebSocket.instances[0];
+  socket.open();
+  socket.receive({ type: "auth.ok", role: "host", clientType: "host", authRequired: false });
+  await connecting;
+
+  const historyText = "x".repeat(512 * 1024);
+  assert.doesNotThrow(() => client.send({
+    v: 1,
+    kind: "event",
+    type: "session.snapshot",
+    id: "large-history-snapshot",
+    sessionId: "session-local",
+    payload: { threadId: "large-thread", messages: [{ kind: "assistant", text: historyText }] },
+  }));
+  assert.equal(socket.sent.at(-1).payload.messages[0].text.length, historyText.length);
+});
+
+test("RelayClient ignores late events from a replaced socket", async (t) => {
+  FakeWebSocket.instances.length = 0;
+  const client = new RelayClient({
+    url: "ws://relay.invalid/v1/connect",
+    accessToken: "host-token",
+    reconnect: false,
+    webSocket: FakeWebSocket,
+  });
+  t.after(() => client.close());
+
+  const firstConnect = client.connect();
+  const first = FakeWebSocket.instances[0];
+  first.open();
+  client.close();
+
+  const secondConnect = client.connect();
+  const second = FakeWebSocket.instances[1];
+  second.open();
+
+  // Simulate a delayed event from the old socket after the replacement.
+  first.open();
+  first.receive({ type: "auth.ok", role: "host", clientType: "host" });
+  assert.equal(second.sent.length, 2, "late auth must not authenticate or flush the new socket");
+
+  client.send({ v: 1, kind: "event", type: "output.chunk", id: "event-after-replace", sessionId: "session-1", payload: { text: "queued" } });
+  second.receive({ type: "auth.ok", role: "host", clientType: "host" });
+  await secondConnect;
+  assert.equal(second.sent[2].id, "event-after-replace");
+  await assert.rejects(firstConnect);
+});

aether-vscodex/test/switchable-agent-adapter.test.js

@@ -0,0 +1,387 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const { SwitchableAgentAdapter } = require("../vscode-extension/dist/switchableAgentAdapter.js");
+
+class FakeAdapter {
+  constructor(name, options = {}) {
+    this.name = name;
+    this.options = options;
+    this.listeners = new Set();
+    this.calls = [];
+    this.disposed = false;
+    this.snapshotValue = options.snapshot ?? idleSnapshot(name);
+  }
+
+  async start() {
+    this.calls.push(["start"]);
+    this.emit({ type: "candidate.starting", payload: { name: this.name } });
+    if (this.options.startGate) await this.options.startGate.promise;
+    if (this.options.startError) throw this.options.startError;
+    this.emit({ type: "connection.opened", payload: { name: this.name } });
+  }
+
+  async startThread(params = {}) { return this.record("startThread", params); }
+  async newSession(params = {}) { return this.record("newSession", params); }
+  async startTurn(params) { return this.record("startTurn", params); }
+  async steerTurn(params) { return this.record("steerTurn", params); }
+  async updateThreadSettings(params) { return this.record("updateThreadSettings", params); }
+  async listSessions(params = {}) { return this.record("listSessions", params); }
+  async selectSession(params) { return this.record("selectSession", params); }
+  async interruptTurn(params) { return this.record("interruptTurn", params); }
+  async sendInput(text, params = {}) { return this.record("sendInput", { text, ...params }); }
+  async cancel(taskId, params = {}) { return this.record("cancel", { taskId, ...params }); }
+  async respondApproval(requestId, decision, reason, response) {
+    return this.record("respondApproval", { requestId, decision, reason, response });
+  }
+  async denyPending(reason) { this.calls.push(["denyPending", reason]); }
+
+  async snapshot() {
+    this.calls.push(["snapshot"]);
+    return structuredClone(this.snapshotValue);
+  }
+
+  onEvent(listener) {
+    this.listeners.add(listener);
+    return { dispose: () => this.listeners.delete(listener) };
+  }
+
+  emit(event) {
+    for (const listener of this.listeners) listener(event);
+  }
+
+  async dispose() {
+    this.calls.push(["dispose"]);
+    this.disposed = true;
+  }
+
+  record(method, params) {
+    this.calls.push([method, params]);
+    return { adapter: this.name, method, params };
+  }
+}
+
+function idleSnapshot(name) {
+  return {
+    threadId: `${name}-thread`,
+    turnId: null,
+    state: "idle",
+    pendingApprovals: [],
+    pendingRequests: [],
+    outputTail: "",
+    metadata: { adapter: name },
+  };
+}
+
+function deferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+  return { promise, resolve, reject };
+}
+
+test("sync mode decorates snapshots and enforces VS Code-owned navigation", async () => {
+  const sync = new FakeAdapter("sync");
+  const adapter = new SwitchableAgentAdapter({ initialMode: "sync", createAdapter: () => sync });
+  await adapter.start();
+
+  const snapshot = await adapter.snapshot();
+  assert.equal(snapshot.metadata.adapter, "sync");
+  assert.equal(snapshot.metadata.mode, "sync");
+  assert.equal(snapshot.metadata.controlMode, "sync");
+  assert.equal(snapshot.metadata.modeEpoch, 0);
+  assert.deepEqual(snapshot.metadata.capabilities, {
+    followsVscodeRoute: true,
+    sessionList: false,
+    sessionSelect: false,
+    sessionCreate: false,
+    threadSettings: true,
+  });
+
+  await assert.rejects(adapter.listSessions(), /unavailable in sync mode/);
+  await assert.rejects(adapter.selectSession({ threadId: "other" }), /unavailable in sync mode/);
+  await assert.rejects(adapter.newSession(), /unavailable in sync mode/);
+  await assert.rejects(adapter.startThread(), /unavailable in sync mode/);
+  assert.equal((await adapter.sendInput("hello")).adapter, "sync");
+  assert.equal((await adapter.updateThreadSettings({ model: "codex" })).adapter, "sync");
+  await adapter.dispose();
+});
+
+test("async mode proxies the complete AgentAdapter surface", async () => {
+  const independent = new FakeAdapter("async");
+  const adapter = new SwitchableAgentAdapter({ initialMode: "async", createAdapter: () => independent });
+  await adapter.start();
+
+  await adapter.startThread({ cwd: "/workspace" });
+  await adapter.newSession({ model: "codex" });
+  await adapter.startTurn({ text: "start" });
+  await adapter.steerTurn({ text: "steer" });
+  await adapter.updateThreadSettings({ effort: "high" });
+  await adapter.listSessions({ limit: 10 });
+  await adapter.selectSession({ threadId: "thread-2" });
+  await adapter.interruptTurn({ turnId: "turn-1" });
+  await adapter.sendInput("input", { source: "web" });
+  await adapter.cancel("turn-2", { reason: "user" });
+  await adapter.respondApproval(7, "allow", "approved", { decision: "accept" });
+  await adapter.denyPending("offline");
+
+  assert.deepEqual(
+    independent.calls.map(([method]) => method).filter((method) => !["start", "snapshot", "dispose"].includes(method)),
+    [
+      "startThread",
+      "newSession",
+      "startTurn",
+      "steerTurn",
+      "updateThreadSettings",
+      "listSessions",
+      "selectSession",
+      "interruptTurn",
+      "sendInput",
+      "cancel",
+      "respondApproval",
+      "denyPending",
+    ],
+  );
+  await adapter.dispose();
+});
+
+test("session/new falls back to thread/start for a minimal async adapter", async () => {
+  const independent = new FakeAdapter("async");
+  independent.newSession = undefined;
+  const adapter = new SwitchableAgentAdapter({ initialMode: "async", createAdapter: () => independent });
+  await adapter.start();
+
+  const result = await adapter.newSession({ cwd: "/workspace" });
+  assert.equal(result.method, "startThread");
+  assert.equal((await adapter.snapshot()).metadata.capabilities.sessionCreate, true);
+  await adapter.dispose();
+});
+
+test("mode switch commits atomically, buffers candidate events, and isolates the old generation", async () => {
+  const sync = new FakeAdapter("sync");
+  const gate = deferred();
+  const asyncAdapter = new FakeAdapter("async", { startGate: gate });
+  const adapter = new SwitchableAgentAdapter({
+    initialMode: "sync",
+    createAdapter: (mode) => mode === "sync" ? sync : asyncAdapter,
+  });
+  const events = [];
+  adapter.onEvent((event) => events.push(`${event.type}:${event.payload.name ?? event.payload.controlMode ?? ""}`));
+  await adapter.start();
+  events.length = 0;
+
+  const switching = adapter.setControlMode({ mode: "async" });
+  await Promise.resolve();
+  sync.emit({ type: "old.while-current", payload: { name: "sync" } });
+  assert.deepEqual(events, ["old.while-current:sync"]);
+  await assert.rejects(adapter.sendInput("racing input"), /mode is switching/);
+  gate.resolve();
+
+  const result = await switching;
+  assert.deepEqual(result, {
+    changed: true,
+    controlMode: "async",
+    previousControlMode: "sync",
+    modeEpoch: 1,
+  });
+  assert.equal(sync.disposed, true);
+  assert.equal(adapter.getControlMode(), "async");
+  assert.ok(events.indexOf("control.mode.changed:async") < events.indexOf("candidate.starting:async"));
+  assert.ok(events.includes("connection.opened:async"));
+
+  sync.emit({ type: "old.after-commit", payload: { name: "sync" } });
+  asyncAdapter.emit({ type: "new.after-commit", payload: { name: "async" } });
+  assert.equal(events.includes("old.after-commit:sync"), false);
+  assert.equal(events.includes("new.after-commit:async"), true);
+
+  const snapshot = await adapter.snapshot();
+  assert.equal(snapshot.metadata.modeEpoch, 1);
+  assert.deepEqual(snapshot.metadata.capabilities, {
+    followsVscodeRoute: false,
+    sessionList: true,
+    sessionSelect: true,
+    sessionCreate: true,
+    threadSettings: true,
+  });
+  assert.equal((await adapter.listSessions()).adapter, "async");
+  assert.equal((await adapter.newSession()).adapter, "async");
+  await adapter.dispose();
+});
+
+test("delegate snapshot events always carry authoritative mode metadata", async () => {
+  const sync = new FakeAdapter("sync");
+  const asyncAdapter = new FakeAdapter("async");
+  const adapter = new SwitchableAgentAdapter({
+    initialMode: "sync",
+    createAdapter: (mode) => mode === "sync" ? sync : asyncAdapter,
+  });
+  const snapshots = [];
+  adapter.onEvent((event) => {
+    if (event.type === "session.snapshot") snapshots.push(event.payload);
+  });
+  await adapter.start();
+
+  sync.emit({
+    type: "session.snapshot",
+    threadId: "sync-thread-2",
+    payload: { threadId: "sync-thread-2", metadata: { adapter: "sync", route: "/thread/2" } },
+  });
+  assert.deepEqual(snapshots.at(-1).metadata, {
+    adapter: "sync",
+    route: "/thread/2",
+    mode: "sync",
+    controlMode: "sync",
+    modeEpoch: 0,
+    capabilities: {
+      followsVscodeRoute: true,
+      sessionList: false,
+      sessionSelect: false,
+      sessionCreate: false,
+      threadSettings: true,
+    },
+  });
+
+  await adapter.setControlMode({ mode: "async" });
+  snapshots.length = 0;
+  asyncAdapter.emit({
+    type: "session.snapshot",
+    threadId: "async-thread-2",
+    payload: { threadId: "async-thread-2", metadata: { adapter: "async", title: "Second" } },
+  });
+  assert.equal(snapshots.length, 1);
+  assert.equal(snapshots[0].metadata.adapter, "async");
+  assert.equal(snapshots[0].metadata.title, "Second");
+  assert.equal(snapshots[0].metadata.controlMode, "async");
+  assert.equal(snapshots[0].metadata.modeEpoch, 1);
+  assert.equal(snapshots[0].metadata.capabilities.followsVscodeRoute, false);
+  assert.equal(snapshots[0].metadata.capabilities.sessionSelect, true);
+  await adapter.dispose();
+});
+
+test("active turns and pending requests prevent a mode switch", async (t) => {
+  const cases = [
+    ["active turn", { ...idleSnapshot("sync"), turnId: "turn-1", state: "active" }],
+    ["active state before a turn id arrives", { ...idleSnapshot("sync"), state: "in_progress" }],
+    ["active runtime flag", { ...idleSnapshot("sync"), activeFlags: ["thinking"] }],
+    ["pending approval", {
+      ...idleSnapshot("sync"),
+      pendingApprovals: [{ requestId: 1, method: "approval", action: "run", risk: "low", summary: "run", createdAt: 1, payload: {} }],
+    }],
+    ["pending input", {
+      ...idleSnapshot("sync"),
+      pendingRequests: [{ requestId: "input-1", method: "item/tool/requestUserInput" }],
+    }],
+  ];
+
+  for (const [name, snapshot] of cases) {
+    await t.test(name, async () => {
+      const sync = new FakeAdapter("sync", { snapshot });
+      let factoryCalls = 0;
+      const adapter = new SwitchableAgentAdapter({
+        initialMode: "sync",
+        createAdapter: (mode) => {
+          factoryCalls += 1;
+          return mode === "sync" ? sync : new FakeAdapter("async");
+        },
+      });
+      await adapter.start();
+      await assert.rejects(adapter.setControlMode({ mode: "async" }), /turn or request is active/);
+      assert.equal(factoryCalls, 1, "busy checks happen before creating a second adapter");
+      assert.equal(adapter.getControlMode(), "sync");
+      await adapter.dispose();
+    });
+  }
+});
+
+test("candidate startup failure leaves the old adapter authoritative", async () => {
+  const sync = new FakeAdapter("sync");
+  const failed = new FakeAdapter("async", { startError: new Error("candidate failed") });
+  const adapter = new SwitchableAgentAdapter({
+    initialMode: "sync",
+    createAdapter: (mode) => mode === "sync" ? sync : failed,
+  });
+  const events = [];
+  adapter.onEvent((event) => events.push(event.type));
+  await adapter.start();
+  events.length = 0;
+
+  await assert.rejects(adapter.setControlMode({ controlMode: "async" }), /candidate failed/);
+  assert.equal(adapter.getControlMode(), "sync");
+  assert.equal(failed.disposed, true);
+  assert.equal(sync.disposed, false);
+  assert.equal(events.includes("candidate.starting"), false, "failed candidate events stay private");
+  assert.equal((await adapter.sendInput("still attached")).adapter, "sync");
+  assert.equal((await adapter.snapshot()).metadata.modeEpoch, 0);
+  await adapter.dispose();
+});
+
+test("a mode factory cannot reuse the currently active adapter instance", async () => {
+  const shared = new FakeAdapter("shared");
+  const adapter = new SwitchableAgentAdapter({ initialMode: "sync", createAdapter: () => shared });
+  await adapter.start();
+
+  await assert.rejects(adapter.setControlMode({ mode: "async" }), /must return a distinct adapter/);
+  assert.equal(adapter.getControlMode(), "sync");
+  assert.equal(shared.disposed, false);
+  assert.equal((await adapter.sendInput("still live")).adapter, "shared");
+  await adapter.dispose();
+});
+
+test("listener failures cannot turn a committed switch into a rejected command", async () => {
+  const sync = new FakeAdapter("sync");
+  const asyncAdapter = new FakeAdapter("async");
+  const adapter = new SwitchableAgentAdapter({
+    initialMode: "sync",
+    createAdapter: (mode) => mode === "sync" ? sync : asyncAdapter,
+  });
+  adapter.onEvent(() => { throw new Error("consumer failed"); });
+  await adapter.start();
+
+  const result = await adapter.setControlMode({ mode: "async" });
+  assert.equal(result.changed, true);
+  assert.equal(adapter.getControlMode(), "async");
+  assert.equal(sync.disposed, true);
+  await adapter.dispose();
+});
+
+test("a turn that appears while the candidate starts aborts before commit", async () => {
+  const sync = new FakeAdapter("sync");
+  const gate = deferred();
+  const candidate = new FakeAdapter("async", { startGate: gate });
+  const adapter = new SwitchableAgentAdapter({
+    initialMode: "sync",
+    createAdapter: (mode) => mode === "sync" ? sync : candidate,
+  });
+  await adapter.start();
+
+  const switching = adapter.setControlMode({ mode: "async" });
+  await Promise.resolve();
+  sync.snapshotValue.turnId = "turn-race";
+  sync.snapshotValue.state = "active";
+  gate.resolve();
+
+  await assert.rejects(switching, /turn or request is active/);
+  assert.equal(adapter.getControlMode(), "sync");
+  assert.equal(candidate.disposed, true);
+  assert.equal(sync.disposed, false);
+  sync.snapshotValue.turnId = null;
+  sync.snapshotValue.state = "idle";
+  await adapter.dispose();
+});
+
+test("control mode validation and idempotent switches are explicit", async () => {
+  const sync = new FakeAdapter("sync");
+  const adapter = new SwitchableAgentAdapter({ initialMode: "sync", createAdapter: () => sync });
+  await adapter.start();
+
+  await assert.rejects(adapter.setControlMode({ mode: "attach" }), /must be sync or async/);
+  assert.deepEqual(await adapter.setControlMode({ mode: "sync" }), {
+    changed: false,
+    controlMode: "sync",
+    previousControlMode: "sync",
+    modeEpoch: 0,
+  });
+  await adapter.dispose();
+});

aether-vscodex/vscode-extension/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+*.vsix

aether-vscodex/vscode-extension/.vscodeignore

@@ -0,0 +1,9 @@
+src/**
+.gitignore
+tsconfig.json
+**/*.map
+node_modules/@types/**
+node_modules/typescript/**
+node_modules/.package-lock.json
+*.tsbuildinfo
+*.vsix

aether-vscodex/vscode-extension/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codex Remote Collaboration contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aether-vscodex/vscode-extension/README.md

@@ -0,0 +1,237 @@
+# Codex Remote Collaboration VS Code Bridge
+
+This extension connects local and Aether relay channels to one switchable Codex
+control host. **Synchronous mode** follows the conversation currently shown by
+the official Codex VS Code extension through its private IPC protocol and does
+not spawn a `codex` process. **Asynchronous mode** starts an independent
+app-server and lets the Web UI list, resume, create, and select conversations.
+
+The attached conversation remains visible and usable in the official Codex
+panel. Remote operators can observe its output, submit a new turn or steer the
+active turn, interrupt it, and answer supported approval/input requests.
+
+The mode can be changed from the Web UI without reconnecting either relay.
+Synchronous mode makes the official panel the only conversation-navigation
+owner; asynchronous mode restores the browser history and new-conversation
+actions. A running turn or pending request blocks mode changes.
+
+## Requirements
+
+- The official `openai.chatgpt` VS Code extension is installed and signed in.
+- The target Codex conversation is open and owned by that extension.
+- The bridge and official extension run as the same OS user. The default Unix
+  socket is `$CODEX_HOME/ipc/ipc.sock`, normally `~/.codex/ipc/ipc.sock`.
+- For a loopback `ws://` URL, the extension starts and owns its bundled relay
+  automatically. Remote and `wss://` relay URLs remain externally hosted.
+
+The IPC follower protocol is private and versioned, not a public OpenAI API.
+An official extension update can require a compatible bridge update. Strict
+stream-version checks are enabled by default so an unknown protocol fails
+closed instead of being interpreted optimistically.
+
+## Build and install
+
+```sh
+npm install
+npm run check
+npm run build
+npx --yes @vscode/vsce package
+code --install-extension codex-remote-collab-0.4.0.vsix --force
+```
+
+Run **Developer: Reload Window** after installing or replacing the VSIX.
+
+## Configure control modes
+
+For the local default, no separate relay command is required. The extension
+starts the bundled relay on the host and port from `codexRemoteCollab.localRelayUrl`.
+To run the development relay manually, disable
+`codexRemoteCollab.autoStartLocalRelay` and use:
+
+```sh
+HOST=127.0.0.1 PORT=8787 CODEX_REMOTE_MODE=host npm start
+```
+
+To opt into authentication later, set `CODEX_REMOTE_AUTH=required` and the three
+token variables before starting the relay.
+
+Set the extension configuration:
+
+```json
+{
+  "codexRemoteCollab.localRelayUrl": "ws://127.0.0.1:8787/v1/connect",
+  "codexRemoteCollab.controlMode": "sync",
+  "codexRemoteCollab.autoDiscoverThread": true,
+  "codexRemoteCollab.autoStart": true
+}
+```
+
+Then:
+
+1. Open the target conversation in the official Codex panel.
+2. Reload VS Code once after installing the companion extension. The local relay and bridge start automatically; no token is needed for loopback. The status item opens the Web console and is not a connect/disconnect toggle.
+3. Open the relay web console; it connects automatically on localhost. The web UI uses a
+   Codex-style conversation stream with a bottom composer; Enter sends and Shift+Enter
+   inserts a newline. There is no separate connect/disconnect step for the local relay.
+
+If the browser says that it is waiting for the VS Code host or the recent-session list is
+empty, verify that `codexRemoteCollab.localRelayUrl` uses the same port as the relay and run
+**Developer: Reload Window**. Keep `codexRemoteCollab.threadId` empty unless a specific
+conversation must be pinned; an old closed ID can prevent startup until it is cleared.
+
+When authentication is enabled, run **Codex Remote: Set Relay Token** with the
+host token. It is stored in `vscode.SecretStorage`, not in settings; the browser
+uses the operator or viewer token separately.
+
+With no configured thread ID, the bridge ranks recent VS Code rollout metadata
+and shows only candidates verified by live IPC owner discovery and a matching
+follower snapshot. Explicit Codex Desktop tasks, closed, stale, and other
+non-attachable history entries are omitted.
+In synchronous mode, switching the conversation in the official Codex panel
+also switches the Web projection after the new owner snapshot is ready. The
+Web UI cannot list, select, or create conversations in this mode. Switch to
+asynchronous mode when the browser should own conversation navigation.
+To avoid ambiguity when several Codex windows are open, run **Codex Remote: Set Existing Thread ID**.
+An empty value restores automatic discovery.
+
+Useful commands:
+
+- **Codex Remote: Start Bridge** / **Stop Bridge**
+- **Codex Remote: Set Existing Thread ID**
+- **Codex Remote: Set Relay Token**
+- **Codex Remote: Pair with Aether**
+- **Codex Remote: Configure Aether Cloud Relay**
+- **Codex Remote: Send Input**
+- **Codex Remote: Show Snapshot**
+
+## Settings
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `codexRemoteCollab.controlMode` | `sync` | `sync` follows VS Code; `async` owns an independent app-server. |
+| `codexRemoteCollab.localRelayUrl` | `ws://127.0.0.1:8787/v1/connect` | Bundled loopback relay used by the local Web control. |
+| `codexRemoteCollab.aetherUrl` | empty | Aether origin remembered by the pairing command. |
+| `codexRemoteCollab.cloudRelayUrl` | empty | Aether WebSocket relay URL populated by pairing. |
+| `codexRemoteCollab.threadId` | empty | Exact existing conversation ID; empty enables discovery. |
+| `codexRemoteCollab.autoDiscoverThread` | `true` | Discover and owner-check a local VS Code session. |
+| `codexRemoteCollab.followVscodeSession` | `true` | Legacy compatibility setting; synchronous mode always follows VS Code. |
+| `codexRemoteCollab.ipcSocketPath` | empty | Override the local IPC socket path. |
+| `codexRemoteCollab.hostId` | `local` | Owner-discovery host identifier. |
+| `codexRemoteCollab.ipcStrictVersions` | `true` | Reject unsupported stream protocol versions. |
+| `codexRemoteCollab.approvalTimeoutMs` | `300000` | Deny an unanswered request locally after this delay. |
+| `codexRemoteCollab.allowHighRiskApprovals` | `false` | Permit remote high-risk approvals when explicitly enabled. |
+
+`codexRemoteCollab.codexCommand`, `codexArgs`, and `defaultCwd` apply only to
+asynchronous mode. The deprecated `mode=attach/spawn` values map to
+`controlMode=sync/async` when no explicit control mode exists.
+
+## Pair with Aether
+
+The local relay stays enabled after cloud pairing. In Aether, open **Codex remote
+control** and generate a one-time code. Then run **Codex Remote: Pair with Aether**
+from the VS Code Command Palette, enter the Aether server URL and the code, and
+the bridge will connect to both relays. The long-lived device credential is stored
+only in VS Code SecretStorage. Revoke a lost or retired device from the Aether page.
+
+## Relay behavior
+
+The bridge sends a `hello` and, when a relay token is configured, a separate
+bearer-auth frame over an outbound WebSocket. It publishes normalized events including:
+
+- `connection.opened` / `connection.closed`
+- `session.snapshot`
+- `output.snapshot` / `output.chunk`
+- `task.started` / `task.finished` / `task.cancelled`
+- `approval.requested` / `approval.resolved` / `approval.expired`
+- `input.requested` / `input.resolved` / `input.expired`
+
+Remote commands are mapped to the existing conversation owner:
+
+- `control/mode/set` atomically switches between `sync` and `async`.
+- `session/list`, `session/select`, and `session/new` are available only in
+  asynchronous mode and map to `thread/list`, `thread/resume`, and `thread/start`.
+- `turn/start` starts a turn in the attached thread.
+- `turn/steer` adds input to the active turn.
+- `turn/interrupt` interrupts the expected active turn.
+- `approval.respond`, `input.respond`, and `server.request.respond` preserve the
+  original request ID and use method-specific follower responses.
+- `thread/start` is deliberately rejected in synchronous mode because VS Code
+  owns conversation navigation there.
+
+The browser never connects directly to the IPC socket. Relay and host both
+enforce role/capability checks; high-risk command approval remains disabled
+unless the local VS Code setting opts in.
+
+## Supported follower requests
+
+- `item/commandExecution/requestApproval`
+- `item/fileChange/requestApproval`
+- `item/permissions/requestApproval`
+- `item/tool/requestUserInput`
+- `mcpServer/elicitation/request`
+- legacy `applyPatchApproval` and `execCommandApproval`
+
+Unanswered requests expire with a local deny. JSON-RPC numeric and string IDs
+remain distinct, and a response can be submitted only once.
+
+## Legacy mode migration
+
+The old setting remains accepted:
+
+```json
+{
+  "codexRemoteCollab.mode": "spawn",
+  "codexRemoteCollab.codexCommand": "/absolute/path/to/codex",
+  "codexRemoteCollab.codexArgs": ["app-server", "--stdio"]
+}
+```
+
+It maps to `controlMode=async`. Prefer the new setting directly. A
+`spawn codex ENOENT` error belongs only to asynchronous mode; it is not a
+synchronous-mode prerequisite or a PATH problem that needs fixing for
+existing-session control.
+
+The standalone `npm run start:stdio` entry point and `createBridge()` helper
+also retain the legacy app-server adapter for compatibility.
+
+## Embedding the attach adapter
+
+The reusable exports are in `src/index.ts`:
+
+```ts
+import {
+  CodexIpcAgentAdapter,
+  RelayClient,
+  RelayHost,
+} from "codex-remote-collab";
+
+const adapter = new CodexIpcAgentAdapter({
+  threadId: process.env.CODEX_THREAD_ID,
+  autoDiscoverThread: true,
+});
+const relay = new RelayClient({
+  url: "wss://relay.example.test/v1/connect",
+  accessToken: process.env.CODEX_REMOTE_HOST_TOKEN,
+});
+const host = new RelayHost({ adapter, relay });
+await host.start();
+```
+
+`CodexIpcClient` is exported separately for protocol fixtures and diagnostics.
+Use `followConversation()` before follower mutations, and always target the
+owner returned by `findThreadOwner()`.
+
+## Troubleshooting
+
+- **No existing session found:** open the target official Codex conversation,
+  keep that VS Code window running, then retry or set its exact thread ID.
+- **Owner not found:** the rollout exists on disk but no live official client
+  currently owns it. Reopen the conversation in the Codex panel.
+- **IPC version mismatch:** update this bridge for the installed official
+  extension. Disabling strict versions is diagnostic only.
+- **Relay stays at waiting for host:** confirm host mode, relay URL, and that no
+  second host is already connected. If authentication is enabled, also check the
+  host token.
+- **Old `spawn codex ENOENT` message:** install version `0.4.0`, reload VS Code,
+  and verify `codexRemoteCollab.controlMode` is `sync` unless independent
+  conversations are intended.

aether-vscodex/vscode-extension/l10n/bundle.l10n.json

@@ -0,0 +1,56 @@
+{
+  "A non-empty Aether device credential is required.": "A non-empty Aether device credential is required.",
+  "Aether cloud connection removed. Local control remains enabled.": "Aether cloud connection removed. Local control remains enabled.",
+  "Aether cloud connection saved. Restart the Codex Remote bridge to connect; local control remains available.": "Aether cloud connection saved. Restart the Codex Remote bridge to connect; local control remains available.",
+  "Aether cloud relay WebSocket URL": "Aether cloud relay WebSocket URL",
+  "Aether pairing completed. Local and cloud control are both active.": "Aether pairing completed. Local and cloud control are both active.",
+  "Aether pairing was saved, but the cloud connection is currently unavailable. Local control remains active and the cloud connection will retry.": "Aether pairing was saved, but the cloud connection is currently unavailable. Local control remains active and the cloud connection will retry.",
+  "Aether returned an invalid pairing response.": "Aether returned an invalid pairing response.",
+  "Aether server URL": "Aether server URL",
+  "Attached to the existing Codex conversation. Click to open the web control.": "Attached to the existing Codex conversation. Click to open the web control.",
+  "Bridge connected. Click to open the web control.": "Bridge connected. Click to open the web control.",
+  "Bridge paused. Click to open the web control and resume automatically.": "Bridge paused. Click to open the web control and resume automatically.",
+  "Codex Remote Collaboration": "Codex Remote Collaboration",
+  "Codex Remote will attach to {0} after the next bridge start.": "Codex Remote will attach to {0} after the next bridge start.",
+  "Codex Remote will auto-discover the latest VS Code Codex conversation after the next bridge start.": "Codex Remote will auto-discover the latest VS Code Codex conversation after the next bridge start.",
+  "Connecting to the local Codex collaboration service": "Connecting to the local Codex collaboration service",
+  "Device credential from the Aether pairing flow": "Device credential from the Aether pairing flow",
+  "Enter a valid URL.": "Enter a valid URL.",
+  "Enter a valid WebSocket URL.": "Enter a valid WebSocket URL.",
+  "Enter the 8-character pairing code.": "Enter the 8-character pairing code.",
+  "Enter the Aether server URL.": "Enter the Aether server URL.",
+  "Existing Codex conversation ID (leave blank for auto-discovery)": "Existing Codex conversation ID (leave blank for auto-discovery)",
+  "Independent Codex mode is connected. Click to open the web control.": "Independent Codex mode is connected. Click to open the web control.",
+  "One-time pairing code shown in Aether": "One-time pairing code shown in Aether",
+  "Relay access token (leave blank for the local relay)": "Relay access token (leave blank for the local relay)",
+  "Relay token stored in VS Code SecretStorage.": "Relay token stored in VS Code SecretStorage.",
+  "Remote Aether connections must use wss://.": "Remote Aether connections must use wss://.",
+  "Remote Aether servers must use https://.": "Remote Aether servers must use https://.",
+  "Restoring the local collaboration service": "Restoring the local collaboration service",
+  "Send input to the active Codex turn": "Send input to the active Codex turn",
+  "Set codexRemoteCollab.localRelayUrl before starting the bridge.": "Set codexRemoteCollab.localRelayUrl before starting the bridge.",
+  "Start the Codex remote bridge first.": "Start the Codex remote bridge first.",
+  "Starting the independent Codex mode.": "Starting the independent Codex mode.",
+  "Starting {0}": "Starting {0}",
+  "The Codex conversation is not connected": "The Codex conversation is not connected",
+  "The Codex executable is unavailable": "The Codex executable is unavailable",
+  "The Codex remote bridge attached to the existing VS Code Codex conversation.": "The Codex remote bridge attached to the existing VS Code Codex conversation.",
+  "The Codex remote bridge is already running.": "The Codex remote bridge is already running.",
+  "The Codex remote collaboration bridge connected.": "The Codex remote collaboration bridge connected.",
+  "The independent Codex mode is not connected": "The independent Codex mode is not connected",
+  "The independent Codex remote mode connected.": "The independent Codex remote mode connected.",
+  "The bridge is not connected": "The bridge is not connected",
+  "The local collaboration URL is invalid. Check codexRemoteCollab.localRelayUrl.": "The local collaboration URL is invalid. Check codexRemoteCollab.localRelayUrl.",
+  "The local collaboration service at {0} is temporarily unavailable. The extension will keep retrying.": "The local collaboration service at {0} is temporarily unavailable. The extension will keep retrying.",
+  "The official Codex extension new-conversation command was not found. Make sure the VS Code Codex extension is enabled.": "The official Codex extension new-conversation command was not found. Make sure the VS Code Codex extension is enabled.",
+  "Unable to pair with Aether: {0}": "Unable to pair with Aether: {0}",
+  "Unable to restore the local collaboration service": "Unable to restore the local collaboration service",
+  "Unable to send Codex input: {0}": "Unable to send Codex input: {0}",
+  "Unable to start the Codex remote bridge: {0}": "Unable to start the Codex remote bridge: {0}",
+  "Unable to start the local Codex collaboration service: {0}": "Unable to start the local Codex collaboration service: {0}",
+  "Unable to start the local collaboration service: {0}": "Unable to start the local collaboration service: {0}",
+  "Use a ws:// or wss:// URL.": "Use a ws:// or wss:// URL.",
+  "Use the Aether origin without credentials, a query, or a fragment.": "Use the Aether origin without credentials, a query, or a fragment.",
+  "Waiting for a Codex conversation to open in VS Code. It will connect automatically.": "Waiting for a Codex conversation to open in VS Code. It will connect automatically.",
+  "codexRemoteCollab.localRelayUrl must be a loopback ws:// address.": "codexRemoteCollab.localRelayUrl must be a loopback ws:// address."
+}

aether-vscodex/vscode-extension/l10n/bundle.l10n.zh-cn.json

@@ -0,0 +1,56 @@
+{
+  "A non-empty Aether device credential is required.": "必须填写 Aether 设备凭据。",
+  "Aether cloud connection removed. Local control remains enabled.": "已移除 Aether 云端连接，本地控制仍然可用。",
+  "Aether cloud connection saved. Restart the Codex Remote bridge to connect; local control remains available.": "已保存 Aether 云端连接。重启 Codex Remote 桥接后即可连接，本地控制仍然可用。",
+  "Aether cloud relay WebSocket URL": "Aether 云端 relay WebSocket 地址",
+  "Aether pairing completed. Local and cloud control are both active.": "Aether 配对完成，本地与云端控制均已启用。",
+  "Aether pairing was saved, but the cloud connection is currently unavailable. Local control remains active and the cloud connection will retry.": "Aether 配对信息已保存，但当前无法连接云端。本地控制仍然可用，云端连接会继续重试。",
+  "Aether returned an invalid pairing response.": "Aether 返回了无效的配对响应。",
+  "Aether server URL": "Aether 服务器地址",
+  "Attached to the existing Codex conversation. Click to open the web control.": "已附加到现有 Codex 会话，点击打开 Web 控制页。",
+  "Bridge connected. Click to open the web control.": "桥接已连接，点击打开 Web 控制页。",
+  "Bridge paused. Click to open the web control and resume automatically.": "桥接已暂停，点击打开 Web 控制页时会自动恢复。",
+  "Codex Remote Collaboration": "Codex 远程协同",
+  "Codex Remote will attach to {0} after the next bridge start.": "Codex Remote 将在下次启动桥接后附加到 {0}。",
+  "Codex Remote will auto-discover the latest VS Code Codex conversation after the next bridge start.": "Codex Remote 将在下次启动桥接后自动发现最新的 VS Code Codex 会话。",
+  "Connecting to the local Codex collaboration service": "正在连接本地 Codex 协同服务",
+  "Device credential from the Aether pairing flow": "Aether 配对流程生成的设备凭据",
+  "Enter a valid URL.": "请输入有效的 URL。",
+  "Enter a valid WebSocket URL.": "请输入有效的 WebSocket URL。",
+  "Enter the 8-character pairing code.": "请输入 8 位配对码。",
+  "Enter the Aether server URL.": "请输入 Aether 服务器地址。",
+  "Existing Codex conversation ID (leave blank for auto-discovery)": "现有 Codex 会话 ID（留空则自动发现）",
+  "Independent Codex mode is connected. Click to open the web control.": "独立 Codex 模式已连接，点击打开 Web 控制页。",
+  "One-time pairing code shown in Aether": "Aether 中显示的一次性配对码",
+  "Relay access token (leave blank for the local relay)": "Relay 访问 token（本地 relay 请留空）",
+  "Relay token stored in VS Code SecretStorage.": "Relay token 已保存到 VS Code SecretStorage。",
+  "Remote Aether connections must use wss://.": "远程 Aether 连接必须使用 wss://。",
+  "Remote Aether servers must use https://.": "远程 Aether 服务器必须使用 https://。",
+  "Restoring the local collaboration service": "正在恢复本地协同服务",
+  "Send input to the active Codex turn": "向当前 Codex turn 发送输入",
+  "Set codexRemoteCollab.localRelayUrl before starting the bridge.": "请先设置 codexRemoteCollab.localRelayUrl，再启动桥接。",
+  "Start the Codex remote bridge first.": "请先启动 Codex 远程桥接。",
+  "Starting the independent Codex mode.": "正在启动独立 Codex 模式。",
+  "Starting {0}": "正在启动 {0}",
+  "The Codex conversation is not connected": "Codex 会话尚未连接",
+  "The Codex executable is unavailable": "Codex 可执行文件不可用",
+  "The Codex remote bridge attached to the existing VS Code Codex conversation.": "Codex 远程桥接已附加到现有 VS Code Codex 会话。",
+  "The Codex remote bridge is already running.": "Codex 远程桥接已在运行。",
+  "The Codex remote collaboration bridge connected.": "Codex 远程协同桥接已连接。",
+  "The independent Codex mode is not connected": "独立 Codex 模式尚未连接",
+  "The independent Codex remote mode connected.": "独立 Codex 远程模式已连接。",
+  "The bridge is not connected": "桥接尚未连接",
+  "The local collaboration URL is invalid. Check codexRemoteCollab.localRelayUrl.": "本地协同地址无效，请检查 codexRemoteCollab.localRelayUrl。",
+  "The local collaboration service at {0} is temporarily unavailable. The extension will keep retrying.": "本地协同服务 {0} 暂时无法连接，扩展会继续重试。",
+  "The official Codex extension new-conversation command was not found. Make sure the VS Code Codex extension is enabled.": "未找到官方 Codex 扩展的新会话命令，请确认 VS Code Codex 扩展已启用。",
+  "Unable to pair with Aether: {0}": "无法与 Aether 配对：{0}",
+  "Unable to restore the local collaboration service": "无法恢复本地协同服务",
+  "Unable to send Codex input: {0}": "无法发送 Codex 输入：{0}",
+  "Unable to start the Codex remote bridge: {0}": "无法启动 Codex 远程桥接：{0}",
+  "Unable to start the local Codex collaboration service: {0}": "无法启动本地 Codex 协同服务：{0}",
+  "Unable to start the local collaboration service: {0}": "无法启动本地协同服务：{0}",
+  "Use a ws:// or wss:// URL.": "请使用 ws:// 或 wss:// URL。",
+  "Use the Aether origin without credentials, a query, or a fragment.": "请填写不含凭据、查询参数或片段的 Aether 源地址。",
+  "Waiting for a Codex conversation to open in VS Code. It will connect automatically.": "正在等待 VS Code 中打开 Codex 会话，检测到后会自动连接。",
+  "codexRemoteCollab.localRelayUrl must be a loopback ws:// address.": "codexRemoteCollab.localRelayUrl 必须是回环地址上的 ws:// URL。"
+}

aether-vscodex/vscode-extension/package-lock.json

@@ -0,0 +1,94 @@
+{
+  "name": "codex-remote-collab",
+  "version": "0.4.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "codex-remote-collab",
+      "version": "0.4.0",
+      "license": "MIT",
+      "dependencies": {
+        "ws": "^8.18.0"
+      },
+      "devDependencies": {
+        "@types/node": "^20.14.0",
+        "@types/vscode": "^1.85.0",
+        "@types/ws": "^8.5.12",
+        "typescript": "^5.4.5"
+      },
+      "engines": {
+        "vscode": "^1.85.0"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "20.19.43",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz",
+      "integrity": "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/@types/vscode": {
+      "version": "1.134.0",
+      "resolved": "https://registry.npmjs.org/@types/vscode/-/vscode-1.134.0.tgz",
+      "integrity": "sha512-NDEu0hg4sF7+vvFsADsktqUJ6f80LHSZvVK2Ovo1XiQ0/VHck1O3zst+ZZyVA/uvz6vo6LcuoqU2q48YMqOwWw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/ws": {
+      "version": "8.18.1",
+      "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
+      "integrity": "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/ws": {
+      "version": "8.21.3",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.3.tgz",
+      "integrity": "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    }
+  }
+}

aether-vscodex/vscode-extension/package.json

@@ -0,0 +1,211 @@
+{
+  "name": "codex-remote-collab",
+  "displayName": "%extension.displayName%",
+  "description": "%extension.description%",
+  "version": "0.4.0",
+  "publisher": "local",
+  "license": "MIT",
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "categories": [
+    "Other"
+  ],
+  "l10n": "./l10n",
+  "activationEvents": [
+    "onStartupFinished",
+    "onCommand:codexRemoteCollab.openWeb",
+    "onCommand:codexRemoteCollab.start",
+    "onCommand:codexRemoteCollab.stop",
+    "onCommand:codexRemoteCollab.setThreadId",
+    "onCommand:codexRemoteCollab.sendInput",
+    "onCommand:codexRemoteCollab.setRelayToken",
+    "onCommand:codexRemoteCollab.configureCloud",
+    "onCommand:codexRemoteCollab.pairCloud",
+    "onCommand:codexRemoteCollab.snapshot"
+  ],
+  "main": "./dist/extension.js",
+  "contributes": {
+    "commands": [
+      {
+        "command": "codexRemoteCollab.openWeb",
+        "title": "%command.openWeb%"
+      },
+      {
+        "command": "codexRemoteCollab.start",
+        "title": "%command.start%"
+      },
+      {
+        "command": "codexRemoteCollab.stop",
+        "title": "%command.stop%"
+      },
+      {
+        "command": "codexRemoteCollab.setThreadId",
+        "title": "%command.setThreadId%"
+      },
+      {
+        "command": "codexRemoteCollab.sendInput",
+        "title": "%command.sendInput%"
+      },
+      {
+        "command": "codexRemoteCollab.setRelayToken",
+        "title": "%command.setRelayToken%"
+      },
+      {
+        "command": "codexRemoteCollab.configureCloud",
+        "title": "%command.configureCloud%"
+      },
+      {
+        "command": "codexRemoteCollab.pairCloud",
+        "title": "%command.pairCloud%"
+      },
+      {
+        "command": "codexRemoteCollab.snapshot",
+        "title": "%command.snapshot%"
+      }
+    ],
+    "configuration": {
+      "title": "%configuration.title%",
+      "properties": {
+        "codexRemoteCollab.localRelayUrl": {
+          "type": "string",
+          "default": "ws://127.0.0.1:8787/v1/connect",
+          "description": "%configuration.localRelayUrl%"
+        },
+        "codexRemoteCollab.relayUrl": {
+          "type": "string",
+          "default": "ws://127.0.0.1:8787/v1/connect",
+          "description": "%configuration.relayUrl%",
+          "deprecationMessage": "%configuration.relayUrl.deprecation%"
+        },
+        "codexRemoteCollab.cloudRelayUrl": {
+          "type": "string",
+          "default": "",
+          "description": "%configuration.cloudRelayUrl%"
+        },
+        "codexRemoteCollab.aetherUrl": {
+          "type": "string",
+          "default": "",
+          "description": "%configuration.aetherUrl%"
+        },
+        "codexRemoteCollab.autoStart": {
+          "type": "boolean",
+          "default": true,
+          "description": "%configuration.autoStart%"
+        },
+        "codexRemoteCollab.autoStartLocalRelay": {
+          "type": "boolean",
+          "default": true,
+          "description": "%configuration.autoStartLocalRelay%"
+        },
+        "codexRemoteCollab.mode": {
+          "type": "string",
+          "enum": [
+            "attach",
+            "spawn"
+          ],
+          "default": "attach",
+          "description": "%configuration.mode%",
+          "deprecationMessage": "%configuration.mode.deprecation%"
+        },
+        "codexRemoteCollab.controlMode": {
+          "type": "string",
+          "enum": [
+            "sync",
+            "async"
+          ],
+          "enumDescriptions": [
+            "%configuration.controlMode.sync%",
+            "%configuration.controlMode.async%"
+          ],
+          "default": "sync",
+          "description": "%configuration.controlMode%"
+        },
+        "codexRemoteCollab.threadId": {
+          "type": "string",
+          "default": "",
+          "description": "%configuration.threadId%"
+        },
+        "codexRemoteCollab.autoDiscoverThread": {
+          "type": "boolean",
+          "default": true,
+          "description": "%configuration.autoDiscoverThread%"
+        },
+        "codexRemoteCollab.followVscodeSession": {
+          "type": "boolean",
+          "default": true,
+          "description": "%configuration.followVscodeSession%"
+        },
+        "codexRemoteCollab.ipcSocketPath": {
+          "type": "string",
+          "default": "",
+          "description": "%configuration.ipcSocketPath%"
+        },
+        "codexRemoteCollab.hostId": {
+          "type": "string",
+          "default": "local",
+          "description": "%configuration.hostId%"
+        },
+        "codexRemoteCollab.ipcStrictVersions": {
+          "type": "boolean",
+          "default": true,
+          "description": "%configuration.ipcStrictVersions%"
+        },
+        "codexRemoteCollab.codexCommand": {
+          "type": "string",
+          "default": "codex",
+          "description": "%configuration.codexCommand%"
+        },
+        "codexRemoteCollab.codexArgs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [
+            "app-server",
+            "--stdio"
+          ],
+          "description": "%configuration.codexArgs%"
+        },
+        "codexRemoteCollab.defaultCwd": {
+          "type": "string",
+          "default": "",
+          "description": "%configuration.defaultCwd%"
+        },
+        "codexRemoteCollab.approvalTimeoutMs": {
+          "type": "number",
+          "default": 300000,
+          "minimum": 1000,
+          "description": "%configuration.approvalTimeoutMs%"
+        },
+        "codexRemoteCollab.allowHighRiskApprovals": {
+          "type": "boolean",
+          "default": false,
+          "description": "%configuration.allowHighRiskApprovals%"
+        },
+        "codexRemoteCollab.relayReconnect": {
+          "type": "boolean",
+          "default": true,
+          "description": "%configuration.relayReconnect%"
+        }
+      }
+    }
+  },
+  "scripts": {
+    "vscode:prepublish": "npm run build:web && npm run build",
+    "build:web": "npm --prefix ../web run build",
+    "build": "tsc -p tsconfig.json && node scripts/sync-local-relay.cjs",
+    "compile": "npm run build",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "start:stdio": "node dist/cli.js"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/vscode": "^1.85.0",
+    "@types/ws": "^8.5.12",
+    "typescript": "^5.4.5"
+  }
+}

aether-vscodex/vscode-extension/package.nls.json

@@ -0,0 +1,38 @@
+{
+  "extension.displayName": "Codex Remote Collaboration",
+  "extension.description": "Synchronize the current VS Code Codex conversation or manage independent Codex conversations from a local browser and Aether cloud.",
+  "command.openWeb": "Codex Remote: Open Local Web Console",
+  "command.start": "Codex Remote: Start Bridge",
+  "command.stop": "Codex Remote: Stop Bridge",
+  "command.setThreadId": "Codex Remote: Set Existing Thread ID",
+  "command.sendInput": "Codex Remote: Send Input",
+  "command.setRelayToken": "Codex Remote: Set Local Relay Token",
+  "command.configureCloud": "Codex Remote: Configure Aether Cloud Manually",
+  "command.pairCloud": "Codex Remote: Pair with Aether",
+  "command.snapshot": "Codex Remote: Show Snapshot",
+  "configuration.title": "Codex Remote Collaboration",
+  "configuration.localRelayUrl": "Loopback relay used by the local browser UI. It remains active when Aether cloud sync is enabled.",
+  "configuration.relayUrl": "Legacy relay setting retained for compatibility. Use localRelayUrl and cloudRelayUrl for new installations.",
+  "configuration.relayUrl.deprecation": "Use codexRemoteCollab.localRelayUrl for local access and codexRemoteCollab.cloudRelayUrl for Aether cloud access.",
+  "configuration.cloudRelayUrl": "Optional Aether cloud relay WebSocket URL. The device credential is stored separately in VS Code SecretStorage.",
+  "configuration.aetherUrl": "Aether server origin used by the one-time pairing flow.",
+  "configuration.autoStart": "Start the bridge when the extension activates.",
+  "configuration.autoStartLocalRelay": "Automatically host the bundled relay for loopback ws:// URLs.",
+  "configuration.mode": "Attach to the existing official VS Code Codex session, or spawn a separate app-server for legacy use.",
+  "configuration.mode.deprecation": "Use codexRemoteCollab.controlMode. attach maps to sync and spawn maps to async.",
+  "configuration.controlMode": "Choose whether the web console follows the current VS Code Codex conversation or manages independent conversations.",
+  "configuration.controlMode.sync": "Synchronize with the conversation currently shown in the official VS Code Codex panel.",
+  "configuration.controlMode.async": "Run an independent Codex app-server and manage its conversations from the web console.",
+  "configuration.threadId": "Existing VS Code Codex conversation ID to follow. Empty uses the most recent locally available session.",
+  "configuration.autoDiscoverThread": "Discover a recent VS Code Codex conversation when no thread ID is configured.",
+  "configuration.followVscodeSession": "Follow conversation changes in the attached official VS Code Codex panel.",
+  "configuration.ipcSocketPath": "Optional official Codex IPC socket path. Empty uses CODEX_HOME/ipc/ipc.sock.",
+  "configuration.hostId": "Codex host identifier used for existing-session discovery.",
+  "configuration.ipcStrictVersions": "Reject unknown private IPC stream versions instead of applying them optimistically.",
+  "configuration.codexCommand": "Asynchronous mode: Codex executable used to launch the independent app-server.",
+  "configuration.codexArgs": "Asynchronous mode: arguments passed to the Codex executable.",
+  "configuration.defaultCwd": "Asynchronous mode: working directory used when starting a conversation.",
+  "configuration.approvalTimeoutMs": "Milliseconds before an unanswered Codex approval or input request is denied locally.",
+  "configuration.allowHighRiskApprovals": "Allow the remote operator to approve high-risk commands. Keep disabled unless the relay and host are tightly controlled.",
+  "configuration.relayReconnect": "Reconnect outbound relay WebSockets after a disconnect."
+}

aether-vscodex/vscode-extension/package.nls.zh-cn.json

@@ -0,0 +1,38 @@
+{
+  "extension.displayName": "Codex 远程协同",
+  "extension.description": "从本地浏览器或 Aether 云端同步 VS Code 当前 Codex 会话，或独立管理 Codex 会话。",
+  "command.openWeb": "Codex 远程：打开本地 Web 控制台",
+  "command.start": "Codex 远程：启动桥接",
+  "command.stop": "Codex 远程：停止桥接",
+  "command.setThreadId": "Codex 远程：设置现有会话 ID",
+  "command.sendInput": "Codex 远程：发送输入",
+  "command.setRelayToken": "Codex 远程：设置本地中继令牌",
+  "command.configureCloud": "Codex 远程：手动配置 Aether 云端",
+  "command.pairCloud": "Codex 远程：与 Aether 配对",
+  "command.snapshot": "Codex 远程：显示会话快照",
+  "configuration.title": "Codex 远程协同",
+  "configuration.localRelayUrl": "本地浏览器控制台使用的回环中继地址。启用 Aether 云同步后仍保持连接。",
+  "configuration.relayUrl": "为兼容旧版本保留的中继设置。新安装请使用 localRelayUrl 和 cloudRelayUrl。",
+  "configuration.relayUrl.deprecation": "本地访问请使用 codexRemoteCollab.localRelayUrl，Aether 云端访问请使用 codexRemoteCollab.cloudRelayUrl。",
+  "configuration.cloudRelayUrl": "可选的 Aether 云端 WebSocket 中继地址。设备凭据单独保存在 VS Code SecretStorage 中。",
+  "configuration.aetherUrl": "一次性配对流程使用的 Aether 服务地址。",
+  "configuration.autoStart": "扩展激活时自动启动桥接。",
+  "configuration.autoStartLocalRelay": "为回环 ws:// 地址自动启动扩展内置的本地中继。",
+  "configuration.mode": "附加到官方 VS Code Codex 现有会话，或为兼容旧版本启动独立 app-server。",
+  "configuration.mode.deprecation": "请改用 codexRemoteCollab.controlMode。attach 对应 sync，spawn 对应 async。",
+  "configuration.controlMode": "选择 Web 控制台是跟随 VS Code 当前 Codex 会话，还是独立管理会话。",
+  "configuration.controlMode.sync": "同步展示官方 VS Code Codex 面板当前打开的会话。",
+  "configuration.controlMode.async": "启动独立 Codex app-server，并从 Web 控制台管理其会话。",
+  "configuration.threadId": "要跟随的现有 VS Code Codex 会话 ID。留空时使用本机最近可附加的会话。",
+  "configuration.autoDiscoverThread": "未设置会话 ID 时自动发现最近的 VS Code Codex 会话。",
+  "configuration.followVscodeSession": "自动跟随官方 VS Code Codex 面板中的会话切换。",
+  "configuration.ipcSocketPath": "可选的官方 Codex IPC socket 路径。留空时使用 CODEX_HOME/ipc/ipc.sock。",
+  "configuration.hostId": "现有会话发现使用的 Codex 主机标识。",
+  "configuration.ipcStrictVersions": "拒绝未知的私有 IPC 流版本，不进行乐观兼容。",
+  "configuration.codexCommand": "异步模式：用于启动独立 app-server 的 Codex 可执行文件。",
+  "configuration.codexArgs": "异步模式：传给 Codex 可执行文件的参数。",
+  "configuration.defaultCwd": "异步模式：启动会话时使用的工作目录。",
+  "configuration.approvalTimeoutMs": "Codex 授权或输入请求无人处理时，在本地拒绝前等待的毫秒数。",
+  "configuration.allowHighRiskApprovals": "允许远程操作员批准高风险命令。仅在中继和主机均受严格控制时启用。",
+  "configuration.relayReconnect": "中继 WebSocket 断开后自动重连。"
+}

aether-vscodex/vscode-extension/scripts/sync-local-relay.cjs

@@ -0,0 +1,19 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const extensionRoot = path.resolve(__dirname, "..");
+const projectRoot = path.resolve(extensionRoot, "..");
+const outputRoot = path.join(extensionRoot, "dist", "local-relay");
+const publicRoot = path.join(extensionRoot, "dist", "public");
+const vuePublicRoot = path.join(projectRoot, "web", "dist");
+
+if (!fs.existsSync(path.join(vuePublicRoot, "index.html"))) {
+  throw new Error("web/dist is missing; run npm run build:web before building the extension");
+}
+
+fs.rmSync(outputRoot, { recursive: true, force: true });
+fs.rmSync(publicRoot, { recursive: true, force: true });
+fs.mkdirSync(outputRoot, { recursive: true });
+fs.mkdirSync(publicRoot, { recursive: true });
+fs.copyFileSync(path.join(projectRoot, "relay", "server.js"), path.join(outputRoot, "server.js"));
+fs.cpSync(vuePublicRoot, publicRoot, { recursive: true });

aether-vscodex/vscode-extension/src/bridge.ts

@@ -0,0 +1,46 @@
+import { CodexAgentAdapter, CodexAgentAdapterOptions } from "./codexAgentAdapter";
+import { RelayClient, RelayClientOptions } from "./relayClient";
+import { RelayHost, RelayHostOptions } from "./relayHost";
+import { AgentAdapter, Logger, RelayTransport } from "./protocol";
+
+export interface CodexRemoteBridgeOptions {
+  /** Use a supplied adapter/transport when embedding or testing. */
+  adapter?: AgentAdapter;
+  relay?: RelayTransport;
+  adapterOptions?: CodexAgentAdapterOptions;
+  relayOptions?: RelayClientOptions;
+  sessionId?: string;
+  capabilities?: Iterable<string>;
+  logger?: Logger;
+}
+export interface CodexRemoteBridge {
+  adapter: AgentAdapter;
+  relay: RelayTransport;
+  host: RelayHost;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+
+/** Construct the default outbound VS Code bridge in one call. */
+export function createBridge(options: CodexRemoteBridgeOptions): CodexRemoteBridge {
+  const adapter = options.adapter ?? new CodexAgentAdapter(options.adapterOptions);
+  const relay = options.relay ?? (() => {
+    if (!options.relayOptions) throw new Error("relayOptions are required when no relay transport is supplied");
+    return new RelayClient(options.relayOptions);
+  })();
+  const hostOptions: RelayHostOptions = {
+    adapter,
+    relay,
+    ...(options.sessionId ? { sessionId: options.sessionId } : {}),
+    ...(options.capabilities ? { capabilities: options.capabilities } : {}),
+    ...(options.logger ? { logger: options.logger } : {}),
+  };
+  const host = new RelayHost(hostOptions);
+  return {
+    adapter,
+    relay,
+    host,
+    start: () => host.start(),
+    stop: () => host.stop(),
+  };
+}

aether-vscodex/vscode-extension/src/cli.ts

@@ -0,0 +1,30 @@
+import { CodexAgentAdapter } from "./codexAgentAdapter";
+import { RelayHost } from "./relayHost";
+import { StdioRelayTransport } from "./relayClient";
+
+/** Standalone bridge: relay frames in stdin, relay frames out on stdout. */
+async function main(): Promise<void> {
+  const logger = {
+    debug: (message: string, ...args: unknown[]) => console.error(`[debug] ${message}`, ...args),
+    info: (message: string, ...args: unknown[]) => console.error(`[info] ${message}`, ...args),
+    warn: (message: string, ...args: unknown[]) => console.error(`[warn] ${message}`, ...args),
+    error: (message: string, ...args: unknown[]) => console.error(`[error] ${message}`, ...args),
+  };
+  const command = process.env.CODEX_COMMAND || "codex";
+  const args = process.env.CODEX_APP_SERVER_ARGS ? JSON.parse(process.env.CODEX_APP_SERVER_ARGS) as string[] : ["app-server", "--stdio"];
+  const adapter = new CodexAgentAdapter({ command, args, defaultCwd: process.env.CODEX_WORKSPACE, logger });
+  const relay = new StdioRelayTransport(process.stdin, process.stdout, logger);
+  const host = new RelayHost({ adapter, relay, sendHandshake: true, logger });
+  const shutdown = async (): Promise<void> => {
+    await host.stop();
+    process.exit(0);
+  };
+  process.once("SIGINT", () => void shutdown());
+  process.once("SIGTERM", () => void shutdown());
+  await host.start();
+}
+
+void main().catch((error) => {
+  console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+  process.exitCode = 1;
+});

aether-vscodex/vscode-extension/src/codexIpc.ts

@@ -0,0 +1,947 @@
+/**
+ * Minimal client for the private Codex desktop/VS Code coordination socket.
+ *
+ * This is intentionally separate from the app-server (JSONL/stdio) adapter.
+ * It attaches to the already running Codex UI through the local IPC router and
+ * therefore does not spawn another `codex` process. The wire protocol is
+ * private and versioned by the official extension; keep this module isolated
+ * so a protocol change can fail without taking down the relay bridge.
+ */
+
+import * as crypto from "node:crypto";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import type { JsonObject, JsonValue } from "./protocol";
+
+export const INITIALIZING_CLIENT_ID = "initializing-client";
+export const DEFAULT_IPC_REQUEST_TIMEOUT_MS = 5_000;
+export const DEFAULT_MAX_IPC_FRAME_BYTES = 256 * 1024 * 1024;
+
+/** Versions shipped by openai.chatgpt 26.820.71523. */
+export const CODEX_IPC_METHOD_VERSIONS = Object.freeze({
+  "thread-stream-state-changed": 11,
+  "thread-stream-following-changed": 1,
+  "thread-stream-following-status-requested": 1,
+  "ipc-connection-reset": 1,
+  "thread-read-state-changed": 2,
+  "thread-archived": 2,
+  "thread-unarchived": 1,
+  "thread-owner-discovery": 1,
+  "thread-follower-start-turn": 2,
+  "thread-follower-load-complete-history": 1,
+  "thread-follower-compact-thread": 1,
+  "thread-follower-steer-turn": 1,
+  "thread-follower-interrupt-turn": 4,
+  "thread-follower-update-thread-settings": 1,
+  "thread-follower-edit-last-user-turn": 2,
+  "thread-follower-command-approval-decision": 1,
+  "thread-follower-file-approval-decision": 1,
+  "thread-follower-permissions-request-approval-response": 1,
+  "thread-follower-submit-user-input": 1,
+  "thread-follower-submit-mcp-server-elicitation-response": 1,
+  "thread-follower-set-queued-follow-ups-state": 1,
+  "thread-queued-followups-changed": 1,
+} as const);
+
+export type IpcMethod = keyof typeof CODEX_IPC_METHOD_VERSIONS;
+export type IpcRequestId = string | number;
+export type IpcPatchPathPart = string | number;
+
+export interface IpcRequest {
+  type: "request";
+  requestId: IpcRequestId;
+  sourceClientId: string;
+  targetClientId?: string;
+  version: number;
+  method: string;
+  params?: JsonValue;
+  timeoutMs?: number;
+}
+
+export interface IpcResponse {
+  type: "response";
+  requestId: IpcRequestId;
+  resultType: "success" | "error";
+  method?: string;
+  handledByClientId?: string;
+  result?: JsonValue;
+  error?: string;
+}
+
+export interface IpcBroadcast {
+  type: "broadcast";
+  method: string;
+  sourceClientId?: string;
+  targetClientIds?: string[];
+  version: number;
+  params?: JsonValue;
+}
+
+export interface IpcClientDiscoveryRequest {
+  type: "client-discovery-request";
+  requestId: IpcRequestId;
+  request: IpcRequest;
+}
+
+export interface IpcClientDiscoveryResponse {
+  type: "client-discovery-response";
+  requestId: IpcRequestId;
+  response: { canHandle: boolean };
+}
+
+export type IpcMessage =
+  | IpcRequest
+  | IpcResponse
+  | IpcBroadcast
+  | IpcClientDiscoveryRequest
+  | IpcClientDiscoveryResponse;
+
+export interface IpcJsonPatch {
+  op: "add" | "remove" | "replace";
+  path: IpcPatchPathPart[];
+  value?: JsonValue;
+}
+
+export interface ThreadStreamSnapshot {
+  type: "snapshot";
+  revision: number;
+  conversationState: JsonObject;
+}
+
+export interface ThreadStreamPatches {
+  type: "patches";
+  baseRevision: number;
+  revision: number;
+  patches: IpcJsonPatch[];
+}
+
+export type ThreadStreamChange = ThreadStreamSnapshot | ThreadStreamPatches;
+
+export interface ConversationStreamState {
+  conversationId: string;
+  hostId: string;
+  ownerClientId: string;
+  revision: number;
+  conversationState: JsonObject;
+}
+
+export type ConversationStreamEvent =
+  | (ConversationStreamState & { kind: "snapshot"; raw: IpcBroadcast })
+  | (ConversationStreamState & { kind: "patches"; patches: IpcJsonPatch[]; baseRevision: number; raw: IpcBroadcast })
+  | {
+      kind: "desync";
+      conversationId: string;
+      hostId: string;
+      ownerClientId: string;
+      expectedRevision: number;
+      receivedBaseRevision: number;
+      receivedRevision: number;
+      raw: IpcBroadcast;
+    };
+
+export interface CodexIpcClientOptions {
+  /** Explicit socket path; otherwise `$CODEX_HOME/ipc/ipc.sock` or `~/.codex`. */
+  socketPath?: string;
+  codexHome?: string;
+  homeDir?: string;
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  clientType?: string;
+  requestTimeoutMs?: number;
+  maxFrameBytes?: number;
+  strictVersions?: boolean;
+  /** Reconnect after a socket close and re-send all active following subscriptions. */
+  autoReconnect?: boolean;
+  reconnectDelayMs?: number;
+  /** Optional handler for discovery requests. Default is fail-closed (`false`). */
+  canHandleRequest?: (request: IpcRequest) => boolean | Promise<boolean>;
+}
+
+export interface FollowerTurnStartOptions {
+  request?: JsonObject;
+  context?: JsonObject;
+  clientUserMessageId?: string;
+  ownerClientId?: string;
+  timeoutMs?: number;
+}
+
+export interface FollowerSteerOptions {
+  clientUserMessageId?: string;
+  serviceTier?: string | null;
+  attachments?: JsonValue[];
+  additionalContext?: JsonObject | null;
+  restoreMessage?: JsonValue | null;
+  ownerClientId?: string;
+  timeoutMs?: number;
+}
+
+export interface FollowerInterruptOptions {
+  mode?: "user-stop" | "system" | "descendant-cleanup" | string;
+  expectedTurnId?: string | null;
+  ownerClientId?: string;
+  timeoutMs?: number;
+}
+
+export interface FollowOptions {
+  hostId?: string;
+  targetClientIds?: string[];
+}
+
+export interface RequestOptions {
+  targetClientId?: string;
+  timeoutMs?: number;
+  version?: number;
+  requestId?: IpcRequestId;
+}
+
+export interface IpcErrorOptions {
+  code: string;
+  response?: IpcResponse;
+}
+
+export class CodexIpcError extends Error {
+  readonly code: string;
+  readonly response?: IpcResponse;
+
+  constructor(message: string, options: IpcErrorOptions) {
+    super(message);
+    this.name = "CodexIpcError";
+    this.code = options.code;
+    this.response = options.response;
+  }
+}
+
+export function resolveCodexIpcSocketPath(options: {
+  socketPath?: string;
+  codexHome?: string;
+  homeDir?: string;
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+} = {}): string {
+  if (options.socketPath?.trim()) return options.socketPath.trim();
+  const platform = options.platform ?? process.platform;
+  if (platform === "win32") return "\\\\.\\pipe\\codex-ipc";
+  const env = options.env ?? process.env;
+  const homeDir = options.homeDir ?? os.homedir();
+  const configuredHome = options.codexHome?.trim() || env.CODEX_HOME?.trim() || path.join(homeDir, ".codex");
+  const codexHome = configuredHome === "~"
+    ? homeDir
+    : configuredHome.startsWith("~/")
+      ? path.join(homeDir, configuredHome.slice(2))
+      : configuredHome;
+  return path.join(codexHome, "ipc", "ipc.sock");
+}
+
+/** Encode one private IPC frame: uint32 little-endian byte length + UTF-8 JSON. */
+export function encodeIpcFrame(message: IpcMessage, maxFrameBytes = DEFAULT_MAX_IPC_FRAME_BYTES): Buffer {
+  const json = JSON.stringify(message);
+  const payload = Buffer.from(json, "utf8");
+  if (payload.length === 0 || payload.length > maxFrameBytes) {
+    throw new RangeError(`IPC frame exceeds ${maxFrameBytes} bytes`);
+  }
+  const frame = Buffer.allocUnsafe(4 + payload.length);
+  frame.writeUInt32LE(payload.length, 0);
+  payload.copy(frame, 4);
+  return frame;
+}
+
+/** Incremental decoder that accepts arbitrary TCP/Unix-socket chunk boundaries. */
+export class IpcFrameDecoder {
+  private buffer = Buffer.alloc(0);
+
+  constructor(private readonly maxFrameBytes = DEFAULT_MAX_IPC_FRAME_BYTES) {}
+
+  push(chunk: Uint8Array): IpcMessage[] {
+    if (chunk.length === 0) return [];
+    this.buffer = this.buffer.length === 0 ? Buffer.from(chunk) : Buffer.concat([this.buffer, chunk]);
+    const messages: IpcMessage[] = [];
+    while (this.buffer.length >= 4) {
+      const payloadLength = this.buffer.readUInt32LE(0);
+      if (payloadLength === 0 || payloadLength > this.maxFrameBytes) {
+        throw new CodexIpcError(`Invalid IPC frame length (${payloadLength} bytes)`, { code: "invalid-frame-length" });
+      }
+      if (this.buffer.length < payloadLength + 4) break;
+      const payload = this.buffer.subarray(4, payloadLength + 4).toString("utf8");
+      this.buffer = this.buffer.subarray(payloadLength + 4);
+      let decoded: unknown;
+      try {
+        decoded = JSON.parse(payload);
+      } catch (error) {
+        throw new CodexIpcError(`Invalid IPC JSON: ${error instanceof Error ? error.message : String(error)}`, {
+          code: "invalid-json",
+        });
+      }
+      if (!isRecord(decoded) || typeof decoded.type !== "string") {
+        throw new CodexIpcError("IPC frame must be an object with a type", { code: "invalid-message" });
+      }
+      messages.push(decoded as unknown as IpcMessage);
+    }
+    return messages;
+  }
+
+  reset(): void {
+    this.buffer = Buffer.alloc(0);
+  }
+}
+
+type Listener<T> = (value: T) => void;
+export interface IpcSubscription { dispose(): void; }
+
+function subscribe<T>(set: Set<Listener<T>>, listener: Listener<T>): IpcSubscription {
+  set.add(listener);
+  return { dispose: () => set.delete(listener) };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isJsonObject(value: unknown): value is JsonObject {
+  return isRecord(value);
+}
+
+function requestIdKey(id: IpcRequestId): string {
+  return `${typeof id}:${String(id)}`;
+}
+
+function cloneJson<T extends JsonValue>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function versionFor(method: string, params?: JsonValue): number {
+  // The official client accepts interrupt v3 when expectedTurnId is absent;
+  // v4 is used when the active-turn precondition is present.
+  if (method === "thread-follower-interrupt-turn"
+    && (!isRecord(params) || params.expectedTurnId === undefined || params.expectedTurnId === null)) return 3;
+  return CODEX_IPC_METHOD_VERSIONS[method as IpcMethod] ?? 0;
+}
+
+function textInput(text: string): JsonObject {
+  return { type: "text", text, text_elements: [] };
+}
+
+function normalizeInput(input: string | JsonValue[]): JsonValue[] {
+  return typeof input === "string"
+    ? [textInput(input)]
+    : input.map((entry) => typeof entry === "string" ? textInput(entry) : entry);
+}
+
+function hasTarget(frame: IpcBroadcast, clientId: string): boolean {
+  return frame.targetClientIds == null || frame.targetClientIds.includes(clientId);
+}
+
+/** Apply the JSON patch arrays generated by Immer in the official webview. */
+export function applyIpcPatches(root: JsonValue, patches: IpcJsonPatch[]): JsonValue {
+  let result = cloneJson(root);
+  for (const patch of patches) {
+    if (!Array.isArray(patch.path)) throw new CodexIpcError("IPC patch path must be an array", { code: "invalid-patch" });
+    if (patch.path.length === 0) {
+      if (patch.op === "remove") throw new CodexIpcError("Removing the conversation root is unsupported", { code: "invalid-patch" });
+      if (patch.value === undefined) throw new CodexIpcError("Patch value is missing", { code: "invalid-patch" });
+      result = cloneJson(patch.value);
+      continue;
+    }
+
+    const parentPath = patch.path.slice(0, -1);
+    const key = patch.path[patch.path.length - 1];
+    assertSafePatchPart(key);
+    const parent = getAtPath(result, parentPath);
+    if (Array.isArray(parent)) {
+      const index = key === "-" ? parent.length : toArrayIndex(key);
+      if (patch.op === "add") {
+        if (patch.value === undefined) throw new CodexIpcError("Patch value is missing", { code: "invalid-patch" });
+        parent.splice(index, 0, cloneJson(patch.value));
+      } else if (patch.op === "replace") {
+        if (patch.value === undefined || index < 0 || index >= parent.length) throw new CodexIpcError("Invalid array replace patch", { code: "invalid-patch" });
+        parent[index] = cloneJson(patch.value);
+      } else {
+        if (index < 0 || index >= parent.length) throw new CodexIpcError("Invalid array remove patch", { code: "invalid-patch" });
+        parent.splice(index, 1);
+      }
+      continue;
+    }
+    if (!isRecord(parent) || typeof key !== "string") {
+      throw new CodexIpcError("IPC patch parent is not an object or array", { code: "invalid-patch" });
+    }
+    if (patch.op === "remove") {
+      delete parent[key];
+    } else {
+      if (patch.value === undefined) throw new CodexIpcError("Patch value is missing", { code: "invalid-patch" });
+      parent[key] = cloneJson(patch.value);
+    }
+  }
+  return result;
+}
+
+function getAtPath(root: JsonValue, pathParts: IpcPatchPathPart[]): JsonValue {
+  let current: JsonValue = root;
+  for (const part of pathParts) {
+    if (Array.isArray(current)) {
+      const index = toArrayIndex(part);
+      if (index < 0 || index >= current.length) throw new CodexIpcError("IPC patch path is out of bounds", { code: "invalid-patch" });
+      current = current[index];
+    } else if (isRecord(current) && typeof part === "string" && Object.prototype.hasOwnProperty.call(current, part)) {
+      assertSafePatchPart(part);
+      current = current[part];
+    } else {
+      throw new CodexIpcError("IPC patch path does not exist", { code: "invalid-patch" });
+    }
+  }
+  return current;
+}
+
+function toArrayIndex(value: IpcPatchPathPart): number {
+  if (typeof value === "number" && Number.isInteger(value)) return value;
+  if (typeof value === "string" && /^\d+$/.test(value)) return Number(value);
+  throw new CodexIpcError(`Invalid array patch index: ${String(value)}`, { code: "invalid-patch" });
+}
+
+function assertSafePatchPart(value: IpcPatchPathPart): void {
+  if (value === "__proto__" || value === "prototype" || value === "constructor") {
+    throw new CodexIpcError("Unsafe IPC patch path", { code: "invalid-patch" });
+  }
+}
+
+export class CodexIpcClient {
+  readonly socketPath: string;
+  private readonly options: Required<Pick<CodexIpcClientOptions, "clientType" | "requestTimeoutMs" | "maxFrameBytes" | "strictVersions" | "autoReconnect" | "reconnectDelayMs">> & CodexIpcClientOptions;
+  private socket: net.Socket | undefined;
+  private decoder: IpcFrameDecoder;
+  private connectPromise: Promise<string> | undefined;
+  private reconnectTimer: NodeJS.Timeout | undefined;
+  private disposed = false;
+  private clientId = INITIALIZING_CLIENT_ID;
+  private readonly pending = new Map<string, { method: string; resolve: (response: IpcResponse) => void; reject: (error: Error) => void; timer: NodeJS.Timeout }>();
+  private readonly followed = new Map<string, string>();
+  private readonly streams = new Map<string, ConversationStreamState>();
+  private readonly messageListeners = new Set<Listener<IpcMessage>>();
+  private readonly broadcastListeners = new Set<Listener<IpcBroadcast>>();
+  private readonly streamListeners = new Set<Listener<ConversationStreamEvent>>();
+  private readonly errorListeners = new Set<Listener<Error>>();
+  private readonly closeListeners = new Set<Listener<Error | undefined>>();
+  private readonly discoveryHandler?: (request: IpcRequest) => boolean | Promise<boolean>;
+
+  constructor(options: CodexIpcClientOptions = {}) {
+    this.options = {
+      ...options,
+      clientType: options.clientType ?? "codex-remote-collab",
+      requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_IPC_REQUEST_TIMEOUT_MS,
+      maxFrameBytes: options.maxFrameBytes ?? DEFAULT_MAX_IPC_FRAME_BYTES,
+      strictVersions: options.strictVersions ?? true,
+      autoReconnect: options.autoReconnect ?? false,
+      reconnectDelayMs: options.reconnectDelayMs ?? 1_000,
+    };
+    this.socketPath = resolveCodexIpcSocketPath(options);
+    this.decoder = new IpcFrameDecoder(this.options.maxFrameBytes);
+    this.discoveryHandler = options.canHandleRequest;
+  }
+
+  getClientId(): string { return this.clientId; }
+
+  getConversationState(conversationId: string): ConversationStreamState | undefined {
+    const state = this.streams.get(conversationId);
+    return state == null ? undefined : { ...state, conversationState: cloneJson(state.conversationState) };
+  }
+
+  getFollowedConversations(): ReadonlyMap<string, string> { return this.followed; }
+
+  onMessage(listener: Listener<IpcMessage>): IpcSubscription { return subscribe(this.messageListeners, listener); }
+  onBroadcast(listener: Listener<IpcBroadcast>): IpcSubscription { return subscribe(this.broadcastListeners, listener); }
+  onStreamEvent(listener: Listener<ConversationStreamEvent>): IpcSubscription { return subscribe(this.streamListeners, listener); }
+  onError(listener: Listener<Error>): IpcSubscription { return subscribe(this.errorListeners, listener); }
+  onClose(listener: Listener<Error | undefined>): IpcSubscription { return subscribe(this.closeListeners, listener); }
+
+  async connect(): Promise<string> {
+    if (this.disposed) throw new CodexIpcError("IPC client is disposed", { code: "disposed" });
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = undefined;
+    }
+    if (this.socket?.writable && this.clientId !== INITIALIZING_CLIENT_ID) return this.clientId;
+    if (this.connectPromise) return this.connectPromise;
+    this.connectPromise = new Promise<string>((resolve, reject) => {
+      const socket = net.createConnection(this.socketPath);
+      this.socket = socket;
+      this.decoder.reset();
+      let settled = false;
+      const finishError = (error: Error): void => {
+        if (!settled) {
+          settled = true;
+          reject(error);
+        }
+        this.emitError(error);
+      };
+      socket.setNoDelay?.(true);
+      socket.on("connect", () => {
+        const requestId = crypto.randomUUID();
+        const timer = setTimeout(() => {
+          this.pending.delete(requestIdKey(requestId));
+          finishError(new CodexIpcError("IPC initialize timed out", { code: "timeout" }));
+          socket.destroy();
+        }, this.options.requestTimeoutMs);
+        this.pending.set(requestIdKey(requestId), {
+          method: "initialize",
+          resolve: (response) => {
+            clearTimeout(timer);
+            if (response.resultType !== "success" || !isRecord(response.result) || typeof response.result.clientId !== "string") {
+              finishError(new CodexIpcError("IPC initialize returned an invalid response", { code: "initialize-failed", response }));
+              socket.destroy();
+              return;
+            }
+            this.clientId = response.result.clientId;
+            settled = true;
+            resolve(this.clientId);
+            this.resubscribeAfterConnect().catch((error) => this.emitError(asError(error)));
+          },
+          reject: (error) => {
+            clearTimeout(timer);
+            finishError(error);
+            socket.destroy();
+          },
+          timer,
+        });
+        this.write({
+          type: "request",
+          requestId,
+          sourceClientId: INITIALIZING_CLIENT_ID,
+          version: 0,
+          method: "initialize",
+          params: { clientType: this.options.clientType },
+        });
+      });
+      socket.on("data", (chunk) => {
+        try {
+          for (const message of this.decoder.push(chunk)) this.handleMessage(message);
+        } catch (error) {
+          const normalized = asError(error);
+          finishError(normalized);
+          socket.destroy(normalized);
+        }
+      });
+      socket.on("error", (error) => {
+        if (!settled) finishError(error);
+        else this.emitError(error);
+      });
+      socket.on("close", () => {
+        this.handleClose();
+      });
+    }).finally(() => {
+      this.connectPromise = undefined;
+    });
+    return this.connectPromise;
+  }
+
+  async followConversation(conversationId: string, following = true, options: FollowOptions = {}): Promise<void> {
+    const hostId = options.hostId ?? "local";
+    await this.connect();
+    if (following) this.followed.set(conversationId, hostId);
+    else {
+      this.followed.delete(conversationId);
+      this.streams.delete(conversationId);
+    }
+    const params: JsonObject = { conversationId, hostId, following };
+    const frame: IpcBroadcast = {
+      type: "broadcast",
+      method: "thread-stream-following-changed",
+      sourceClientId: this.clientId,
+      version: CODEX_IPC_METHOD_VERSIONS["thread-stream-following-changed"],
+      params,
+    };
+    if (options.targetClientIds) frame.targetClientIds = options.targetClientIds;
+    this.write(frame);
+  }
+
+  async findThreadOwner(conversationId: string, hostId = "local", timeoutMs = this.options.requestTimeoutMs): Promise<string | null> {
+    try {
+      const response = await this.request("thread-owner-discovery", { conversationId, hostId }, { timeoutMs });
+      return response.handledByClientId ?? null;
+    } catch (error) {
+      if (error instanceof CodexIpcError
+        && (error.code === "no-client-found" || error.code.startsWith("no-client-found:"))) return null;
+      throw error;
+    }
+  }
+
+  async request(method: string, params?: JsonValue, options: RequestOptions = {}): Promise<IpcResponse> {
+    await this.connect();
+    const requestId = options.requestId ?? crypto.randomUUID();
+    const timeoutMs = options.timeoutMs ?? this.options.requestTimeoutMs;
+    const frame: IpcRequest = {
+      type: "request",
+      requestId,
+      sourceClientId: this.clientId,
+      version: options.version ?? versionFor(method, params),
+      method,
+      params,
+    };
+    if (options.targetClientId) frame.targetClientId = options.targetClientId;
+    if (timeoutMs > 0) frame.timeoutMs = timeoutMs;
+    return new Promise<IpcResponse>((resolve, reject) => {
+      const key = requestIdKey(requestId);
+      const timer = setTimeout(() => {
+        this.pending.delete(key);
+        reject(new CodexIpcError(`${method} timed out`, { code: "timeout" }));
+      }, timeoutMs > 0 ? timeoutMs : 2 ** 31 - 1);
+      this.pending.set(key, { method, resolve, reject, timer });
+      try {
+        this.write(frame);
+      } catch (error) {
+        clearTimeout(timer);
+        this.pending.delete(key);
+        reject(asError(error));
+      }
+    }).then((response) => {
+      if (response.resultType === "error") {
+        throw new CodexIpcError(response.error ?? `${method} failed`, { code: response.error ?? "ipc-error", response });
+      }
+      if (response.method != null && response.method !== method) {
+        throw new CodexIpcError(`IPC response method mismatch: expected ${method}, got ${response.method}`, {
+          code: "response-method-mismatch",
+          response,
+        });
+      }
+      return response;
+    });
+  }
+
+  async requestFollower(method: string, conversationId: string, params: JsonObject = {}, options: RequestOptions & { ownerClientId?: string } = {}): Promise<IpcResponse> {
+    const ownerClientId = options.ownerClientId ?? this.streams.get(conversationId)?.ownerClientId;
+    if (!ownerClientId) throw new CodexIpcError(`No owner is known for conversation ${conversationId}`, { code: "owner-unknown" });
+    // Do not allow a caller-provided params object to accidentally retarget a
+    // request after the owner has been selected from the stream snapshot.
+    const body: JsonObject = { ...params, conversationId };
+    const { ownerClientId: _owner, ...requestOptions } = options;
+    return this.request(method, body, { ...requestOptions, targetClientId: ownerClientId });
+  }
+
+  /** Send the exact private `turnStart` envelope expected by the owner. */
+  async startTurn(conversationId: string, input: string | JsonValue[], options: FollowerTurnStartOptions = {}): Promise<JsonValue | undefined> {
+    const request: JsonObject = {
+      ...(options.request ?? {}),
+      threadId: conversationId,
+      input: options.request?.input ?? normalizeInput(input),
+    };
+    const context: JsonObject = { inheritThreadSettings: true, ...(options.context ?? {}) };
+    if (options.clientUserMessageId) request.clientUserMessageId = options.clientUserMessageId;
+    const response = await this.requestFollower("thread-follower-start-turn", conversationId, {
+      turnStart: { request, context },
+    }, {
+      ownerClientId: options.ownerClientId,
+      timeoutMs: options.timeoutMs,
+    });
+    return response.result;
+  }
+
+  async steerTurn(conversationId: string, input: string | JsonValue[], options: FollowerSteerOptions = {}): Promise<JsonValue | undefined> {
+    const params: JsonObject = {
+      clientUserMessageId: options.clientUserMessageId ?? crypto.randomUUID(),
+      input: normalizeInput(input),
+      attachments: options.attachments ?? [],
+    };
+    if (options.serviceTier !== undefined) params.serviceTier = options.serviceTier;
+    if (options.additionalContext !== undefined) params.additionalContext = options.additionalContext;
+    if (options.restoreMessage !== undefined) params.restoreMessage = options.restoreMessage;
+    const response = await this.requestFollower("thread-follower-steer-turn", conversationId, params, {
+      ownerClientId: options.ownerClientId,
+      timeoutMs: options.timeoutMs,
+    });
+    return response.result;
+  }
+
+  /**
+   * Persist settings for the next turn through the official conversation
+   * owner.  The owner-side follower handler expects the settings nested under
+   * `threadSettings`; `requestFollower` adds the conversation id to the
+   * outer envelope, yielding:
+   * `{ conversationId, threadSettings }`.
+   */
+  async updateThreadSettings(
+    conversationId: string,
+    threadSettings: JsonObject,
+    options: RequestOptions & { ownerClientId?: string } = {},
+  ): Promise<JsonValue | undefined> {
+    if (!isJsonObject(threadSettings)) {
+      throw new CodexIpcError("thread settings must be a JSON object", { code: "invalid-thread-settings" });
+    }
+    const response = await this.requestFollower(
+      "thread-follower-update-thread-settings",
+      conversationId,
+      { threadSettings: cloneJson(threadSettings) },
+      options,
+    );
+    return response.result;
+  }
+
+  /** Alias matching the official app-server manager method name. */
+  async updateThreadSettingsForNextTurn(
+    conversationId: string,
+    threadSettings: JsonObject,
+    options: RequestOptions & { ownerClientId?: string } = {},
+  ): Promise<JsonValue | undefined> {
+    return this.updateThreadSettings(conversationId, threadSettings, options);
+  }
+
+  async interruptTurn(conversationId: string, options: FollowerInterruptOptions = {}): Promise<JsonValue | undefined> {
+    const params: JsonObject = { mode: options.mode ?? "user-stop" };
+    if (options.expectedTurnId !== undefined && options.expectedTurnId !== null) params.expectedTurnId = options.expectedTurnId;
+    const response = await this.requestFollower("thread-follower-interrupt-turn", conversationId, params, {
+      ownerClientId: options.ownerClientId,
+      timeoutMs: options.timeoutMs,
+    });
+    return response.result;
+  }
+
+  async loadCompleteHistory(conversationId: string, options: RequestOptions & { ownerClientId?: string } = {}): Promise<JsonValue | undefined> {
+    const response = await this.requestFollower("thread-follower-load-complete-history", conversationId, {}, options);
+    return response.result;
+  }
+
+  async respondCommandApproval(conversationId: string, requestId: IpcRequestId, decision: JsonValue, options: RequestOptions & { ownerClientId?: string } = {}): Promise<JsonValue | undefined> {
+    return this.respondFollower("thread-follower-command-approval-decision", conversationId, { requestId, decision }, options);
+  }
+
+  async respondFileApproval(conversationId: string, requestId: IpcRequestId, decision: JsonValue, options: RequestOptions & { ownerClientId?: string } = {}): Promise<JsonValue | undefined> {
+    return this.respondFollower("thread-follower-file-approval-decision", conversationId, { requestId, decision }, options);
+  }
+
+  async respondPermissionsApproval(conversationId: string, requestId: IpcRequestId, response: JsonValue, options: RequestOptions & { ownerClientId?: string } = {}): Promise<JsonValue | undefined> {
+    return this.respondFollower("thread-follower-permissions-request-approval-response", conversationId, { requestId, response }, options);
+  }
+
+  async respondUserInput(conversationId: string, requestId: IpcRequestId, response: JsonValue, options: RequestOptions & { ownerClientId?: string } = {}): Promise<JsonValue | undefined> {
+    return this.respondFollower("thread-follower-submit-user-input", conversationId, { requestId, response }, options);
+  }
+
+  async respondMcpElicitation(conversationId: string, requestId: IpcRequestId, response: JsonValue, options: RequestOptions & { ownerClientId?: string } = {}): Promise<JsonValue | undefined> {
+    return this.respondFollower("thread-follower-submit-mcp-server-elicitation-response", conversationId, { requestId, response }, options);
+  }
+
+  private async respondFollower(method: string, conversationId: string, params: JsonObject, options: RequestOptions & { ownerClientId?: string }): Promise<JsonValue | undefined> {
+    const response = await this.requestFollower(method, conversationId, params, options);
+    return response.result;
+  }
+
+  async dispose(): Promise<void> {
+    this.disposed = true;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = undefined;
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new CodexIpcError("IPC client disposed", { code: "disposed" }));
+    }
+    this.pending.clear();
+    this.socket?.destroy();
+    this.socket = undefined;
+    this.clientId = INITIALIZING_CLIENT_ID;
+  }
+
+  private write(message: IpcMessage): void {
+    if (!this.socket?.writable) throw new CodexIpcError("IPC socket is not connected", { code: "not-connected" });
+    this.socket.write(encodeIpcFrame(message, this.options.maxFrameBytes));
+  }
+
+  private handleMessage(message: IpcMessage): void {
+    for (const listener of this.messageListeners) safeCall(listener, message, (error) => this.emitError(error));
+    switch (message.type) {
+      case "response":
+        this.handleResponse(message);
+        return;
+      case "broadcast":
+        this.handleBroadcast(message);
+        return;
+      case "client-discovery-request":
+        this.handleDiscoveryRequest(message).catch((error) => this.emitError(asError(error)));
+        return;
+      case "request":
+        this.handleUnexpectedRequest(message);
+        return;
+      case "client-discovery-response":
+        // Discovery responses are consumed by the router, not by clients.
+        return;
+    }
+  }
+
+  private handleResponse(response: IpcResponse): void {
+    const key = requestIdKey(response.requestId);
+    const pending = this.pending.get(key);
+    if (!pending) return;
+    this.pending.delete(key);
+    clearTimeout(pending.timer);
+    pending.resolve(response);
+  }
+
+  private handleBroadcast(frame: IpcBroadcast): void {
+    if (!hasTarget(frame, this.clientId)) return;
+    for (const listener of this.broadcastListeners) safeCall(listener, frame, (error) => this.emitError(error));
+    if (frame.method === "thread-stream-state-changed") {
+      this.handleStreamStateBroadcast(frame);
+    } else if (frame.method === "thread-stream-following-status-requested") {
+      this.handleFollowingStatusRequested(frame);
+    }
+  }
+
+  /** Re-announce active subscriptions when an owner reconnects or hands off. */
+  private handleFollowingStatusRequested(frame: IpcBroadcast): void {
+    if (!isRecord(frame.params)) return;
+    if (this.options.strictVersions
+      && frame.version !== CODEX_IPC_METHOD_VERSIONS["thread-stream-following-status-requested"]) {
+      this.emitError(new CodexIpcError(`Unsupported thread following status version ${frame.version}`, { code: "version-mismatch" }));
+      return;
+    }
+    const conversationId = typeof frame.params.conversationId === "string"
+      ? frame.params.conversationId
+      : undefined;
+    const hostId = typeof frame.params.hostId === "string" ? frame.params.hostId : "local";
+    const requester = frame.sourceClientId;
+    if (!conversationId || !requester || requester === this.clientId) return;
+    if (this.followed.get(conversationId) !== hostId) return;
+    void this.followConversation(conversationId, true, {
+      hostId,
+      targetClientIds: [requester],
+    }).catch((error) => this.emitError(asError(error)));
+  }
+
+  private handleStreamStateBroadcast(frame: IpcBroadcast): void {
+    if (!isRecord(frame.params)) return;
+    const conversationId = typeof frame.params.conversationId === "string" ? frame.params.conversationId : undefined;
+    const hostId = typeof frame.params.hostId === "string" ? frame.params.hostId : "local";
+    const change = frame.params.change;
+    if (!conversationId || !isRecord(change) || typeof change.type !== "string") return;
+    if (this.options.strictVersions && frame.version !== CODEX_IPC_METHOD_VERSIONS["thread-stream-state-changed"]) {
+      this.emitError(new CodexIpcError(`Unsupported thread stream version ${frame.version}`, { code: "version-mismatch" }));
+      return;
+    }
+    const ownerClientId = frame.sourceClientId ?? "";
+    if (change.type === "snapshot") {
+      if (typeof change.revision !== "number" || !isJsonObject(change.conversationState)) return;
+      const state: ConversationStreamState = {
+        conversationId,
+        hostId,
+        ownerClientId,
+        revision: change.revision,
+        conversationState: cloneJson(change.conversationState),
+      };
+      this.streams.set(conversationId, state);
+      this.emitStream({ kind: "snapshot", ...state, raw: frame });
+      return;
+    }
+    if (change.type !== "patches" || typeof change.baseRevision !== "number" || typeof change.revision !== "number" || !Array.isArray(change.patches)) return;
+    const current = this.streams.get(conversationId);
+    if (!current || current.ownerClientId !== ownerClientId || current.revision !== change.baseRevision) {
+      const expectedRevision = current?.revision ?? 0;
+      this.emitStream({
+        kind: "desync",
+        conversationId,
+        hostId,
+        ownerClientId,
+        expectedRevision,
+        receivedBaseRevision: change.baseRevision,
+        receivedRevision: change.revision,
+        raw: frame,
+      });
+      // Re-sending `following:true` is how the official follower asks the
+      // owner for a fresh snapshot when a patch base revision is missed.
+      if (this.followed.has(conversationId)) {
+        this.followConversation(conversationId, true, { hostId }).catch((error) => this.emitError(asError(error)));
+      }
+      return;
+    }
+    try {
+      const patches = change.patches as unknown as IpcJsonPatch[];
+      const nextConversationState = applyIpcPatches(current.conversationState, patches);
+      if (!isJsonObject(nextConversationState)) throw new CodexIpcError("Patched conversation state is not an object", { code: "invalid-patch" });
+      const next: ConversationStreamState = {
+        ...current,
+        revision: change.revision,
+        conversationState: nextConversationState,
+      };
+      this.streams.set(conversationId, next);
+      this.emitStream({ kind: "patches", ...next, patches, baseRevision: change.baseRevision, raw: frame });
+    } catch (error) {
+      this.emitError(asError(error));
+    }
+  }
+
+  private async handleDiscoveryRequest(message: IpcClientDiscoveryRequest): Promise<void> {
+    const request = message.request;
+    let canHandle = false;
+    try {
+      canHandle = this.discoveryHandler ? await this.discoveryHandler(request) : false;
+    } catch {
+      canHandle = false;
+    }
+    this.write({
+      type: "client-discovery-response",
+      requestId: message.requestId,
+      response: { canHandle },
+    });
+  }
+
+  private handleUnexpectedRequest(request: IpcRequest): void {
+    try {
+      this.write({
+        type: "response",
+        requestId: request.requestId,
+        resultType: "error",
+        error: "no-handler-for-request",
+      });
+    } catch (error) {
+      this.emitError(asError(error));
+    }
+  }
+
+  private async resubscribeAfterConnect(): Promise<void> {
+    const subscriptions = [...this.followed.entries()];
+    for (const [conversationId, hostId] of subscriptions) {
+      this.write({
+        type: "broadcast",
+        method: "thread-stream-following-changed",
+        sourceClientId: this.clientId,
+        version: CODEX_IPC_METHOD_VERSIONS["thread-stream-following-changed"],
+        params: { conversationId, hostId, following: true },
+      });
+    }
+  }
+
+  private handleClose(): void {
+    const socket = this.socket;
+    this.socket = undefined;
+    this.decoder.reset();
+    const closeError = new CodexIpcError("IPC socket closed", { code: "connection-closed" });
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(closeError);
+    }
+    this.pending.clear();
+    this.clientId = INITIALIZING_CLIENT_ID;
+    for (const listener of this.closeListeners) safeCall(listener, closeError, (error) => this.emitError(error));
+    if (!this.disposed && this.options.autoReconnect && socket) {
+      this.reconnectTimer = setTimeout(() => {
+        this.reconnectTimer = undefined;
+        this.connect().catch((error) => this.emitError(asError(error)));
+      }, this.options.reconnectDelayMs);
+    }
+  }
+
+  private emitStream(event: ConversationStreamEvent): void {
+    for (const listener of this.streamListeners) safeCall(listener, event, (error) => this.emitError(error));
+  }
+
+  private emitError(error: Error): void {
+    for (const listener of this.errorListeners) safeCall(listener, error, () => undefined);
+  }
+}
+
+function safeCall<T>(listener: Listener<T>, value: T, onError: (error: Error) => void): void {
+  try {
+    listener(value);
+  } catch (error) {
+    onError(asError(error));
+  }
+}
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}

aether-vscodex/vscode-extension/src/codexPath.ts

@@ -0,0 +1,152 @@
+import { accessSync, constants, Dirent, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, isAbsolute, join, sep } from "node:path";
+
+export interface CodexPathOptions {
+  /** Environment used for PATH lookup. Defaults to the extension host environment. */
+  env?: NodeJS.ProcessEnv;
+  /** Home directory used when looking for bundled installations. */
+  homeDir?: string;
+  /** Platform override for deterministic tests. */
+  platform?: NodeJS.Platform;
+}
+
+/**
+ * Resolve the executable used by the VS Code bridge.
+ *
+ * VS Code launched from Finder/Dock often receives a smaller PATH than a shell.
+ * The default `codex` command therefore gets a few explicit installation
+ * fallbacks, while a user-supplied command remains authoritative.
+ */
+export function resolveCodexCommand(configuredCommand = "codex", options: CodexPathOptions = {}): string {
+  const command = configuredCommand.trim() || "codex";
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+  const home = options.homeDir ?? homedir();
+
+  if (hasPathComponent(command, platform)) {
+    const resolved = executablePath(command, platform);
+    if (resolved) return resolved;
+    throw missingCodexError(command, platform);
+  }
+
+  const fromPath = findOnPath(command, env.PATH, platform, env.PATHEXT);
+  if (fromPath) return fromPath;
+
+  // Only the default command gets installation-specific fallbacks. A custom
+  // bare command should fail loudly instead of silently running another binary.
+  if (!isDefaultCommand(command, platform)) throw missingCodexError(command, platform);
+
+  for (const candidate of bundledCandidates(home, platform)) {
+    const resolved = executablePath(candidate, platform);
+    if (resolved) return resolved;
+  }
+
+  throw missingCodexError(command, platform);
+}
+
+export function missingCodexError(command: string, platform: NodeJS.Platform = process.platform): Error {
+  const examples = platform === "darwin"
+    ? ' Set "codexRemoteCollab.codexCommand" to the full path, for example "/Applications/ChatGPT.app/Contents/Resources/codex".'
+    : ' Set "codexRemoteCollab.codexCommand" to the full path of the Codex executable.';
+  return new Error(`Codex executable "${command}" was not found.${examples}`);
+}
+
+function isDefaultCommand(command: string, platform: NodeJS.Platform): boolean {
+  return platform === "win32" ? command.toLowerCase() === "codex" || command.toLowerCase() === "codex.exe" : command === "codex";
+}
+
+function hasPathComponent(command: string, platform: NodeJS.Platform): boolean {
+  return isAbsolute(command) || command.includes(sep) || (platform === "win32" && command.includes("\\"));
+}
+
+function executablePath(candidate: string, platform: NodeJS.Platform): string | undefined {
+  try {
+    const info = statSync(candidate);
+    if (!info.isFile()) return undefined;
+    // X_OK is meaningful on POSIX; Windows still benefits from the file check.
+    if (platform !== "win32") accessSync(candidate, constants.X_OK);
+    return candidate;
+  } catch {
+    return undefined;
+  }
+}
+
+function findOnPath(command: string, pathValue: string | undefined, platform: NodeJS.Platform, pathextValue?: string): string | undefined {
+  if (!pathValue) return undefined;
+  const extensions = platform === "win32" ? windowsExtensions(command, pathextValue) : [""];
+  for (const directory of pathValue.split(delimiter)) {
+    if (!directory) continue;
+    for (const extension of extensions) {
+      const candidate = join(directory, `${command}${extension}`);
+      const resolved = executablePath(candidate, platform);
+      if (resolved) return resolved;
+    }
+  }
+  return undefined;
+}
+
+function windowsExtensions(command: string, pathextValue: string | undefined): string[] {
+  if (/[.][^./\\]+$/.test(command)) return [""];
+  const extensions = (pathextValue ?? ".COM;.EXE;.BAT;.CMD")
+    .split(";")
+    .map((value) => value.trim())
+    .filter(Boolean);
+  return ["", ...extensions];
+}
+
+function bundledCandidates(home: string, platform: NodeJS.Platform): string[] {
+  if (platform !== "darwin") return [];
+
+  const candidates = [
+    join(home, "Applications", "ChatGPT.app", "Contents", "Resources", "codex"),
+    "/Applications/ChatGPT.app/Contents/Resources/codex",
+    join(home, ".local", "bin", "codex"),
+    join(home, ".npm-global", "bin", "codex"),
+  ];
+
+  for (const extensionsRoot of [
+    join(home, ".vscode", "extensions"),
+    join(home, ".vscode-insiders", "extensions"),
+  ]) {
+    candidates.push(...officialExtensionCandidates(extensionsRoot));
+  }
+  return candidates;
+}
+
+function officialExtensionCandidates(extensionsRoot: string): string[] {
+  let entries: Dirent<string>[];
+  try {
+    entries = readdirSync(extensionsRoot, { withFileTypes: true, encoding: "utf8" });
+  } catch {
+    return [];
+  }
+
+  const matches = entries
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith("openai.chatgpt-"))
+    .map((entry) => {
+      const directory = join(extensionsRoot, entry.name);
+      let modified = 0;
+      try {
+        modified = statSync(directory).mtimeMs;
+      } catch {
+        // Keep an unreadable entry at the end of the deterministic sort.
+      }
+      return { directory, modified };
+    })
+    .sort((left, right) => right.modified - left.modified || right.directory.localeCompare(left.directory));
+
+  const candidates: string[] = [];
+  for (const match of matches) {
+    let architectures: Dirent<string>[];
+    try {
+      architectures = readdirSync(join(match.directory, "bin"), { withFileTypes: true, encoding: "utf8" });
+    } catch {
+      continue;
+    }
+    for (const architecture of architectures) {
+      if (architecture.isDirectory()) candidates.push(join(match.directory, "bin", architecture.name, "codex"));
+    }
+  }
+  return candidates;
+}

aether-vscodex/vscode-extension/src/compositeRelay.ts

@@ -0,0 +1,131 @@
+import { Disposable, RelayFrame, RelayTransport } from "./protocol";
+
+export interface NamedRelayTransport {
+  id: string;
+  transport: RelayTransport;
+  required?: boolean;
+}
+
+/**
+ * Fans host events out to local and cloud relays while presenting one
+ * transport lifecycle to RelayHost. A temporary cloud outage must not stop
+ * the local bridge (and vice versa).
+ */
+export class CompositeRelayTransport implements RelayTransport {
+  readonly handlesHandshake = true;
+  private readonly entries: NamedRelayTransport[];
+  private readonly subscriptions: Disposable[] = [];
+  private readonly openEntries = new Set<string>();
+  private readonly messageListeners = new Set<(frame: RelayFrame) => void>();
+  private readonly openListeners = new Set<() => void>();
+  private readonly closeListeners = new Set<(error?: Error) => void>();
+  private started = false;
+  private sessionId?: string;
+
+  constructor(entries: NamedRelayTransport[]) {
+    if (entries.length === 0) throw new Error("CompositeRelayTransport requires at least one relay");
+    const ids = new Set<string>();
+    for (const entry of entries) {
+      if (!entry.id || ids.has(entry.id)) throw new Error(`duplicate relay id: ${entry.id || "(empty)"}`);
+      ids.add(entry.id);
+    }
+    this.entries = [...entries];
+  }
+
+  setSessionId(sessionId: string): void {
+    this.sessionId = sessionId;
+    for (const { transport } of this.entries) {
+      (transport as RelayTransport & { setSessionId?: (value: string) => void }).setSessionId?.(sessionId);
+    }
+  }
+
+  async connect(): Promise<void> {
+    if (this.started) return;
+    this.started = true;
+    this.bindTransports();
+    if (this.sessionId) this.setSessionId(this.sessionId);
+
+    const results = await Promise.allSettled(this.entries.map(({ transport }) => transport.connect()));
+    const failures = results
+      .map((result, index) => ({ result, entry: this.entries[index] }))
+      .filter((item): item is { result: PromiseRejectedResult; entry: NamedRelayTransport } => item.result.status === "rejected");
+    const requiredFailure = failures.find(({ entry }) => entry.required);
+    const connected = results.length - failures.length;
+    if (requiredFailure || connected === 0) {
+      this.started = false;
+      this.disposeSubscriptions();
+      for (const { transport } of this.entries) transport.close();
+      const detail = failures.map(({ entry, result }) => `${entry.id}: ${errorMessage(result.reason)}`).join("; ");
+      throw new Error(`unable to connect relay${failures.length === 1 ? "" : "s"}: ${detail}`);
+    }
+  }
+
+  send(frame: RelayFrame): void {
+    const failures: string[] = [];
+    for (const { id, transport } of this.entries) {
+      try {
+        transport.send(frame);
+      } catch (error) {
+        failures.push(`${id}: ${errorMessage(error)}`);
+      }
+    }
+    if (failures.length === this.entries.length) {
+      throw new Error(`all relay sends failed: ${failures.join("; ")}`);
+    }
+  }
+
+  onMessage(listener: (frame: RelayFrame) => void): Disposable {
+    this.messageListeners.add(listener);
+    return { dispose: () => this.messageListeners.delete(listener) };
+  }
+
+  onOpen(listener: () => void): Disposable {
+    this.openListeners.add(listener);
+    return { dispose: () => this.openListeners.delete(listener) };
+  }
+
+  onClose(listener: (error?: Error) => void): Disposable {
+    this.closeListeners.add(listener);
+    return { dispose: () => this.closeListeners.delete(listener) };
+  }
+
+  isConnected(id: string): boolean {
+    return this.openEntries.has(id);
+  }
+
+  close(): void {
+    this.started = false;
+    this.openEntries.clear();
+    this.disposeSubscriptions();
+    for (const { transport } of this.entries) transport.close();
+  }
+
+  private bindTransports(): void {
+    for (const { id, transport } of this.entries) {
+      this.subscriptions.push(transport.onMessage((frame) => {
+        for (const listener of this.messageListeners) listener(frame);
+      }));
+      if (transport.onOpen) this.subscriptions.push(transport.onOpen(() => {
+        this.openEntries.add(id);
+        // RelayHost publishes an authoritative snapshot after an authenticated
+        // reconnect. Surface every member reconnect so a recovered cloud relay
+        // is hydrated even while the local relay remained online.
+        for (const listener of this.openListeners) listener();
+      }));
+      if (transport.onClose) this.subscriptions.push(transport.onClose((error) => {
+        const wasOpen = this.openEntries.delete(id);
+        if (wasOpen && this.openEntries.size === 0) {
+          for (const listener of this.closeListeners) listener(error);
+        }
+      }));
+    }
+  }
+
+  private disposeSubscriptions(): void {
+    for (const subscription of this.subscriptions.splice(0)) subscription.dispose();
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

aether-vscodex/vscode-extension/src/extension.ts

@@ -0,0 +1,574 @@
+import { hostname } from "node:os";
+
+import * as vscode from "vscode";
+
+import { CodexAgentAdapter } from "./codexAgentAdapter";
+import { resolveCodexCommand } from "./codexPath";
+import { CodexIpcAgentAdapter } from "./codexIpcAgentAdapter";
+import { CompositeRelayTransport } from "./compositeRelay";
+import { LocalRelayController, localRelayTarget } from "./localRelay";
+import { AgentAdapter, ControlMode, Disposable, JsonObject, Logger } from "./protocol";
+import { RelayClient } from "./relayClient";
+import { RelayHost } from "./relayHost";
+import { SwitchableAgentAdapter } from "./switchableAgentAdapter";
+
+let activeHost: RelayHost | undefined;
+let activeAdapter: AgentAdapter | undefined;
+let activeRelay: CompositeRelayTransport | undefined;
+let activeAdapterStatusSubscription: Disposable | undefined;
+let statusItem: vscode.StatusBarItem | undefined;
+let autoStartRetryTimer: NodeJS.Timeout | undefined;
+let autoStartRetryMs = 3_000;
+let localRelayController: LocalRelayController | undefined;
+const t = (message: string, ...args: Array<string | number | boolean>): string => vscode.l10n.t(message, ...args);
+
+export async function activate(context: vscode.ExtensionContext): Promise<void> {
+  const output = vscode.window.createOutputChannel(t("Codex Remote Collaboration"));
+  context.subscriptions.push(output);
+  const logger = {
+    debug: (message: string, ...args: unknown[]) => output.appendLine(`[debug] ${message} ${formatArgs(args)}`),
+    info: (message: string, ...args: unknown[]) => output.appendLine(`[info] ${message} ${formatArgs(args)}`),
+    warn: (message: string, ...args: unknown[]) => output.appendLine(`[warn] ${message} ${formatArgs(args)}`),
+    error: (message: string, ...args: unknown[]) => output.appendLine(`[error] ${message} ${formatArgs(args)}`),
+  };
+  localRelayController = new LocalRelayController({ extensionPath: context.extensionPath, logger });
+
+  statusItem = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Right, 100);
+  statusItem.command = "codexRemoteCollab.openWeb";
+  statusItem.text = "$(plug) Codex Remote";
+  statusItem.tooltip = t("Connecting to the local Codex collaboration service");
+  statusItem.show();
+  context.subscriptions.push(statusItem);
+
+  const start = async (automatic = false): Promise<void> => {
+    if (!automatic && autoStartRetryTimer) {
+      clearTimeout(autoStartRetryTimer);
+      autoStartRetryTimer = undefined;
+    }
+    if (activeHost) {
+      if (!automatic) vscode.window.showInformationMessage(t("The Codex remote bridge is already running."));
+      return;
+    }
+    const configuration = vscode.workspace.getConfiguration("codexRemoteCollab");
+    const relayConfiguration = resolveRelayConfiguration(configuration);
+    const localRelayUrl = relayConfiguration.localUrl;
+    if (!localRelayUrl) {
+      vscode.window.showWarningMessage(t("Set codexRemoteCollab.localRelayUrl before starting the bridge."));
+      return;
+    }
+    const localTarget = localRelayTarget(localRelayUrl);
+    if (!localTarget) {
+      vscode.window.showErrorMessage(t("codexRemoteCollab.localRelayUrl must be a loopback ws:// address."));
+      return;
+    }
+    if (localTarget && configuration.get<boolean>("autoStartLocalRelay", true)) {
+      setStatus("$(sync~spin) Codex Remote", t("Starting {0}", localTarget.webUrl), "codexRemoteCollab.openWeb");
+      try {
+        await localRelayController?.ensureRunning(localRelayUrl);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        setStatus("$(error) Codex Remote", t("Unable to start the local collaboration service: {0}", message), "codexRemoteCollab.openWeb");
+        if (automatic) {
+          logger.warn(`Automatic local relay start failed; retrying in ${autoStartRetryMs}ms`, error);
+          scheduleAutoStartRetry(start);
+        } else {
+          vscode.window.showErrorMessage(t("Unable to start the local Codex collaboration service: {0}", message));
+        }
+        return;
+      }
+    }
+    const legacyToken = await context.secrets.get("codexRemoteCollab.relayToken");
+    const localToken = relayConfiguration.legacyRemote ? undefined : legacyToken;
+    if (!localToken) logger.info("Using the loopback-only unauthenticated local relay");
+    const initialControlMode = resolveInitialControlMode(configuration);
+    let currentControlMode: ControlMode = initialControlMode;
+    const createAdapter = (controlMode: ControlMode): AgentAdapter => {
+      if (controlMode === "sync") {
+        const configuredThreadId = configuration.get<string>("threadId", "").trim();
+        const socketPath = configuration.get<string>("ipcSocketPath", "").trim();
+        logger.info(`Synchronous mode enabled; following the VS Code Codex panel${configuredThreadId ? ` (initial conversation ${configuredThreadId})` : ""}`);
+        return new CodexIpcAgentAdapter({
+          threadId: configuredThreadId || undefined,
+          socketPath: socketPath || undefined,
+          hostId: configuration.get<string>("hostId", "local"),
+          autoDiscoverThread: configuration.get<boolean>("autoDiscoverThread", true),
+          // Synchronous mode has one navigation owner: the official panel.
+          followVscodeSession: true,
+          preferredCwds: workspaceRoots(),
+          strictVersions: configuration.get<boolean>("ipcStrictVersions", true),
+          logger,
+          approvalTimeoutMs: configuration.get<number>("approvalTimeoutMs", 300_000),
+          openNewSession: () => openOfficialNewSession(logger),
+        });
+      }
+
+      const configuredCommand = configuration.get<string>("codexCommand", "codex");
+      const command = resolveCodexCommand(configuredCommand);
+      const args = configuration.get<string[]>("codexArgs", ["app-server", "--stdio"]);
+      const defaultCwd = configuration.get<string>("defaultCwd", "") || firstWorkspaceRoot();
+      logger.info(`Asynchronous mode enabled; using independent Codex executable: ${command}`);
+      return new CodexAgentAdapter({
+        command,
+        args,
+        defaultCwd: defaultCwd || undefined,
+        logger,
+        approvalTimeoutMs: configuration.get<number>("approvalTimeoutMs", 300_000),
+      });
+    };
+    const adapter = new SwitchableAgentAdapter({
+      initialMode: initialControlMode,
+      createAdapter,
+      logger,
+      onModeChanged: async (nextMode) => {
+        currentControlMode = nextMode;
+        await configuration.update("controlMode", nextMode, vscode.ConfigurationTarget.Global);
+        setControlModeStatus(nextMode, nextMode === "async" || Boolean((await adapter.snapshot()).threadId));
+      },
+    });
+    const localRelay = new RelayClient({
+      url: localRelayUrl,
+      ...(localToken ? { accessToken: localToken } : {}),
+      reconnect: configuration.get<boolean>("relayReconnect", true),
+      logger,
+    });
+    const relayEntries = [{ id: "local", transport: localRelay, required: true }];
+    const cloudRelayUrl = relayConfiguration.cloudUrl;
+    const cloudToken = await context.secrets.get("codexRemoteCollab.cloudRelayToken")
+      ?? (relayConfiguration.legacyRemote ? legacyToken : undefined);
+    if (cloudRelayUrl && cloudToken) {
+      relayEntries.push({
+        id: "aether-cloud",
+        transport: new RelayClient({
+          url: cloudRelayUrl,
+          accessToken: cloudToken,
+          reconnect: configuration.get<boolean>("relayReconnect", true),
+          logger,
+        }),
+        required: false,
+      });
+      logger.info(`Aether cloud relay enabled: ${cloudRelayUrl}`);
+    } else if (cloudRelayUrl) {
+      logger.warn("Aether cloud relay URL is configured without a device credential; cloud sync is disabled until pairing is completed");
+    }
+    const relay = new CompositeRelayTransport(relayEntries);
+    const capabilities = ["read_output", "send_task_input", "cancel_task", "approve_low_risk"];
+    if (configuration.get<boolean>("allowHighRiskApprovals", false)) capabilities.push("approve_high_risk");
+    const host = new RelayHost({ adapter, relay, logger, capabilities });
+    let controlReady = initialControlMode === "async";
+    activeAdapterStatusSubscription?.dispose();
+    const adapterStatusSubscription = adapter.onEvent((event) => {
+      if (activeAdapter !== adapter) return;
+      if (event.type === "control.mode.changed") {
+        const changedMode = event.payload.controlMode;
+        if (changedMode === "sync" || changedMode === "async") currentControlMode = changedMode;
+      }
+      if (event.type !== "session.snapshot") return;
+      const metadata = event.payload.metadata;
+      if (metadata !== null && typeof metadata === "object" && !Array.isArray(metadata)) {
+        const snapshotMode = (metadata as JsonObject).controlMode;
+        if (snapshotMode === "sync" || snapshotMode === "async") currentControlMode = snapshotMode;
+      }
+      const waiting = event.payload.state === "waiting_for_host"
+        || (metadata !== null && typeof metadata === "object" && !Array.isArray(metadata)
+          && (metadata as JsonObject).waitingForSession === true);
+      const threadId = event.threadId
+        ?? (typeof event.payload.threadId === "string" ? event.payload.threadId : undefined);
+      controlReady = currentControlMode === "async" || (Boolean(threadId) && !waiting);
+      setControlModeStatus(currentControlMode, controlReady);
+    });
+    activeAdapterStatusSubscription = adapterStatusSubscription;
+    activeAdapter = adapter;
+    activeRelay = relay;
+    activeHost = host;
+    if (configuration.get<boolean>("autoStartLocalRelay", true)) {
+      localRelay.onClose(() => {
+        if (activeHost !== host) return;
+        setStatus("$(sync~spin) Codex Remote", t("Restoring the local collaboration service"), "codexRemoteCollab.openWeb");
+        void localRelayController?.ensureRunning(localRelayUrl).catch((error) => {
+          logger.warn("Unable to recover bundled local relay", error);
+          setStatus("$(error) Codex Remote", t("Unable to restore the local collaboration service"), "codexRemoteCollab.openWeb");
+        });
+      });
+      localRelay.onOpen(() => {
+        if (activeHost === host) {
+          setControlModeStatus(currentControlMode, controlReady);
+        }
+      });
+    }
+    try {
+      await host.start();
+      autoStartRetryMs = 3_000;
+      const snapshot = await adapter.snapshot();
+      const snapshotMode = snapshot.metadata?.controlMode;
+      if (snapshotMode === "sync" || snapshotMode === "async") currentControlMode = snapshotMode;
+      controlReady = currentControlMode === "async" || Boolean(snapshot.threadId);
+      setControlModeStatus(currentControlMode, controlReady);
+      if (!automatic && (currentControlMode === "async" || controlReady)) {
+        vscode.window.showInformationMessage(currentControlMode === "sync"
+          ? t("The Codex remote bridge attached to the existing VS Code Codex conversation.")
+          : t("The independent Codex remote mode connected."));
+      }
+    } catch (error) {
+      activeHost = undefined;
+      activeAdapter = undefined;
+      activeRelay = undefined;
+      if (activeAdapterStatusSubscription === adapterStatusSubscription) {
+        activeAdapterStatusSubscription.dispose();
+        activeAdapterStatusSubscription = undefined;
+      }
+      await host.stop().catch(() => undefined);
+      const message = error instanceof Error ? error.message : String(error);
+      if (initialControlMode === "sync" && isAttachSessionUnavailable(message)) {
+        setStatus("$(sync~spin) Codex Remote", t("Waiting for a Codex conversation to open in VS Code. It will connect automatically."), "codexRemoteCollab.openWeb");
+        logger.info(`No attachable VS Code Codex session is available; retrying in ${autoStartRetryMs}ms`);
+        scheduleAutoStartRetry(start);
+        return;
+      }
+      setStatus("$(error) Codex Remote", initialControlMode === "sync" ? t("The Codex conversation is not connected") : t("The independent Codex mode is not connected"), "codexRemoteCollab.openWeb");
+      if (automatic) {
+        logger.warn(`Automatic bridge start failed; retrying in ${autoStartRetryMs}ms`, error);
+        scheduleAutoStartRetry(start);
+      } else {
+        const detail = localTarget && /ECONNREFUSED|connect refused/i.test(message)
+          ? t("The local collaboration service at {0} is temporarily unavailable. The extension will keep retrying.", localTarget.webUrl)
+          : t("Unable to start the Codex remote bridge: {0}", message);
+        vscode.window.showErrorMessage(detail);
+      }
+    }
+  };
+
+  const stop = async (): Promise<void> => {
+    if (autoStartRetryTimer) {
+      clearTimeout(autoStartRetryTimer);
+      autoStartRetryTimer = undefined;
+    }
+    autoStartRetryMs = 3_000;
+    const host = activeHost;
+    activeHost = undefined;
+    activeAdapter = undefined;
+    activeRelay = undefined;
+    activeAdapterStatusSubscription?.dispose();
+    activeAdapterStatusSubscription = undefined;
+    if (host) await host.stop();
+    setStatus("$(plug) Codex Remote", t("Bridge paused. Click to open the web control and resume automatically."), "codexRemoteCollab.openWeb");
+  };
+
+  context.subscriptions.push(vscode.commands.registerCommand("codexRemoteCollab.openWeb", async () => {
+    const localRelayUrl = resolveRelayConfiguration(vscode.workspace.getConfiguration("codexRemoteCollab")).localUrl;
+    const webUrl = localRelayController?.getWebUrl(localRelayUrl);
+    if (!webUrl) {
+      vscode.window.showErrorMessage(t("The local collaboration URL is invalid. Check codexRemoteCollab.localRelayUrl."));
+      return;
+    }
+    if (!activeHost) await start(false);
+    if (activeHost) await vscode.env.openExternal(vscode.Uri.parse(webUrl));
+  }));
+  context.subscriptions.push(vscode.commands.registerCommand("codexRemoteCollab.start", start));
+  context.subscriptions.push(vscode.commands.registerCommand("codexRemoteCollab.stop", stop));
+  context.subscriptions.push(vscode.commands.registerCommand("codexRemoteCollab.setThreadId", async () => {
+    const configuration = vscode.workspace.getConfiguration("codexRemoteCollab");
+    const current = configuration.get<string>("threadId", "");
+    const value = await vscode.window.showInputBox({
+      prompt: t("Existing Codex conversation ID (leave blank for auto-discovery)"),
+      value: current,
+      ignoreFocusOut: true,
+    });
+    if (value === undefined) return;
+    await configuration.update("threadId", value.trim(), vscode.ConfigurationTarget.Global);
+    vscode.window.showInformationMessage(value.trim()
+      ? t("Codex Remote will attach to {0} after the next bridge start.", value.trim())
+      : t("Codex Remote will auto-discover the latest VS Code Codex conversation after the next bridge start."));
+  }));
+  context.subscriptions.push(vscode.commands.registerCommand("codexRemoteCollab.setRelayToken", async () => {
+    const token = await vscode.window.showInputBox({ prompt: t("Relay access token (leave blank for the local relay)"), password: true, ignoreFocusOut: true });
+    if (token === undefined) return;
+    await context.secrets.store("codexRemoteCollab.relayToken", token);
+    vscode.window.showInformationMessage(t("Relay token stored in VS Code SecretStorage."));
+  }));
+  context.subscriptions.push(vscode.commands.registerCommand("codexRemoteCollab.configureCloud", async () => {
+    const configuration = vscode.workspace.getConfiguration("codexRemoteCollab");
+    const currentUrl = configuration.get<string>("cloudRelayUrl", "");
+    const url = await vscode.window.showInputBox({
+      prompt: t("Aether cloud relay WebSocket URL"),
+      value: currentUrl,
+      placeHolder: "wss://aether.example.com/api/vscodex/ws",
+      ignoreFocusOut: true,
+      validateInput: validateCloudRelayUrl,
+    });
+    if (url === undefined) return;
+    if (!url.trim()) {
+      await configuration.update("cloudRelayUrl", "", vscode.ConfigurationTarget.Global);
+      await context.secrets.delete("codexRemoteCollab.cloudRelayToken");
+      vscode.window.showInformationMessage(t("Aether cloud connection removed. Local control remains enabled."));
+      return;
+    }
+    const token = await vscode.window.showInputBox({
+      prompt: t("Device credential from the Aether pairing flow"),
+      password: true,
+      ignoreFocusOut: true,
+    });
+    if (token === undefined) return;
+    if (!token.trim()) {
+      vscode.window.showWarningMessage(t("A non-empty Aether device credential is required."));
+      return;
+    }
+    await configuration.update("cloudRelayUrl", url.trim(), vscode.ConfigurationTarget.Global);
+    await context.secrets.store("codexRemoteCollab.cloudRelayToken", token.trim());
+    vscode.window.showInformationMessage(t("Aether cloud connection saved. Restart the Codex Remote bridge to connect; local control remains available."));
+  }));
+  context.subscriptions.push(vscode.commands.registerCommand("codexRemoteCollab.pairCloud", async () => {
+    const configuration = vscode.workspace.getConfiguration("codexRemoteCollab");
+    const currentBaseUrl = configuration.get<string>("aetherUrl", "");
+    const baseUrl = await vscode.window.showInputBox({
+      prompt: t("Aether server URL"),
+      value: currentBaseUrl,
+      placeHolder: "https://aether.example.com",
+      ignoreFocusOut: true,
+      validateInput: validateAetherBaseUrl,
+    });
+    if (baseUrl === undefined || !baseUrl.trim()) return;
+    const code = await vscode.window.showInputBox({
+      prompt: t("One-time pairing code shown in Aether"),
+      placeHolder: "ABCD-EFGH",
+      ignoreFocusOut: true,
+      validateInput: (value) => normalizePairingCode(value).length === 8 ? undefined : t("Enter the 8-character pairing code."),
+    });
+    if (code === undefined || !code.trim()) return;
+    try {
+      const normalizedBaseUrl = baseUrl.trim().replace(/\/+$/, "");
+      const response = await fetch(`${normalizedBaseUrl}/api/vscodex/pair`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ code: normalizePairingCode(code), name: hostname() || "VS Code" }),
+      });
+      const raw = await response.text();
+      let result: unknown;
+      try {
+        result = JSON.parse(raw);
+      } catch {
+        result = null;
+      }
+      if (!response.ok) {
+        const detail = isJsonRecord(result) && typeof result.error === "string" ? result.error : `HTTP ${response.status}`;
+        throw new Error(detail);
+      }
+      if (!isJsonRecord(result) || typeof result.device_token !== "string" || typeof result.ws_url !== "string") {
+        throw new Error(t("Aether returned an invalid pairing response."));
+      }
+      const wsError = validateCloudRelayUrl(result.ws_url);
+      if (wsError) throw new Error(wsError);
+      await configuration.update("aetherUrl", normalizedBaseUrl, vscode.ConfigurationTarget.Global);
+      await configuration.update("cloudRelayUrl", result.ws_url, vscode.ConfigurationTarget.Global);
+      await context.secrets.store("codexRemoteCollab.cloudRelayToken", result.device_token);
+      if (activeHost) await stop();
+      await start(false);
+      if (!activeHost) return;
+      if (activeRelay?.isConnected("aether-cloud")) {
+        vscode.window.showInformationMessage(t("Aether pairing completed. Local and cloud control are both active."));
+      } else {
+        vscode.window.showWarningMessage(t("Aether pairing was saved, but the cloud connection is currently unavailable. Local control remains active and the cloud connection will retry."));
+      }
+    } catch (error) {
+      vscode.window.showErrorMessage(t("Unable to pair with Aether: {0}", error instanceof Error ? error.message : String(error)));
+    }
+  }));
+  context.subscriptions.push(vscode.commands.registerCommand("codexRemoteCollab.sendInput", async () => {
+    if (!activeAdapter) {
+      vscode.window.showWarningMessage(t("Start the Codex remote bridge first."));
+      return;
+    }
+    const text = await vscode.window.showInputBox({ prompt: t("Send input to the active Codex turn"), ignoreFocusOut: true });
+    if (text === undefined || !text.trim()) return;
+    try {
+      await activeAdapter.sendInput(text);
+    } catch (error) {
+      vscode.window.showErrorMessage(t("Unable to send Codex input: {0}", error instanceof Error ? error.message : String(error)));
+    }
+  }));
+  context.subscriptions.push(vscode.commands.registerCommand("codexRemoteCollab.snapshot", async () => {
+    if (!activeAdapter) return vscode.window.showWarningMessage(t("Start the Codex remote bridge first."));
+    const snapshot = await activeAdapter.snapshot();
+    output.appendLine(JSON.stringify(snapshot));
+    output.show(true);
+  }));
+
+  if (vscode.workspace.getConfiguration("codexRemoteCollab").get<boolean>("autoStart", true)) await start(true);
+}
+
+export async function deactivate(): Promise<void> {
+  if (autoStartRetryTimer) {
+    clearTimeout(autoStartRetryTimer);
+    autoStartRetryTimer = undefined;
+  }
+  const host = activeHost;
+  activeHost = undefined;
+  activeAdapter = undefined;
+  activeAdapterStatusSubscription?.dispose();
+  activeAdapterStatusSubscription = undefined;
+  if (host) await host.stop();
+  const localRelay = localRelayController;
+  localRelayController = undefined;
+  if (localRelay) await localRelay.stop();
+}
+
+function firstWorkspaceRoot(): string | undefined {
+  return vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
+}
+
+function workspaceRoots(): string[] {
+  return (vscode.workspace.workspaceFolders ?? []).map((folder) => folder.uri.fsPath);
+}
+
+function setStatus(text: string, tooltip: string, command?: string): void {
+  if (!statusItem) return;
+  statusItem.text = text;
+  statusItem.tooltip = tooltip;
+  statusItem.command = command;
+}
+
+function setAttachStatus(ready: boolean): void {
+  setStatus(
+    ready ? "$(check) Codex Remote" : "$(sync~spin) Codex Remote",
+    ready ? t("Attached to the existing Codex conversation. Click to open the web control.") : t("Waiting for a Codex conversation to open in VS Code. It will connect automatically."),
+    "codexRemoteCollab.openWeb",
+  );
+}
+
+function setControlModeStatus(mode: ControlMode, ready: boolean): void {
+  if (mode === "sync") {
+    setAttachStatus(ready);
+    return;
+  }
+  setStatus(
+    ready ? "$(check) Codex Remote" : "$(sync~spin) Codex Remote",
+    ready
+      ? t("Independent Codex mode is connected. Click to open the web control.")
+      : t("Starting the independent Codex mode."),
+    "codexRemoteCollab.openWeb",
+  );
+}
+
+function scheduleAutoStartRetry(start: (automatic?: boolean) => Promise<void>): void {
+  if (autoStartRetryTimer) return;
+  const delay = autoStartRetryMs;
+  autoStartRetryMs = Math.min(autoStartRetryMs * 2, 30_000);
+  autoStartRetryTimer = setTimeout(() => {
+    autoStartRetryTimer = undefined;
+    void start(true);
+  }, delay);
+}
+
+function formatArgs(args: unknown[]): string {
+  return args.length ? args.map((arg) => (typeof arg === "string" ? arg : JSON.stringify(arg))).join(" ") : "";
+}
+
+function isAttachSessionUnavailable(message: string): boolean {
+  return message.includes("没有找到已打开的 VS Code Codex 会话")
+    || /找不到会话\s+.+\s+的 VS Code Codex owner/.test(message);
+}
+
+function validateCloudRelayUrl(value: string): string | undefined {
+  if (!value.trim()) return undefined;
+  try {
+    const url = new URL(value.trim());
+    if (url.protocol !== "wss:" && url.protocol !== "ws:") return t("Use a ws:// or wss:// URL.");
+    if (url.protocol === "ws:" && !isLoopbackHostname(url.hostname)) {
+      return t("Remote Aether connections must use wss://.");
+    }
+    return undefined;
+  } catch {
+    return t("Enter a valid WebSocket URL.");
+  }
+}
+
+function resolveRelayConfiguration(configuration: vscode.WorkspaceConfiguration): {
+  localUrl: string;
+  cloudUrl: string;
+  legacyRemote: boolean;
+} {
+  const defaultLocalUrl = "ws://127.0.0.1:8787/v1/connect";
+  const explicitLocal = inspectedValue<string>(configuration.inspect<string>("localRelayUrl"));
+  const explicitCloud = inspectedValue<string>(configuration.inspect<string>("cloudRelayUrl"));
+  const explicitLegacy = inspectedValue<string>(configuration.inspect<string>("relayUrl"));
+  const legacyUrl = explicitLegacy?.trim() || "";
+  const legacyRemote = Boolean(legacyUrl && !localRelayTarget(legacyUrl));
+  const localUrl = (explicitLocal?.trim()
+    || (!legacyRemote ? legacyUrl : "")
+    || configuration.get<string>("localRelayUrl", defaultLocalUrl).trim()
+    || defaultLocalUrl);
+  const cloudUrl = explicitCloud?.trim()
+    || (legacyRemote ? legacyUrl : "")
+    || configuration.get<string>("cloudRelayUrl", "").trim();
+  return { localUrl, cloudUrl, legacyRemote };
+}
+
+function inspectedValue<T>(inspection: ReturnType<vscode.WorkspaceConfiguration["inspect"]> | undefined): T | undefined {
+  if (!inspection) return undefined;
+  const values = inspection as {
+    globalLanguageValue?: T;
+    workspaceFolderLanguageValue?: T;
+    workspaceLanguageValue?: T;
+    workspaceFolderValue?: T;
+    workspaceValue?: T;
+    globalValue?: T;
+  };
+  return values.workspaceFolderLanguageValue
+    ?? values.workspaceLanguageValue
+    ?? values.globalLanguageValue
+    ?? values.workspaceFolderValue
+    ?? values.workspaceValue
+    ?? values.globalValue;
+}
+
+function resolveInitialControlMode(configuration: vscode.WorkspaceConfiguration): ControlMode {
+  const configured = inspectedValue<ControlMode>(configuration.inspect<ControlMode>("controlMode"));
+  if (configured === "sync" || configured === "async") return configured;
+  const legacyMode = inspectedValue<"attach" | "spawn">(configuration.inspect<"attach" | "spawn">("mode"));
+  return legacyMode === "spawn" ? "async" : "sync";
+}
+
+function validateAetherBaseUrl(value: string): string | undefined {
+  if (!value.trim()) return t("Enter the Aether server URL.");
+  try {
+    const url = new URL(value.trim());
+    if (url.username || url.password || url.search || url.hash) return t("Use the Aether origin without credentials, a query, or a fragment.");
+    if (url.protocol === "https:") return undefined;
+    if (url.protocol === "http:" && isLoopbackHostname(url.hostname)) return undefined;
+    return t("Remote Aether servers must use https://.");
+  } catch {
+    return t("Enter a valid URL.");
+  }
+}
+
+function normalizePairingCode(value: string): string {
+  return value.toUpperCase().replace(/[^A-Z2-9]/g, "");
+}
+
+function isLoopbackHostname(value: string): boolean {
+  const hostname = value.replace(/^\[|\]$/g, "").toLowerCase();
+  return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1";
+}
+
+function isJsonRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Reuse the official extension's command registry for the header's new-chat
+ * action. This keeps the remote UI attached to the same VS Code Codex
+ * installation and avoids launching a second app-server process.
+ */
+async function openOfficialNewSession(logger: Logger): Promise<JsonObject> {
+  const commands = await vscode.commands.getCommands(true);
+  const command = commands.includes("chatgpt.newCodexPanel")
+    ? "chatgpt.newCodexPanel"
+    : commands.includes("chatgpt.newChat")
+      ? "chatgpt.newChat"
+      : undefined;
+  if (!command) {
+    throw new Error(t("The official Codex extension new-conversation command was not found. Make sure the VS Code Codex extension is enabled."));
+  }
+  await vscode.commands.executeCommand(command);
+  logger.info?.("Opened a new official Codex conversation with " + command);
+  return { opened: true, command };
+}

aether-vscodex/vscode-extension/src/index.ts

@@ -0,0 +1,11 @@
+export * from "./protocol";
+export * from "./jsonlRpc";
+export * from "./codexAgentAdapter";
+export * from "./relayClient";
+export * from "./compositeRelay";
+export * from "./relayHost";
+export * from "./bridge";
+export * from "./codexPath";
+export * from "./codexIpc";
+export * from "./codexIpcAgentAdapter";
+export * from "./switchableAgentAdapter";

aether-vscodex/vscode-extension/src/jsonlRpc.ts

@@ -0,0 +1,268 @@
+import { ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { createInterface, Interface as ReadLineInterface } from "node:readline";
+
+import {
+  asJsonValue,
+  Disposable,
+  isRecord,
+  JsonRpcId,
+  JsonRpcNotification,
+  JsonRpcRequest,
+  JsonValue,
+  Logger,
+  jsonRpcIdKey,
+} from "./protocol";
+
+export interface JsonlRpcClientOptions {
+  command?: string;
+  args?: string[];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  logger?: Logger;
+  /** Optional request timeout. Zero disables it, which is useful for long turns. */
+  requestTimeoutMs?: number;
+}
+
+interface PendingRequest {
+  method: string;
+  resolve: (value: JsonValue) => void;
+  reject: (reason: Error) => void;
+  timer?: NodeJS.Timeout;
+}
+
+export class JsonRpcRemoteError extends Error {
+  constructor(
+    message: string,
+    readonly code: number,
+    readonly data?: JsonValue,
+  ) {
+    super(message);
+    this.name = "JsonRpcRemoteError";
+  }
+}
+
+/** Minimal newline-delimited JSON-RPC client used by `codex app-server --stdio`. */
+export class JsonlRpcClient {
+  private readonly options: Required<Pick<JsonlRpcClientOptions, "command" | "args" | "requestTimeoutMs">> &
+    Omit<JsonlRpcClientOptions, "command" | "args" | "requestTimeoutMs">;
+  private child?: ChildProcessWithoutNullStreams;
+  private stdoutLines?: ReadLineInterface;
+  private nextId = 1;
+  private readonly pending = new Map<string, PendingRequest>();
+  private readonly notificationListeners = new Set<(message: JsonRpcNotification) => void>();
+  private readonly requestListeners = new Set<(message: JsonRpcRequest) => void>();
+  private readonly exitListeners = new Set<(error?: Error) => void>();
+
+  constructor(options: JsonlRpcClientOptions = {}) {
+    this.options = {
+      command: options.command ?? "codex",
+      args: options.args ?? ["app-server", "--stdio"],
+      requestTimeoutMs: options.requestTimeoutMs ?? 0,
+      cwd: options.cwd,
+      env: options.env,
+      logger: options.logger,
+    };
+  }
+
+  get running(): boolean {
+    return Boolean(this.child && this.child.exitCode === null && !this.child.killed);
+  }
+
+  async start(): Promise<void> {
+    if (this.running) return;
+
+    const child = spawn(this.options.command, this.options.args, {
+      cwd: this.options.cwd,
+      env: { ...process.env, ...(this.options.env ?? {}) },
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    this.child = child;
+
+    this.stdoutLines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+    this.stdoutLines.on("line", (line) => this.handleLine(line));
+    child.stderr.on("data", (chunk: Buffer) => {
+      const text = redactDiagnostic(chunk.toString("utf8").trim());
+      if (text) this.options.logger?.debug?.(`[app-server stderr] ${text}`);
+    });
+    child.once("exit", (code, signal) => {
+      const expected = child.killed;
+      const error = expected
+        ? undefined
+        : new Error(`codex app-server exited (code=${String(code)}, signal=${String(signal)})`);
+      this.handleExit(error);
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      const onSpawn = (): void => {
+        child.off("error", onError);
+        resolve();
+      };
+      const onError = (error: Error): void => {
+        child.off("spawn", onSpawn);
+        const spawnError = error as NodeJS.ErrnoException;
+        if (spawnError.code === "ENOENT") {
+          reject(new Error(`Codex executable "${this.options.command}" was not found. Set codexRemoteCollab.codexCommand to its full path.`));
+          return;
+        }
+        reject(error);
+      };
+      child.once("spawn", onSpawn);
+      child.once("error", onError);
+    });
+  }
+
+  request(method: string, params?: JsonValue): Promise<JsonValue> {
+    if (!this.running) return Promise.reject(new Error("app-server is not running"));
+    const id = this.nextId++;
+
+    return new Promise<JsonValue>((resolve, reject) => {
+      const pending: PendingRequest = { method, resolve, reject };
+      if (this.options.requestTimeoutMs > 0) {
+        pending.timer = setTimeout(() => {
+          this.pending.delete(jsonRpcIdKey(id));
+          reject(new Error(`app-server request timed out: ${method}`));
+        }, this.options.requestTimeoutMs);
+      }
+      this.pending.set(jsonRpcIdKey(id), pending);
+      try {
+        this.write({ id, method, ...(params === undefined ? {} : { params }) });
+      } catch (error) {
+        this.pending.delete(jsonRpcIdKey(id));
+        if (pending.timer) clearTimeout(pending.timer);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+
+  notify(method: string, params?: JsonValue): void {
+    this.write({ method, ...(params === undefined ? {} : { params }) });
+  }
+
+  respond(id: JsonRpcId, result: JsonValue): void {
+    this.write({ id, result });
+  }
+
+  respondError(id: JsonRpcId, code: number, message: string, data?: JsonValue): void {
+    this.write({ id, error: { code, message, ...(data === undefined ? {} : { data }) } });
+  }
+
+  onNotification(listener: (message: JsonRpcNotification) => void): Disposable {
+    this.notificationListeners.add(listener);
+    return { dispose: () => this.notificationListeners.delete(listener) };
+  }
+
+  onServerRequest(listener: (message: JsonRpcRequest) => void): Disposable {
+    this.requestListeners.add(listener);
+    return { dispose: () => this.requestListeners.delete(listener) };
+  }
+
+  onExit(listener: (error?: Error) => void): Disposable {
+    this.exitListeners.add(listener);
+    return { dispose: () => this.exitListeners.delete(listener) };
+  }
+
+  close(): void {
+    const child = this.child;
+    this.child = undefined;
+    this.stdoutLines?.close();
+    this.stdoutLines = undefined;
+    if (child && child.exitCode === null && !child.killed) child.kill();
+    this.rejectAll(new Error("app-server client closed"));
+  }
+
+  private write(message: unknown): void {
+    const child = this.child;
+    if (!child || child.exitCode !== null || child.killed || !child.stdin.writable) {
+      throw new Error("app-server is not running");
+    }
+    child.stdin.write(`${JSON.stringify(message)}\n`, "utf8");
+  }
+
+  private handleLine(line: string): void {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    let message: unknown;
+    try {
+      message = JSON.parse(trimmed);
+    } catch (error) {
+      this.options.logger?.warn?.("Ignoring malformed app-server JSON", error, trimmed.slice(0, 500));
+      return;
+    }
+    if (!isRecord(message)) return;
+
+    const hasId = typeof message.id === "string" || typeof message.id === "number";
+    const hasMethod = typeof message.method === "string";
+    if (hasId && (Object.hasOwn(message, "result") || Object.hasOwn(message, "error")) && !hasMethod) {
+      this.handleResponse(message as Record<string, unknown> & { id: JsonRpcId });
+      return;
+    }
+
+    if (hasMethod && hasId) {
+      const request: JsonRpcRequest = {
+        id: message.id as JsonRpcId,
+        method: message.method as string,
+        ...(message.params === undefined ? {} : { params: asJsonValue(message.params) }),
+      };
+      for (const listener of this.requestListeners) listener(request);
+      return;
+    }
+
+    if (hasMethod) {
+      const notification: JsonRpcNotification = {
+        method: message.method as string,
+        ...(message.params === undefined ? {} : { params: asJsonValue(message.params) }),
+      };
+      for (const listener of this.notificationListeners) listener(notification);
+      return;
+    }
+
+    this.options.logger?.warn?.("Ignoring unknown app-server message", message);
+  }
+
+  private handleResponse(message: Record<string, unknown> & { id: JsonRpcId }): void {
+    const pending = this.pending.get(jsonRpcIdKey(message.id));
+    if (!pending) {
+      this.options.logger?.warn?.(`Received response for unknown app-server request ${String(message.id)}`);
+      return;
+    }
+    this.pending.delete(jsonRpcIdKey(message.id));
+    if (pending.timer) clearTimeout(pending.timer);
+
+    if (isRecord(message.error)) {
+      pending.reject(
+        new JsonRpcRemoteError(
+          typeof message.error.message === "string" ? message.error.message : `Request failed: ${pending.method}`,
+          typeof message.error.code === "number" ? message.error.code : -32000,
+          message.error.data === undefined ? undefined : asJsonValue(message.error.data),
+        ),
+      );
+      return;
+    }
+    pending.resolve(message.result === undefined ? null : asJsonValue(message.result));
+  }
+
+  private handleExit(error?: Error): void {
+    this.child = undefined;
+    this.stdoutLines?.close();
+    this.stdoutLines = undefined;
+    this.rejectAll(error ?? new Error("app-server exited"));
+    for (const listener of this.exitListeners) listener(error);
+  }
+
+  private rejectAll(error: Error): void {
+    for (const request of this.pending.values()) {
+      if (request.timer) clearTimeout(request.timer);
+      request.reject(error);
+    }
+    this.pending.clear();
+  }
+}
+
+function redactDiagnostic(text: string): string {
+  return text
+    .replace(/Bearer\s+[A-Za-z0-9._~+\-/]+=*/gi, "Bearer [REDACTED]")
+    .replace(/\b(?:sk-[A-Za-z0-9_-]{12,}|gh[pousr]_[A-Za-z0-9_]{12,})\b/g, "[REDACTED]")
+    .replace(/((?:token|secret|password|api[_-]?key)\s*[:=]\s*)[^\s,;]+/gi, "$1[REDACTED]");
+}

aether-vscodex/vscode-extension/src/localRelay.ts

@@ -0,0 +1,193 @@
+import * as http from "node:http";
+import * as path from "node:path";
+
+import { Logger } from "./protocol";
+
+interface BundledRelay {
+  start(): Promise<{ host: string; port: number }>;
+  stop(): Promise<void>;
+}
+
+interface BundledRelayModule {
+  CodexRelay: new (options: Record<string, unknown>) => BundledRelay;
+}
+
+export interface LocalRelayTarget {
+  host: string;
+  port: number;
+  healthUrl: string;
+  webUrl: string;
+}
+
+export interface LocalRelayControllerOptions {
+  extensionPath: string;
+  logger?: Logger;
+  probeTimeoutMs?: number;
+  relayModulePath?: string;
+  loadRelayModule?: (modulePath: string) => BundledRelayModule;
+  probeRelayHealth?: (url: string, timeoutMs?: number) => Promise<boolean>;
+}
+
+/**
+ * Owns the loopback relay bundled with the companion extension. Remote and
+ * TLS relay URLs deliberately stay outside this controller.
+ */
+export class LocalRelayController {
+  private readonly options: LocalRelayControllerOptions;
+  private relay?: BundledRelay;
+  private target?: LocalRelayTarget;
+  private starting?: Promise<boolean>;
+  private generation = 0;
+
+  constructor(options: LocalRelayControllerOptions) {
+    this.options = options;
+  }
+
+  async ensureRunning(relayUrl: string): Promise<boolean> {
+    const target = localRelayTarget(relayUrl);
+    if (!target) return false;
+    if ((this.relay || this.starting) && this.target?.healthUrl !== target.healthUrl) await this.stop();
+    const generation = this.generation;
+    this.target = target;
+    const available = await this.probeHealth(target.healthUrl);
+    // `stop()` may run while the health request is in flight. Do not let that
+    // completed probe resurrect a relay owned by a deactivated extension.
+    if (generation !== this.generation) return false;
+    if (available) return false;
+    if (this.relay) {
+      await this.relay.stop().catch(() => undefined);
+      this.relay = undefined;
+    }
+    if (this.starting) return this.starting;
+    this.starting = this.startBundledRelay(target).finally(() => {
+      this.starting = undefined;
+    });
+    return this.starting;
+  }
+
+  getWebUrl(relayUrl: string): string | undefined {
+    return localRelayTarget(relayUrl)?.webUrl;
+  }
+
+  async stop(): Promise<void> {
+    this.generation += 1;
+    const starting = this.starting;
+    if (starting) await starting.catch(() => undefined);
+    const relay = this.relay;
+    this.relay = undefined;
+    this.target = undefined;
+    if (relay) await relay.stop();
+  }
+
+  private async startBundledRelay(target: LocalRelayTarget): Promise<boolean> {
+    const modulePath = this.options.relayModulePath
+      ?? path.join(this.options.extensionPath, "dist", "local-relay", "server.js");
+    let relay: BundledRelay;
+    try {
+      const load = this.options.loadRelayModule ?? ((value: string) => require(value) as BundledRelayModule);
+      const module = load(modulePath);
+      if (typeof module?.CodexRelay !== "function") throw new Error("bundled relay module is invalid");
+      relay = new module.CodexRelay({
+        host: target.host,
+        port: target.port,
+        mode: "host",
+        spawnCodex: false,
+        authRequired: false,
+      });
+      await relay.start();
+    } catch (error) {
+      // Another VS Code window can win the listen race after our health
+      // probe. Treat that as success only when the expected relay responds.
+      if (await this.probeHealth(target.healthUrl)) {
+        this.options.logger?.info?.(`Using existing local relay at ${target.webUrl}`);
+        return false;
+      }
+      throw error;
+    }
+    this.relay = relay;
+    this.options.logger?.info?.(`Started bundled local relay at ${target.webUrl}`);
+    return true;
+  }
+
+  private probeHealth(url: string): Promise<boolean> {
+    const probe = this.options.probeRelayHealth ?? relayHealthAvailable;
+    return probe(url, this.options.probeTimeoutMs);
+  }
+}
+
+export function localRelayTarget(relayUrl: string): LocalRelayTarget | undefined {
+  let url: URL;
+  try {
+    url = new URL(relayUrl);
+  } catch {
+    return undefined;
+  }
+  if (url.protocol !== "ws:" || !isLoopbackHostname(url.hostname)) return undefined;
+  const port = Number(url.port || 80);
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) return undefined;
+  const hostname = normalizeLoopbackHostname(url.hostname);
+  const authorityHost = hostname.includes(":") ? `[${hostname}]` : hostname;
+  return {
+    host: hostname,
+    port,
+    healthUrl: `http://${authorityHost}:${port}/api/health`,
+    webUrl: `http://${authorityHost}:${port}/`,
+  };
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1";
+}
+
+function normalizeLoopbackHostname(hostname: string): string {
+  const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  return normalized === "localhost" ? "127.0.0.1" : normalized;
+}
+
+export function relayHealthAvailable(url: string, timeoutMs = 700): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer: NodeJS.Timeout | undefined;
+    const finish = (available: boolean): void => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(available);
+    };
+    const request = http.get(url, (response) => {
+      if (response.statusCode !== 200) {
+        response.resume();
+        finish(false);
+        return;
+      }
+      let body = "";
+      response.setEncoding("utf8");
+      response.on("data", (chunk) => {
+        if (body.length <= 16_384) body += chunk;
+      });
+      response.on("end", () => {
+        try {
+          const payload = JSON.parse(body) as { ok?: unknown };
+          finish(payload.ok === true);
+        } catch {
+          finish(false);
+        }
+      });
+      response.on("aborted", () => finish(false));
+      response.on("error", () => finish(false));
+      response.on("close", () => {
+        if (!response.complete) finish(false);
+      });
+    });
+    request.setTimeout(timeoutMs, () => {
+      request.destroy();
+      finish(false);
+    });
+    request.on("error", () => finish(false));
+    timer = setTimeout(() => {
+      request.destroy();
+      finish(false);
+    }, timeoutMs);
+  });
+}

aether-vscodex/vscode-extension/src/protocol.ts

@@ -0,0 +1,496 @@
+/**
+ * Wire types shared by the relay host and the Codex app-server adapter.
+ *
+ * The relay intentionally treats `payload` as JSON. Keeping this boundary
+ * unopinionated lets the bridge continue working when app-server adds a new
+ * notification or request before this extension is updated.
+ */
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+export type JsonObject = { [key: string]: JsonValue };
+export type JsonRpcId = string | number;
+
+/** Preserve the JSON-RPC id type when using it as a map key. */
+export function jsonRpcIdKey(id: JsonRpcId): string {
+  return `${typeof id}:${String(id)}`;
+}
+
+export function isJsonRpcId(value: unknown): value is JsonRpcId {
+  return typeof value === "string" || typeof value === "number";
+}
+
+export type ApprovalDecisionKind = "allow" | "deny" | "cancel";
+
+const LEGACY_APPROVAL_METHODS = new Set(["applyPatchApproval", "execCommandApproval"]);
+const V2_APPROVAL_METHODS = new Set([
+  "item/commandExecution/requestApproval",
+  "item/fileChange/requestApproval",
+]);
+
+/**
+ * Classify both current and legacy app-server approval decisions without
+ * rewriting the wire value. Unknown tagged objects intentionally return
+ * `undefined` so callers can fail closed instead of accidentally approving a
+ * newly introduced response shape.
+ */
+export function approvalDecisionKind(value: unknown): ApprovalDecisionKind | undefined {
+  if (typeof value === "string") {
+    if (new Set([
+      "allow",
+      "accept",
+      "acceptForSession",
+      "approved",
+      "approved_for_session",
+      "approved_mcp_policy_amendment",
+    ]).has(value)) return "allow";
+    if (new Set(["deny", "decline", "denied", "timed_out"]).has(value)) return "deny";
+    if (new Set(["cancel", "abort"]).has(value)) return "cancel";
+    return undefined;
+  }
+  if (!isRecord(value)) return undefined;
+  const keys = Object.keys(value);
+  if (keys.length !== 1) return undefined;
+  const key = keys[0];
+  const nested = value[key];
+  if (isExecpolicyAmendmentTag(key, nested) || isNetworkPolicyAmendmentTag(key, nested)) return "allow";
+  if (key === "denied" && isRecord(nested) && typeof nested.rejection === "string") return "deny";
+  return undefined;
+}
+
+/**
+ * Classify a decision against the response schema for one app-server method.
+ * The generic classifier above is intentionally useful for relay envelopes;
+ * this method-aware variant prevents a v2 tagged object from being sent to a
+ * legacy callback (or vice versa), while retaining compatibility aliases that
+ * the relay may use in its outer `decision` field.
+ */
+export function approvalDecisionKindForMethod(
+  value: unknown,
+  method?: string,
+): ApprovalDecisionKind | undefined {
+  const generic = approvalDecisionKind(value);
+  if (!generic || !method) return generic;
+
+  if (LEGACY_APPROVAL_METHODS.has(method)) {
+    if (typeof value === "string") {
+      return new Set([
+        "approved",
+        "approved_for_session",
+        "approved_mcp_policy_amendment",
+        "timed_out",
+        "abort",
+      ]).has(value) ? generic : undefined;
+    }
+    if (!isRecord(value)) return undefined;
+    const key = Object.keys(value)[0];
+    return key === "approved_execpolicy_amendment"
+      || key === "network_policy_amendment"
+      || key === "denied" ? generic : undefined;
+  }
+
+  if (V2_APPROVAL_METHODS.has(method)) {
+    if (typeof value === "string") {
+      return new Set(["accept", "acceptForSession", "decline", "cancel"]).has(value)
+        ? generic
+        : undefined;
+    }
+    if (!isRecord(value)) return undefined;
+    const key = Object.keys(value)[0];
+    if (method === "item/fileChange/requestApproval") return undefined;
+    return key === "acceptWithExecpolicyAmendment" || key === "applyNetworkPolicyAmendment"
+      ? generic
+      : undefined;
+  }
+
+  if (method === "mcpServer/elicitation/request") {
+    return typeof value === "string" && new Set(["accept", "decline", "cancel"]).has(value)
+      ? generic
+      : undefined;
+  }
+
+  return generic;
+}
+
+function isExecpolicyAmendmentTag(key: string, nested: unknown): boolean {
+  if (!isRecord(nested)) return false;
+  if (key === "acceptWithExecpolicyAmendment") {
+    return isStringArray(nested.execpolicy_amendment);
+  }
+  if (key === "approved_execpolicy_amendment") {
+    return isStringArray(nested.proposed_execpolicy_amendment);
+  }
+  return false;
+}
+
+function isNetworkPolicyAmendmentTag(key: string, nested: unknown): boolean {
+  if (!isRecord(nested)) return false;
+  if (key === "applyNetworkPolicyAmendment") {
+    return isNetworkPolicyAmendment(nested.network_policy_amendment);
+  }
+  if (key === "network_policy_amendment") {
+    return isNetworkPolicyAmendment(nested.network_policy_amendment);
+  }
+  return false;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isNetworkPolicyAmendment(value: unknown): boolean {
+  return isRecord(value)
+    && typeof value.host === "string"
+    && (value.action === "allow" || value.action === "deny");
+}
+
+/** Whether a response explicitly carries a decision/action field. */
+export function hasApprovalDecisionField(value: unknown): value is Record<string, unknown> {
+  return isRecord(value) && (Object.prototype.hasOwnProperty.call(value, "decision")
+    || Object.prototype.hasOwnProperty.call(value, "action"));
+}
+
+export interface Disposable {
+  dispose(): void;
+}
+
+export interface JsonRpcRequest {
+  id: JsonRpcId;
+  method: string;
+  params?: JsonValue;
+}
+
+export interface JsonRpcNotification {
+  method: string;
+  params?: JsonValue;
+}
+
+export interface JsonRpcResponse {
+  id: JsonRpcId;
+  result?: JsonValue;
+  error?: {
+    code: number;
+    message: string;
+    data?: JsonValue;
+  };
+}
+
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+
+export type RelayRole = "owner" | "operator" | "approver" | "viewer" | string;
+
+export interface RelayActor {
+  id?: string;
+  role?: RelayRole;
+}
+
+/** A versioned relay event frame. `seq` is normally assigned by the relay. */
+export interface RelayEventFrame {
+  v: 1;
+  kind: "event";
+  type: string;
+  id: string;
+  sessionId: string;
+  seq?: number;
+  ts: string;
+  actor?: RelayActor;
+  payload: JsonObject;
+  /** Optional typed execution projection attached by a VS Code host. */
+  status?: AgentStatusSnapshot;
+}
+
+export interface RelayCommandFrame {
+  v?: 1;
+  kind?: "command";
+  type: string;
+  /** Compact relay compatibility form: `{ type: "command", method, params }`. */
+  method?: string;
+  params?: JsonObject;
+  commandId?: string;
+  id?: string;
+  sessionId?: string;
+  actor?: RelayActor;
+  payload?: JsonObject;
+  /** Some clients put the command body under `command`. */
+  command?: {
+    type?: string;
+    commandId?: string;
+    payload?: JsonObject;
+    [key: string]: JsonValue | undefined;
+  };
+}
+
+export interface RelayHelloFrame {
+  v: 1;
+  kind: "hello";
+  clientType: "host" | "web" | string;
+  protocol?: number;
+  accessToken?: string;
+  token?: string;
+  lastSeq?: number;
+  sessionId?: string;
+  payload?: JsonObject;
+}
+
+export interface RelayAckFrame {
+  v: 1;
+  kind: "ack";
+  sessionId: string;
+  seq: number;
+}
+
+export interface RelayErrorFrame {
+  v: 1;
+  kind: "error";
+  code: string;
+  message: string;
+  retryable?: boolean;
+  commandId?: string;
+}
+
+export type RelayFrame =
+  | RelayEventFrame
+  | RelayCommandFrame
+  | RelayHelloFrame
+  | RelayAckFrame
+  | RelayErrorFrame
+  | (JsonObject & { kind?: string; v?: number });
+
+/**
+ * Live execution information projected from the official Codex conversation
+ * state. The private IPC protocol can add new turn statuses/flags, so the
+ * string fields intentionally remain open-ended for forward compatibility.
+ */
+export interface AgentStatusSnapshot {
+  /** Coarse UI activity, for example `thinking`, `editing`, or `running`. */
+  activity: string;
+  /** Raw/normalized turn status (`inProgress`, `completed`, ...). */
+  turnStatus: string;
+  /** Runtime flags such as `waitingOnApproval` or `waitingOnUserInput`. */
+  activeFlags: string[];
+  startedAtMs?: number | null;
+  durationMs?: number | null;
+  /**
+   * Time spent doing work in the official UI.  This deliberately differs
+   * from `durationMs`: Codex starts the worked-for clock at the first work
+   * item and stops it when the final assistant response starts.
+   */
+  workedDurationMs?: number | null;
+  /** Elapsed wall-clock time for an active turn. */
+  elapsedMs?: number | null;
+  firstTurnWorkItemStartedAtMs?: number | null;
+  finalAssistantStartedAtMs?: number | null;
+  error?: JsonValue;
+}
+
+/** Official background-agent lifecycle values emitted by Codex v2 items. */
+export type CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound"
+  | string;
+
+export type CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent"
+  | string;
+
+export type CollabAgentToolCallStatus = "inProgress" | "completed" | "failed" | string;
+export type SubAgentActivityKind = "started" | "interacted" | "interrupted" | "completed" | string;
+
+/** Last known state for one receiver in a collabAgentToolCall item. */
+export interface CollabAgentStateSnapshot {
+  status: CollabAgentStatus;
+  message?: string | null;
+}
+
+/**
+ * Browser-safe projection of a background Codex subagent. The official
+ * webview currently uses the four coarse statuses below; the string union is
+ * deliberately open so a newer app-server status does not break the relay.
+ */
+export interface SubagentSnapshot {
+  threadId: string;
+  displayName: string | null;
+  prompt: string | null;
+  /** Alias used by the subagent side panel for the same prompt text. */
+  objective?: string | null;
+  status: "waiting" | "working" | "done" | "failed" | string;
+  statusMessage: string | null;
+  startedAtMs?: number | null;
+  completedAtMs?: number | null;
+  canInteract?: boolean;
+  model?: string | null;
+  agentPath?: string | null;
+  parentThreadId?: string | null;
+}
+
+export interface AgentEvent {
+  /** Normalized relay event name, for example `output.chunk`. */
+  type: string;
+  threadId?: string;
+  turnId?: string;
+  requestId?: JsonRpcId;
+  payload: JsonObject;
+  /** Original app-server notification/request, when available. */
+  raw?: JsonValue;
+  /** Optional typed projection of live Codex turn/runtime status. */
+  status?: AgentStatusSnapshot;
+}
+
+export interface PendingApproval {
+  requestId: JsonRpcId;
+  method: string;
+  threadId?: string;
+  turnId?: string;
+  itemId?: string;
+  action: string;
+  risk: "low" | "medium" | "high" | "unknown";
+  summary: string;
+  /** SHA-256 of canonicalized, unredacted app-server request params. */
+  commandHash?: string;
+  createdAt: number;
+  expiresAt?: number;
+  payload: JsonObject;
+}
+
+export interface SessionSnapshot {
+  threadId: string | null;
+  turnId: string | null;
+  state: string;
+  pendingApprovals: PendingApproval[];
+  pendingRequests?: Array<{
+    requestId: JsonRpcId;
+    method: string;
+    params?: JsonValue;
+    commandHash?: string;
+    risk?: string;
+    summary?: string;
+    createdAt?: number;
+    expiresAt?: number;
+  }>;
+  outputTail: string;
+  /** Optional role-aware projection used by the browser renderer. */
+  messages?: JsonValue[];
+  /** Background/inline subagents reconstructed from official collab items. */
+  subagents?: SubagentSnapshot[];
+  /** Live execution projection; retained alongside the legacy `state` field. */
+  status?: AgentStatusSnapshot;
+  /** Convenience aliases for clients that do not consume `status` yet. */
+  activity?: string;
+  turnStatus?: string;
+  activeFlags?: string[];
+  startedAtMs?: number | null;
+  durationMs?: number | null;
+  workedDurationMs?: number | null;
+  elapsedMs?: number | null;
+  metadata?: JsonObject;
+}
+
+/** A live VS Code Codex conversation that the attach bridge has verified. */
+export interface SessionListEntry {
+  threadId: string;
+  title: string;
+  updatedAtMs: number | null;
+  cwd?: string | null;
+  active: boolean;
+  /** True for attach-mode results; retained for wire compatibility. */
+  available: boolean;
+}
+
+export interface SessionListResult {
+  sessions: SessionListEntry[];
+  activeThreadId: string | null;
+}
+
+/** Which owner controls conversation navigation for the remote surface. */
+export type ControlMode = "sync" | "async";
+
+export interface AgentAdapter {
+  start(): Promise<void>;
+  /** Switch between following VS Code and independently owned conversations. */
+  setControlMode?(params: JsonObject): Promise<JsonValue>;
+  /** Return the currently committed control mode without taking a snapshot. */
+  getControlMode?(): ControlMode;
+  /** Start a new app-server thread. */
+  startThread?(params?: JsonObject): Promise<JsonValue>;
+  /** Ask the official VS Code Codex extension to open a fresh conversation. */
+  newSession?(params?: JsonObject): Promise<JsonValue>;
+  /** Start a turn; `threadId` may be supplied in params or use the active thread. */
+  startTurn?(params: JsonObject): Promise<JsonValue>;
+  /** Steer the active turn. */
+  steerTurn?(params: JsonObject): Promise<JsonValue>;
+  /** Persist model/effort and other owner-managed settings on the thread. */
+  updateThreadSettings?(params: JsonObject): Promise<JsonValue>;
+  /** List verified, attachable local conversations without starting another Codex process. */
+  listSessions?(params?: JsonObject): Promise<JsonValue>;
+  /** Attach the follower to another already-open conversation. */
+  selectSession?(params: JsonObject): Promise<JsonValue>;
+  /** Interrupt a turn. */
+  interruptTurn?(params: JsonObject): Promise<JsonValue>;
+  /** Convenience MVP aliases. */
+  sendInput(text: string, params?: JsonObject): Promise<JsonValue>;
+  cancel(taskId?: string, params?: JsonObject): Promise<JsonValue>;
+  respondApproval(
+    requestId: JsonRpcId,
+    decision: "allow" | "deny" | "cancel",
+    reason?: string,
+    response?: JsonValue,
+  ): Promise<JsonValue>;
+  /** Resolve all pending approvals/inputs with a deny response. */
+  denyPending?(reason?: string): Promise<void>;
+  snapshot(): Promise<SessionSnapshot>;
+  onEvent(listener: (event: AgentEvent) => void): Disposable;
+  dispose(): Promise<void>;
+}
+
+export interface RelayTransport {
+  connect(): Promise<void>;
+  send(frame: RelayFrame): void;
+  onMessage(listener: (frame: RelayFrame) => void): Disposable;
+  onOpen?(listener: () => void): Disposable;
+  onClose?(listener: (error?: Error) => void): Disposable;
+  close(): void;
+}
+
+export interface Logger {
+  debug?(message: string, ...args: unknown[]): void;
+  info?(message: string, ...args: unknown[]): void;
+  warn?(message: string, ...args: unknown[]): void;
+  error?(message: string, ...args: unknown[]): void;
+}
+
+export const noopDisposable = (): Disposable => ({ dispose: () => undefined });
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function asJsonObject(value: unknown): JsonObject {
+  return isRecord(value) ? (value as JsonObject) : {};
+}
+
+export function asJsonValue(value: unknown): JsonValue {
+  if (value === undefined) return null;
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(asJsonValue);
+  }
+  if (isRecord(value)) {
+    const output: JsonObject = {};
+    for (const [key, item] of Object.entries(value)) {
+      if (item !== undefined) output[key] = asJsonValue(item);
+    }
+    return output;
+  }
+  return String(value);
+}