Build frontend delivery artifacts outside Git with verified upgrade retention

.gitattributes

@@ -1,5 +1,2 @@
-# Vite bundles may retain whitespace-only lines inside generated template literals.
-loopx/web/chat/assets/*.js whitespace=-blank-at-eol
-
 # Preserve the immutable archive's bytes even with core.autocrlf=true.
 benchmark/deepswe-gptxhigh-v1/** text eol=lf

.github/workflows/desktop-updater.yml

@@ -31,6 +31,9 @@ jobs:
       - uses: Swatinem/rust-cache@v2
         with:
           workspaces: apps/desktop/loopx-control-plane/src-tauri -> target
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
       - run: python3 scripts/desktop_runtime_bundle.py
       - run: python3 -m unittest discover -s tests/desktop -p 'test_*.py'
       - run: cargo test --locked && cargo clippy --all-targets --locked -- -D warnings

.github/workflows/frontstage-pages.yml

@@ -10,7 +10,9 @@ on:
       - "README.md"
       - "README.zh-CN.md"
       - "apps/presentation/dashboard/**"
-      - "loopx/web/chat/**"
+      - "scripts/chat_bundle.py"
+      - "scripts/chat_bundle_launcher.mjs"
+      - "loopx/presentation/chat_bundle.py"
       - "apps/presentation/site/**"
       - "benchmark/deepswe/behavior-discovery/**"
       - "docs/**"
@@ -46,7 +48,9 @@ on:
       - "README.md"
       - "README.zh-CN.md"
       - "apps/presentation/dashboard/**"
-      - "loopx/web/chat/**"
+      - "scripts/chat_bundle.py"
+      - "scripts/chat_bundle_launcher.mjs"
+      - "loopx/presentation/chat_bundle.py"
       - "apps/presentation/site/**"
       - "benchmark/deepswe/behavior-discovery/**"
       - "docs/**"
@@ -125,14 +129,17 @@ jobs:
         working-directory: apps/presentation/dashboard
         run: |
           npm run build:chat
-          if [[ -n "$(git -C ../../.. status --short --untracked-files=all -- loopx/web/chat)" ]]; then
-            git -C ../../.. status --short --untracked-files=all -- loopx/web/chat
-            echo "Tracked packaged Dashboard assets differ from a clean source build." >&2
-            exit 1
-          fi
+          python ../../../scripts/chat_bundle.py verify --source
           ./node_modules/.bin/playwright install --with-deps chromium
           npm run smoke:personal-workspace-packaged
 
+      - uses: actions/upload-artifact@v7
+        with:
+          name: frontstage-chat-bundle-${{ github.sha }}
+          path: loopx/web/chat/
+          if-no-files-found: error
+          retention-days: 7
+
       - name: Install docs dependencies
         run: |
           python -m pip install --disable-pip-version-check -r docs/requirements-docs.txt

.github/workflows/full-public-smokes.yml

@@ -76,6 +76,9 @@ jobs:
       - name: Install locked TypeScript parser for semantic production checks
         run: npm ci --ignore-scripts
 
+      - name: Build the packaged frontend from source
+        run: python scripts/chat_bundle.py build --install
+
       - name: Preview full-public shard
         run: |
           python3 examples/run-smokes.py \

.github/workflows/python-tests.yml

@@ -19,6 +19,8 @@ on:
       - "package.json"
       - "package-lock.json"
       - "pyproject.toml"
+      - "setup.py"
+      - "MANIFEST.in"
       - "tsconfig.control-plane.json"
 
 permissions:
@@ -83,8 +85,38 @@ jobs:
           if-no-files-found: error
           retention-days: 7
 
-  kernel-static-checks:
+  chat-bundle:
     needs: changes
+    if: needs.changes.outputs.core_tests == 'true' || needs.changes.outputs.python_tests == 'true' || needs.changes.outputs.presentation_tests == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: apps/presentation/dashboard/package-lock.json
+      - run: python scripts/chat_bundle.py build --install
+      - run: python scripts/chat_bundle.py verify --source
+      - name: Qualify the actual compiled UI before saving the artifact
+        working-directory: apps/presentation/dashboard
+        run: |
+          ./node_modules/.bin/playwright install --with-deps chromium
+          npm run smoke:personal-workspace-packaged
+          npm run smoke:chat-upgrade
+      - uses: actions/upload-artifact@v7
+        with:
+          name: chat-bundle-${{ github.sha }}
+          path: loopx/web/chat/
+          if-no-files-found: error
+          retention-days: 7
+
+  kernel-static-checks:
+    needs: [changes, chat-bundle]
     if: needs.changes.outputs.core_tests == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 60
@@ -94,6 +126,11 @@ jobs:
         with:
           fetch-depth: 0
 
+      - uses: actions/download-artifact@v7
+        with:
+          name: chat-bundle-${{ github.sha }}
+          path: loopx/web/chat/
+
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
@@ -156,14 +193,19 @@ jobs:
         run: python examples/control_plane/cli-output-budget-regression-smoke.py
 
   dashboard-acceptance:
-    needs: changes
+    needs: [changes, chat-bundle]
     if: needs.changes.outputs.core_tests == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
       - name: Check out repository
         uses: actions/checkout@v7
 
+      - uses: actions/download-artifact@v7
+        with:
+          name: chat-bundle-${{ github.sha }}
+          path: loopx/web/chat/
+
       - name: Set up the qualified Node.js runtime
         uses: actions/setup-node@v6
         with:
@@ -258,7 +300,7 @@ jobs:
           npm run test:control-plane
 
   test-shard:
-    needs: changes
+    needs: [changes, chat-bundle]
     if: needs.changes.outputs.python_tests == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 30
@@ -270,6 +312,11 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
+      - uses: actions/download-artifact@v7
+        with:
+          name: chat-bundle-${{ github.sha }}
+          path: loopx/web/chat/
+
       - uses: actions/setup-python@v6
         with:
           python-version: "3.11"
@@ -378,7 +425,7 @@ jobs:
       SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
 
   stage2c-suite:
-    needs: changes
+    needs: [changes, chat-bundle]
     if: needs.changes.outputs.stage2c_tests == 'true'
     name: stage2c (${{ matrix.suite }} ${{ matrix.shard }})
     runs-on: ubuntu-latest
@@ -393,6 +440,11 @@ jobs:
           - {suite: installed, shard: 0}
     steps:
       - uses: actions/checkout@v7
+      - uses: actions/download-artifact@v7
+        with:
+          name: chat-bundle-${{ github.sha }}
+          path: loopx/web/chat/
+
       - uses: actions/setup-python@v6
         with:
           python-version: "3.11"
@@ -472,16 +524,21 @@ jobs:
         run: test "$STAGE2C_RESULT" = success
 
   windows-powershell:
-    needs: changes
+    needs: [changes, chat-bundle]
     if: needs.changes.outputs.python_tests == 'true'
     runs-on: windows-latest
-    timeout-minutes: 20
+    timeout-minutes: 30
     steps:
       - name: Check out repository
         uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
+      - uses: actions/download-artifact@v7
+        with:
+          name: chat-bundle-${{ github.sha }}
+          path: loopx/web/chat/
+
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
@@ -492,6 +549,8 @@ jobs:
         uses: actions/setup-node@v6
         with:
           node-version: "24"
+          cache: npm
+          cache-dependency-path: apps/presentation/dashboard/package-lock.json
 
       - name: Install test dependencies
         run: python -m pip install --disable-pip-version-check -e ".[test]"
@@ -527,34 +586,43 @@ jobs:
           tests/control_plane_ts/local_authority_provider.test.ts
           tests/control_plane_ts/sqlite_runtime_admission.test.ts
 
+      - name: Install the frontend dependencies for a source rebuild
+        working-directory: apps/presentation/dashboard
+        run: npm ci --ignore-scripts
+
+      - name: Rebuild the Chat bundle where only python.exe is usable
+        working-directory: apps/presentation/dashboard
+        shell: pwsh
+        run: |
+          $shadow = Join-Path $env:RUNNER_TEMP "python-exe-only"
+          New-Item -ItemType Directory -Force -Path $shadow | Out-Null
+          # Supported Windows installs may expose python.exe alone, and a
+          # python3.exe App Execution Alias stub is not runnable. The npm entry
+          # must resolve a real 3.11+ interpreter either way.
+          Set-Content -Path (Join-Path $shadow "python3.exe") `
+            -Value "unusable python3 stand-in" -Encoding ascii
+          $env:PATH = "$shadow;$env:PATH"
+          npm run build:chat
+
+      - name: Verify the Windows-built Chat bundle
+        run: python scripts/chat_bundle.py verify --source
+
   presentation:
-    needs: changes
+    needs: [changes, chat-bundle]
     if: needs.changes.outputs.presentation_tests == 'true'
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 5
     steps:
       - uses: actions/checkout@v7
+      - uses: actions/download-artifact@v7
+        with:
+          name: chat-bundle-${{ github.sha }}
+          path: loopx/web/chat/
       - uses: actions/setup-python@v6
         with:
           python-version: "3.11"
-          cache: pip
-      - uses: actions/setup-node@v6
-        with:
-          node-version: "24"
-          cache: npm
-          cache-dependency-path: apps/presentation/dashboard/package-lock.json
-      - run: python -m pip install --disable-pip-version-check -e ".[test]"
-      - name: Build and test the actual packaged Dashboard
-        working-directory: apps/presentation/dashboard
-        run: |
-          npm ci --ignore-scripts
-          npm run build:chat
-          if [[ -n "$(git -C ../../.. status --short --untracked-files=all -- loopx/web/chat)" ]]; then
-            echo "Packaged Dashboard differs from its source build." >&2
-            exit 1
-          fi
-          ./node_modules/.bin/playwright install --with-deps chromium
-          npm run smoke:personal-workspace-packaged
+      - name: Verify the source-bound, browser-qualified Dashboard artifact
+        run: python scripts/chat_bundle.py verify --source
 
   merge-gate:
     # Always publish one stable outcome, including documentation-only PRs.

.github/workflows/release-artifacts.yml

@@ -9,6 +9,11 @@ on:
       - "package.json"
       - "package-lock.json"
       - "pyproject.toml"
+      - "setup.py"
+      - "MANIFEST.in"
+      - "apps/presentation/dashboard/**"
+      - "scripts/chat_bundle.py"
+      - "scripts/verify_installed_chat.py"
       - "README.md"
       - "scripts/release_artifacts.py"
       - "tsconfig.control-plane.json"
@@ -75,6 +80,11 @@ jobs:
           echo "SOURCE_DATE_EPOCH=${source_date_epoch}" >> "${GITHUB_ENV}"
           echo "PYTHONHASHSEED=0" >> "${GITHUB_ENV}"
 
+      - name: Build exact release frontend with previous delivery assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: python scripts/chat_bundle.py release-build --tag "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY"
+
       - name: Install release build tools
         run: python -m pip install --disable-pip-version-check build==1.4.4 twine==6.2.0
 
@@ -196,6 +206,21 @@ jobs:
               assert committed["replayed"] is False, committed
           PY
 
+      - name: Verify installed frontend and sdist rebuild
+        run: |
+          python scripts/verify_installed_chat.py --python "${RUNNER_TEMP}/loopx-wheel/bin/python"
+          python -m pip wheel --no-deps dist/packages/*.tar.gz --wheel-dir "${RUNNER_TEMP}/sdist-wheel"
+          "${RUNNER_TEMP}/loopx-wheel/bin/python" -m pip install --force-reinstall --no-deps "${RUNNER_TEMP}"/sdist-wheel/*.whl
+          python scripts/verify_installed_chat.py --python "${RUNNER_TEMP}/loopx-wheel/bin/python"
+
+      - name: Exercise the installed page in a real browser
+        working-directory: apps/presentation/dashboard
+        env:
+          LOOPX_PYTHON_BIN: ${{ runner.temp }}/loopx-wheel/bin/python
+        run: |
+          ./node_modules/.bin/playwright install --with-deps chromium
+          npm run smoke:personal-workspace-packaged
+
       - name: Verify wheel through the DSH managed-runtime install shape
         run: |
           set -euo pipefail

.gitignore

@@ -40,3 +40,7 @@ logs/
 
 # Legacy semantic census reports are derived locally, never repository authority.
 /loopx/semantics/inventory_v0.json
+
+# Frontend delivery artifacts are built and qualified from source.
+/loopx/web/chat/
+/loopx/web/.chat-build-*/

