ci: run the pull-request Windows blocking gates under Wine on hosted Linux

The required windows job moves from windows-2025 to ubuntu-latest, running
checksum-verified Windows Node under Wine at Linux-job wall clock (2m46s
warm vs 7-9min); master's serial-windows native-kernel reference is
untouched, and a new master-only wine-apt-cache job seeds the apt cache
every pull request restores. The experiment workflow folds into ci.yml,
the Agent Note moves to implemented with measured results, and the two CI
topology notes update to the shipped facts.
This commit is contained in:
Tianyi Cui
2026-07-27 13:17:12 +08:00
parent b052cd1161
commit cff614d37d
15 changed files with 316 additions and 375 deletions

2
.github/AGENTS.md vendored
View File

@@ -1,3 +1,3 @@
# AGENTS.md — GitHub Actions
Run Windows jobs under native `pwsh`.
Run jobs on Windows runners (`windows-*` labels) under native `pwsh`. The pull-request `windows` job is not one of them: it runs Windows Node under Wine on hosted Linux, so its steps are bash — see the [Wine lane Agent Note](../.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md).

View File

@@ -281,41 +281,224 @@ jobs:
- name: Run complete keyless Python suite
run: uv run --python 3.10 --group test --project python/sdk pytest
# One standard Windows box shares setup across the required build/site checks
# and the observational portability inventory. Serial worker bounds keep this
# recovery path portable; Linux owns duplicate lint, coverage, and snapshots.
# The required pull-request Windows signal: the two blocking win32 surfaces
# (workspace build, production site) execute with real, checksum-verified
# Windows Node under Wine on standard hosted Linux. The master
# serial-windows job below keeps the complete native-kernel inventory —
# including the observational portability gates this lane does not run —
# on real windows-2025. Direct tool entrypoints stand in for pnpm's cmd
# shims, which a Linux-side install does not create; layout, fidelity
# limits, and measured timings live in
# .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
windows:
if: github.event_name == 'pull_request'
runs-on: windows-2025
name: windows node 24 / complete
runs-on: ubuntu-latest
name: windows node 24 / wine blocking
timeout-minutes: 15
env:
DSH_COVERAGE_MAX_WORKERS: '1'
DSH_GATE_CONCURRENCY: '1'
DSH_PUBLINT_CONCURRENCY: '1'
WINEDEBUG: '-all'
WINEARCH: win64
# Skip Wine Mono / Gecko installers: Node needs neither.
WINEDLLOVERRIDES: 'mscoree,mshtml='
steps:
- uses: actions/checkout@v6
- name: Enable Developer Mode (symlink support)
shell: pwsh
run: >-
reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
/t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
with:
persist-credentials: false
- uses: actions/setup-node@v6
with:
node-version: ${{ env.PRIMARY_NODE_VERSION }}
# Extracting the many-file pnpm store cache is slower than a clean install,
# and saving it adds more latency after gates.
- name: Enable corepack and install (immutable)
shell: pwsh
- uses: actions/cache/restore@v4
with:
path: /home/runner/.local/share/pnpm/store/v11
key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
restore-keys: |
${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
# Master's wine-apt-cache job seeds the default-branch scope every pull
# request can read; a save from this job only reaches reruns of the
# same merge ref.
- name: Compose Wine apt cache key
id: wine-cache-key
run: echo "key=wine-debs-${ImageOS:-linux}-${ImageVersion:-v0}" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v4
with:
path: ~/wine-debs
key: ${{ steps.wine-cache-key.outputs.key }}
- name: Install dependencies and provision Wine concurrently
run: |
corepack enable
pnpm install --frozen-lockfile
- name: Run blocking and observational Windows gates concurrently
shell: pwsh
run: pnpm run check:ci:windows-complete
# Windows-lane install-time overrides. supportedArchitectures
# additionally materializes the win32-x64 platform packages
# (@esbuild/win32-x64, rolldown and rollup MSVC bindings) the
# Windows toolchain resolves at runtime; nodeLinker: hoisted lays
# node_modules out flat with real files because Windows Node under
# Wine does not realpath pnpm's isolated-layout symlinks. Neither
# override is recorded in the lockfile, so --frozen-lockfile stays
# valid. --ignore-scripts skips Linux lifecycle scripts no gate in
# this lane loads; the win32 binaries ship prebuilt.
cat >> pnpm-workspace.yaml <<'EOF'
nodeLinker: hoisted
supportedArchitectures:
os: [current, win32]
cpu: [current, x64]
EOF
pnpm install --frozen-lockfile --ignore-scripts &
install_pid=$!
provision_wine() {
set -euo pipefail
# Wine from the apt cache when present; else download the full
# dependency closure once and keep it for the next run. The
# `wine` dispatcher package (not bare `wine64`) is what puts a
# binary on PATH.
if compgen -G "$HOME/wine-debs/*.deb" > /dev/null; then
sudo apt-get install -y --no-install-recommends "$HOME"/wine-debs/*.deb
else
sudo apt-get update
sudo apt-get install -y --no-install-recommends --download-only wine
mkdir -p "$HOME/wine-debs"
cp /var/cache/apt/archives/*.deb "$HOME/wine-debs/" 2>/dev/null || true
sudo apt-get install -y --no-install-recommends wine
fi
WINE_BIN=''
for candidate in "$(command -v wine || true)" "$(command -v wine64 || true)" /usr/lib/wine/wine64; do
if [ -n "$candidate" ] && [ -x "$candidate" ]; then WINE_BIN="$candidate"; break; fi
done
[ -n "$WINE_BIN" ] || { echo '::error::no wine binary found after install'; exit 1; }
echo "WINE_BIN=$WINE_BIN" >> "$GITHUB_ENV"
# Windows Node for the repo's primary line, checksum-verified
# against the same dist directory.
version=$(curl -fsSL https://nodejs.org/dist/index.json \
| jq -r --arg p "v${PRIMARY_NODE_VERSION}." '[.[] | select(.version | startswith($p))][0].version')
echo "Windows Node: $version"
curl -fsSL -o "$RUNNER_TEMP/node-win.zip" \
"https://nodejs.org/dist/${version}/node-${version}-win-x64.zip"
curl -fsSL "https://nodejs.org/dist/${version}/SHASUMS256.txt" \
| awk -v a="node-${version}-win-x64.zip" '$2 == a { print $1 " '"$RUNNER_TEMP"'/node-win.zip" }' \
| sha256sum --check -
unzip -q "$RUNNER_TEMP/node-win.zip" -d "$RUNNER_TEMP/node-win"
echo "NODE_WIN=$RUNNER_TEMP/node-win/node-${version}-win-x64/node.exe" >> "$GITHUB_ENV"
"$WINE_BIN" wineboot --init || true
wineserver -w || true
}
provision_wine &
wine_pid=$!
install_status=0
wait "$install_pid" || install_status=$?
wine_status=0
wait "$wine_pid" || wine_status=$?
if (( install_status != 0 )); then exit "$install_status"; fi
exit "$wine_status"
- name: Resolve entrypoints, link vue, smoke Windows Node
run: |
# Node under Wine cannot attach stdio to the Actions runner's pipes
# (Socket open EBADF at bootstrap), so every invocation runs through
# this wrapper: stdio to a regular file, replayed after exit.
cat > "$RUNNER_TEMP/wine-node.sh" <<'SH'
#!/usr/bin/env bash
set -u
log="$1"; shift
"$WINE_BIN" "$NODE_WIN" "$@" < /dev/null > "$log" 2>&1
status=$?
tail -n 300 "$log"
exit "$status"
SH
chmod +x "$RUNNER_TEMP/wine-node.sh"
resolve() {
local name="$1"; shift
for p in "$@"; do
if [ -f "$p" ]; then echo "$name=$PWD/$p" >> "$GITHUB_ENV"; return 0; fi
done
echo "::error::$name not found at any of: $*"; return 1
}
resolve TSC_JS node_modules/typescript/bin/tsc
resolve TSDOWN_JS node_modules/tsdown/dist/run.mjs
resolve VITEPRESS_JS website/node_modules/vitepress/bin/vitepress.js node_modules/vitepress/bin/vitepress.js
# VitePress links vue into the site's node_modules at build time;
# Wine cannot CREATE Windows symlinks (ENOTSUP) but follows
# pre-existing Unix ones, so lay the link down host-side.
if [ -d node_modules/vue ] && [ ! -e website/node_modules/vue ]; then
mkdir -p website/node_modules
ln -s ../../node_modules/vue website/node_modules/vue
fi
"$RUNNER_TEMP/wine-node.sh" "$RUNNER_TEMP/smoke.log" -p "'smoke: ' + process.platform + ' ' + process.arch + ' ' + process.version"
# The two blocking surfaces run concurrently, the same shape run-gates
# gives ci-windows-blocking on native Windows: `build` = tsc -b then
# tsdown, `production site` = the VitePress build. Both statuses are
# captured so one failure cannot hide the other's result.
- name: Run blocking Windows gates concurrently under Wine
run: |
build_gate() {
"$RUNNER_TEMP/wine-node.sh" "$RUNNER_TEMP/tsc.log" "$TSC_JS" -b --pretty false || return $?
"$RUNNER_TEMP/wine-node.sh" "$RUNNER_TEMP/tsdown.log" "$TSDOWN_JS"
}
site_gate() {
cd website
"$RUNNER_TEMP/wine-node.sh" "$RUNNER_TEMP/site.log" "$VITEPRESS_JS" build .
}
start=$SECONDS
build_gate > "$RUNNER_TEMP/build-gate.out" 2>&1 &
build_pid=$!
site_gate > "$RUNNER_TEMP/site-gate.out" 2>&1 &
site_pid=$!
build_status=0
wait "$build_pid" || build_status=$?
site_status=0
wait "$site_pid" || site_status=$?
echo "== build gate (exit $build_status, $((SECONDS - start))s elapsed) =="
tail -n 120 "$RUNNER_TEMP/build-gate.out"
echo "== production site gate (exit $site_status, $((SECONDS - start))s elapsed) =="
tail -n 120 "$RUNNER_TEMP/site-gate.out"
if (( build_status != 0 )); then exit "$build_status"; fi
exit "$site_status"
- name: Shut down wineserver
if: always()
run: wineserver -k 2>/dev/null || true
# Master seeds the Wine apt-archive cache in the default-branch scope,
# which every pull request's windows job can restore; saves from
# pull-request runs are scoped to their own merge ref and help nobody
# else. Runs in seconds when the image version already has a cache.
wine-apt-cache:
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
name: wine apt cache
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Compose Wine apt cache key
id: wine-cache-key
run: echo "key=wine-debs-${ImageOS:-linux}-${ImageVersion:-v0}" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v4
id: wine-cache
with:
path: ~/wine-debs
key: ${{ steps.wine-cache-key.outputs.key }}
- name: Download the Wine dependency closure
if: steps.wine-cache.outputs.cache-hit != 'true'
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends --download-only wine
mkdir -p "$HOME/wine-debs"
cp /var/cache/apt/archives/*.deb "$HOME/wine-debs/"
du -sh "$HOME/wine-debs"
# Master pushes run only the serial reference jobs below.
# Each host executes the complete, unsharded primary Node aggregate with one

View File

@@ -1,230 +0,0 @@
# EXPERIMENT: run the blocking Windows CI gates on a Linux runner through
# Wine with a real Windows Node.js binary, at roughly the wall clock of the
# Linux CI jobs (~2 min). Speed comes from four levers: the master-refreshed
# pnpm store cache, provisioning Wine concurrently with the dependency
# install, running the two blocking surfaces concurrently (the same shape
# run-gates gives them on native Windows), and an apt package cache for Wine
# itself. Dependency provisioning happens natively on Linux with
# `supportedArchitectures` extended to win32-x64 so the Windows
# esbuild/rolldown/rollup binaries are present, and `nodeLinker: hoisted`
# because Windows Node under Wine does not realpath pnpm's isolated-layout
# Unix symlinks — the sibling prototype in PR #689 kept the isolated layout
# and failed on exactly that. The pnpm-run/cmd shim layer is deliberately
# bypassed; each gate invokes its tool's JavaScript entrypoint directly — the
# same commands run-gates ultimately spawns. Owning rationale and promotion
# criteria:
# .agents/notes/proposed/process/2026-07-27-wine-windows-gates-experiment.md
name: Experiment Wine Windows gates
on:
workflow_dispatch:
pull_request:
paths:
- .github/workflows/exp-wine-windows.yml
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
permissions:
contents: read
env:
PRIMARY_NODE_VERSION: '24'
jobs:
wine-blocking-gates:
name: wine / blocking windows gates (${{ matrix.runner }})
# Pull requests run the free standard runner only; a manual dispatch adds
# the 8-core benchmark pool for a like-for-like core-count comparison.
# The larger leg stays dispatch-only because those restricted pools can
# queue indefinitely (observed on the sibling KVM experiment).
runs-on: ${{ matrix.runner }}
strategy:
fail-fast: false
matrix:
runner: ${{ fromJSON(github.event_name == 'workflow_dispatch' && '["ubuntu-latest", "dsh-ubuntu-24-04-8core"]' || '["ubuntu-latest"]') }}
timeout-minutes: 30
env:
WINEDEBUG: '-all'
WINEARCH: win64
# Skip Wine Mono / Gecko installers: Node needs neither.
WINEDLLOVERRIDES: 'mscoree,mshtml='
steps:
- uses: actions/checkout@v6
with:
persist-credentials: false
- uses: actions/setup-node@v6
with:
node-version: ${{ env.PRIMARY_NODE_VERSION }}
# The default-branch pnpm store cache ci.yml maintains; restore-only,
# same key, so this lane rides the cache master already refreshes.
- uses: actions/cache/restore@v4
with:
path: /home/runner/.local/share/pnpm/store/v11
key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
restore-keys: |
${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
# Keyed on the runner image so a new image version re-downloads once.
# Cache scoping: each trigger seeds its own scope (pull_request → the
# PR merge ref, dispatch → the branch); only same-scope reruns hit.
# Promotion to ci.yml would let master seed the shared default-branch
# scope every trigger reads, as the pnpm store cache already does.
- name: Compose Wine apt cache key
id: wine-cache-key
run: echo "key=wine-debs-${ImageOS:-linux}-${ImageVersion:-v0}" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v4
with:
path: ~/wine-debs
key: ${{ steps.wine-cache-key.outputs.key }}
- name: Install dependencies and provision Wine concurrently
run: |
corepack enable
# Experiment-only install-time overrides. supportedArchitectures
# additionally materializes the win32-x64 platform packages
# (@esbuild/win32-x64, rolldown and rollup MSVC bindings) the
# Windows toolchain resolves at runtime; nodeLinker: hoisted lays
# node_modules out flat with real files because Windows Node under
# Wine does not realpath pnpm's isolated-layout symlinks (PR #689's
# failure mode). Neither override is recorded in the lockfile, so
# --frozen-lockfile stays valid. --ignore-scripts skips the Linux
# esbuild/node-pty/lefthook lifecycle scripts: no gate in this lane
# loads them, and the win32 binaries ship prebuilt in their
# packages.
cat >> pnpm-workspace.yaml <<'EOF'
nodeLinker: hoisted
supportedArchitectures:
os: [current, win32]
cpu: [current, x64]
EOF
pnpm install --frozen-lockfile --ignore-scripts &
install_pid=$!
provision_wine() {
set -euo pipefail
# Wine from the apt cache when present; else download the full
# dependency closure once and keep it for the next run. The
# `wine` dispatcher package (not bare `wine64`) is what puts a
# binary on PATH.
if compgen -G "$HOME/wine-debs/*.deb" > /dev/null; then
sudo apt-get install -y --no-install-recommends "$HOME"/wine-debs/*.deb
else
sudo apt-get update
sudo apt-get install -y --no-install-recommends --download-only wine
mkdir -p "$HOME/wine-debs"
cp /var/cache/apt/archives/*.deb "$HOME/wine-debs/" 2>/dev/null || true
sudo apt-get install -y --no-install-recommends wine
fi
WINE_BIN=''
for candidate in "$(command -v wine || true)" "$(command -v wine64 || true)" /usr/lib/wine/wine64; do
if [ -n "$candidate" ] && [ -x "$candidate" ]; then WINE_BIN="$candidate"; break; fi
done
[ -n "$WINE_BIN" ] || { echo '::error::no wine binary found after install'; exit 1; }
echo "WINE_BIN=$WINE_BIN" >> "$GITHUB_ENV"
# Windows Node for the repo's primary line, checksum-verified
# against the same dist directory (adopted from PR #689).
version=$(curl -fsSL https://nodejs.org/dist/index.json \
| jq -r --arg p "v${PRIMARY_NODE_VERSION}." '[.[] | select(.version | startswith($p))][0].version')
echo "Windows Node: $version"
curl -fsSL -o "$RUNNER_TEMP/node-win.zip" \
"https://nodejs.org/dist/${version}/node-${version}-win-x64.zip"
curl -fsSL "https://nodejs.org/dist/${version}/SHASUMS256.txt" \
| awk -v a="node-${version}-win-x64.zip" '$2 == a { print $1 " '"$RUNNER_TEMP"'/node-win.zip" }' \
| sha256sum --check -
unzip -q "$RUNNER_TEMP/node-win.zip" -d "$RUNNER_TEMP/node-win"
echo "NODE_WIN=$RUNNER_TEMP/node-win/node-${version}-win-x64/node.exe" >> "$GITHUB_ENV"
"$WINE_BIN" wineboot --init || true
wineserver -w || true
}
provision_wine &
wine_pid=$!
install_status=0
wait "$install_pid" || install_status=$?
wine_status=0
wait "$wine_pid" || wine_status=$?
if (( install_status != 0 )); then exit "$install_status"; fi
exit "$wine_status"
- name: Resolve entrypoints, link vue, smoke Windows Node
run: |
# Node under Wine cannot attach stdio to the Actions runner's pipes
# (Socket open EBADF at bootstrap), so every invocation runs through
# this wrapper: stdio to a regular file, replayed after exit.
cat > "$RUNNER_TEMP/wine-node.sh" <<'SH'
#!/usr/bin/env bash
set -u
log="$1"; shift
"$WINE_BIN" "$NODE_WIN" "$@" < /dev/null > "$log" 2>&1
status=$?
tail -n 300 "$log"
exit "$status"
SH
chmod +x "$RUNNER_TEMP/wine-node.sh"
resolve() {
local name="$1"; shift
for p in "$@"; do
if [ -f "$p" ]; then echo "$name=$PWD/$p" >> "$GITHUB_ENV"; return 0; fi
done
echo "::error::$name not found at any of: $*"; return 1
}
resolve TSC_JS node_modules/typescript/bin/tsc
resolve TSDOWN_JS node_modules/tsdown/dist/run.mjs
resolve VITEPRESS_JS website/node_modules/vitepress/bin/vitepress.js node_modules/vitepress/bin/vitepress.js
# VitePress links vue into the site's node_modules at build time;
# Wine cannot CREATE Windows symlinks (ENOTSUP) but follows
# pre-existing Unix ones, so lay the link down host-side.
if [ -d node_modules/vue ] && [ ! -e website/node_modules/vue ]; then
mkdir -p website/node_modules
ln -s ../../node_modules/vue website/node_modules/vue
fi
"$RUNNER_TEMP/wine-node.sh" "$RUNNER_TEMP/smoke.log" -p "'smoke: ' + process.platform + ' ' + process.arch + ' ' + process.version"
# The two blocking surfaces run concurrently, the same shape run-gates
# gives ci-windows-blocking on native Windows (DSH_GATE_CONCURRENCY):
# `build` = tsc -b then tsdown, `production site` = the VitePress
# build. Both statuses are captured so one failure cannot hide the
# other's result.
- name: Run blocking Windows gates concurrently under Wine
timeout-minutes: 20
run: |
build_gate() {
"$RUNNER_TEMP/wine-node.sh" "$RUNNER_TEMP/tsc.log" "$TSC_JS" -b --pretty false || return $?
"$RUNNER_TEMP/wine-node.sh" "$RUNNER_TEMP/tsdown.log" "$TSDOWN_JS"
}
site_gate() {
cd website
"$RUNNER_TEMP/wine-node.sh" "$RUNNER_TEMP/site.log" "$VITEPRESS_JS" build .
}
start=$SECONDS
build_gate > "$RUNNER_TEMP/build-gate.out" 2>&1 &
build_pid=$!
site_gate > "$RUNNER_TEMP/site-gate.out" 2>&1 &
site_pid=$!
build_status=0
wait "$build_pid" || build_status=$?
site_status=0
wait "$site_pid" || site_status=$?
echo "== build gate (exit $build_status, $((SECONDS - start))s elapsed) =="
tail -n 120 "$RUNNER_TEMP/build-gate.out"
echo "== production site gate (exit $site_status, $((SECONDS - start))s elapsed) =="
tail -n 120 "$RUNNER_TEMP/site-gate.out"
if (( build_status != 0 )); then exit "$build_status"; fi
exit "$site_status"
- name: Shut down wineserver
if: always()
run: wineserver -k 2>/dev/null || true