MANIFEST.in

@@ -0,0 +1 @@
+graft loopx/web/chat

apps/presentation/dashboard/README.md

@@ -450,3 +450,7 @@ The throttled smoke protects the "quiet scheduling state" first screen. The
 operator-gate smoke protects planned high-complexity goals: they should appear
 as controller/user actions, not Codex-ready work. Those older browser smokes
 still use the local Playwright CLI wrapper.
+
+## Packaged frontend delivery
+
+Generated Chat assets are not committed. See [frontend delivery](../../../docs/development/frontend-delivery.md) for source rebuilds, SHA-bound CI artifacts, package validation and the one-delivery upgrade window.

apps/presentation/dashboard/package.json

@@ -7,8 +7,8 @@
   "scripts": {
     "smoke:workspace-progressive-loader": "node smoke/workspace-progressive-status-smoke.mjs",
     "smoke:workspace-progressive": "node ../../../examples/workspace-progressive-loading-browser-smoke.mjs",
-    "build": "tsc --noEmit && vite build && vite build --config vite.chat.config.ts",
-    "build:chat": "tsc --noEmit && vite build --config vite.chat.config.ts",
+    "build": "tsc --noEmit && vite build && npm run build:chat",
+    "build:chat": "node ../../../scripts/chat_bundle_launcher.mjs build",
     "build:desktop": "tsc --noEmit && vite build",
     "dev": "bash ../../../scripts/dashboard-dev.sh",
     "dev:web": "vite --host 127.0.0.1",
@@ -51,7 +51,9 @@
     "smoke:attention-details": "tsc --ignoreConfig --target ES2022 --module CommonJS --moduleResolution Node --ignoreDeprecations 6.0 --resolveJsonModule --esModuleInterop --skipLibCheck --strict --outDir /tmp/loopx-attention-details-smoke smoke/attention-details-smoke.ts && NODE_PATH=\"$PWD/node_modules\" node /tmp/loopx-attention-details-smoke/apps/presentation/dashboard/smoke/attention-details-smoke.js",
     "smoke:delivery-review": "tsc --ignoreConfig --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck --strict --rootDir src --outDir node_modules/.cache/delivery-review src/data/delivery-review.ts src/data/goal-acceptance-observation.ts src/features/personal-workspace/delivery-review-copy.ts && node smoke/delivery-review-smoke.mjs",
     "smoke:team-artifact-comparison": "tsc --ignoreConfig --target ES2022 --module ES2022 --moduleResolution Bundler --skipLibCheck --strict --rootDir src --outDir node_modules/.cache/team-comparison src/features/personal-workspace/team-artifact-comparison.ts src/vite-env.d.ts && node smoke/team-artifact-comparison-smoke.mjs",
-    "smoke:team-report": "tsc --ignoreConfig --target ES2022 --module ES2022 --moduleResolution Bundler --jsx react-jsx --skipLibCheck --strict --rootDir src --outDir node_modules/.cache/team-report src/features/personal-workspace/team-artifact-content.tsx src/vite-env.d.ts && node smoke/team-report-smoke.mjs"
+    "smoke:team-report": "tsc --ignoreConfig --target ES2022 --module ES2022 --moduleResolution Bundler --jsx react-jsx --skipLibCheck --strict --rootDir src --outDir node_modules/.cache/team-report src/features/personal-workspace/team-artifact-content.tsx src/vite-env.d.ts && node smoke/team-report-smoke.mjs",
+    "build:chat:vite": "tsc --noEmit && vite build --config vite.chat.config.ts",
+    "smoke:chat-upgrade": "LOOPX_PLAYWRIGHT_PACKAGE=\"$PWD/node_modules/playwright\" node ../../../examples/chat-bundle-upgrade-browser-smoke.mjs"
   },
   "dependencies": {
     "@fontsource-variable/geist": "^5.3.0",