build: use sqlite3 1.1.3 ARM musl prebuilds (#3105 )

fix: isolate Alpine Node runtime and bound URL probes (#3104 )
Pin Alpine amd64 to the verified upstream Node runtime without retaining temporary binaries in image layers. Bound fresh-process URL probes and verify serialized amd64/ARMv6 layers in CI. Keep existing Sequelize, SQLite and Debian runtime behavior unchanged.
2026-11-03 16:19:11 +08:00 · 2026-10-24 17:40:47 +08:00 · 2026-10-23 23:34:24 +08:00
10 changed files with 278 additions and 42 deletions
@@ -6,6 +6,11 @@ on:
      - '.github/workflows/release-readiness.yml'
      - 'package.json'
      - 'pnpm-lock.yaml'
+      - 'docker/Dockerfile*'
+      - 'shell/node-runtime-probe.cjs'
+      - 'scripts/verify-panel-package.cjs'
+      - 'scripts/verify-image-node-layers.py'
+      - 'test/back/node-runtime-probe.test.cjs'
  workflow_dispatch:

 permissions:
@@ -41,6 +46,13 @@ jobs:
          path: static/
          include-hidden-files: true
          if-no-files-found: error
+      - name: Pack the verified npm archive for isolated runtime validation
+        run: node scripts/verify-panel-package.cjs pack "$RUNNER_TEMP/npm-panel"
+      - uses: actions/upload-artifact@v6
+        with:
+          name: release-readiness-npm-panel
+          path: ${{ runner.temp }}/npm-panel/
+          if-no-files-found: error

  images:
    needs: [regression, static]
@@ -121,16 +133,47 @@ jobs:
          docker run --rm --network none --entrypoint node \
            qinglong-readiness:${{ matrix.image }} \
            -e 'const assert=require("node:assert/strict"); const {createRequire}=require("node:module"); for(const [name,want] of Object.entries({"@grpc/grpc-js":"1.14.5",compression:"1.8.2",multer:"2.4.0",sequelize:"6.37.8"}))assert.equal(require(name+"/package.json").version,want); const expressRequire=createRequire(require.resolve("express")); assert.equal(expressRequire("proxy-addr/package.json").version,"2.0.8"); const sockRequire=createRequire(require.resolve("sockjs")); assert.equal(sockRequire("websocket-driver/package.json").version,"0.7.5"); require("sqlite3"); require("nodemailer"); require("undici"); console.log("Minimal production patches and runtime imports verified")'
-      - name: Export native Debian image for isolated dev validation
-        if: matrix.image == 'debian'
-        run: |
-          docker save qinglong-readiness:debian | gzip -1 > release-readiness-debian-image.tar.gz
-          sha256sum release-readiness-debian-image.tar.gz > release-readiness-debian-image.sha256
-          docker image inspect qinglong-readiness:debian > release-readiness-debian-image.json
-      - uses: actions/upload-artifact@v6
-        if: matrix.image == 'debian'
+      - name: Load ARMv6 image for SQLite and Node regression checks
+        if: startsWith(matrix.image, 'alpine')
+        uses: docker/build-push-action@v7
        with:
-          name: release-readiness-debian-image
-          path: release-readiness-debian-image.*
+          context: .
+          file: ${{ matrix.file }}
+          platforms: linux/arm/v6
+          build-args: |
+            QL_URL=${{ steps.source.outputs.url }}
+            QL_BRANCH=${{ steps.source.outputs.branch }}
+            SOURCE_COMMIT=${{ steps.source.outputs.sha }}
+          tags: qinglong-readiness:${{ matrix.image }}-armv6
+          load: true
+          push: false
+          provenance: false
+          sbom: false
+      - name: Verify ARMv6 SQLite on an ARM1176 CPU without networking
+        if: startsWith(matrix.image, 'alpine')
+        run: |
+          docker run --rm --network none --platform linux/arm/v6 \
+            -e QEMU_CPU=arm1176 --entrypoint node \
+            qinglong-readiness:${{ matrix.image }}-armv6 --jitless \
+            -e 'const assert=require("node:assert/strict"); const sqlite3=require("sqlite3"); const db=new sqlite3.Database(":memory:"); db.get("SELECT 42 AS n",(error,row)=>{assert.ifError(error); assert.equal(row.n,42); db.close()});'
+      - name: Check Node binaries in every serialized image layer
+        if: startsWith(matrix.image, 'alpine')
+        run: |
+          docker save qinglong-readiness:${{ matrix.image }} -o "$RUNNER_TEMP/node-layers-amd64.tar"
+          docker save qinglong-readiness:${{ matrix.image }}-armv6 -o "$RUNNER_TEMP/node-layers-arm.tar"
+          python3 scripts/verify-image-node-layers.py "$RUNNER_TEMP/node-layers-amd64.tar" amd64
+          python3 scripts/verify-image-node-layers.py "$RUNNER_TEMP/node-layers-arm.tar" arm
+          rm "$RUNNER_TEMP/node-layers-amd64.tar" "$RUNNER_TEMP/node-layers-arm.tar"
+      - name: Export native image for isolated dev validation
+        if: matrix.image == 'debian' || matrix.image == 'alpine'
+        run: |
+          docker save qinglong-readiness:${{ matrix.image }} | gzip -1 > release-readiness-${{ matrix.image }}-image.tar.gz
+          sha256sum release-readiness-${{ matrix.image }}-image.tar.gz > release-readiness-${{ matrix.image }}-image.sha256
+          docker image inspect qinglong-readiness:${{ matrix.image }} > release-readiness-${{ matrix.image }}-image.json
+      - uses: actions/upload-artifact@v6
+        if: matrix.image == 'debian' || matrix.image == 'alpine'
+        with:
+          name: release-readiness-${{ matrix.image }}-image
+          path: release-readiness-${{ matrix.image }}-image.*
          compression-level: 0
          if-no-files-found: error
@@ -3,6 +3,7 @@
 FROM --platform=$BUILDPLATFORM node:18-alpine3.18 AS builder

 ARG TARGETARCH
+ARG TARGETVARIANT
 ENV NPM_CONFIG_PREFIX=/opt/node-global
 ENV PATH=/opt/node-global/bin:${PATH}

@@ -17,13 +18,25 @@ RUN set -x \
    ppc64le) NODE_ARCH=ppc64 ;; \
    *) NODE_ARCH="${TARGETARCH}" ;; \
  esac \
+  && case "${TARGETARCH}/${TARGETVARIANT:-}" in \
+    arm/v6) NODE_LIBC=musl-armv6 ;; \
+    arm/v7) NODE_LIBC=musl-armv7 ;; \
+    arm/*) echo "Unsupported ARM variant: ${TARGETVARIANT:-unknown}" >&2; exit 1 ;; \
+    *) NODE_LIBC=musl ;; \
+  esac \
  && npm_config_target_platform=linux \
    npm_config_target_arch="${NODE_ARCH}" \
-    npm_config_target_libc=musl \
-    pnpm install --prod --frozen-lockfile
+    npm_config_target_libc="${NODE_LIBC}" \
+    pnpm install --prod --frozen-lockfile --side-effects-cache=false
+
+# Pin amd64 to upstream's musl runtime after native URL parser crashes with APK Node.
+FROM --platform=linux/amd64 node:24.18.1-alpine3.24@sha256:f70403e87646dc51b45295f4b8b70cdad0b63d2297c4c9899119b03f7af7a6b3 AS node-runtime-amd64

 FROM python:3.11-alpine

+ARG TARGETARCH
+ARG TARGETVARIANT
+
 ARG QL_MAINTAINER="whyour"
 LABEL maintainer="${QL_MAINTAINER}"
 ARG QL_URL=https://github.com/${QL_MAINTAINER}/qinglong.git
@@ -44,7 +57,8 @@ EXPOSE 5700
 COPY --from=builder /opt/node-global/lib/node_modules/. /usr/local/lib/node_modules/
 COPY --from=builder /opt/node-global/bin/. /usr/local/bin/

-RUN set -x \
+RUN --mount=type=bind,from=node-runtime-amd64,source=/usr/local/bin/node,target=/tmp/node-runtime-amd64 \
+  set -x \
  && apk update -f \
  && apk upgrade \
  && apk --no-cache add -f bash \
@@ -62,6 +76,10 @@ RUN set -x \
  netcat-openbsd \
  unzip \
  npm \
+  && if [ "$TARGETARCH" = amd64 ]; then \
+       cp /tmp/node-runtime-amd64 /usr/local/bin/node; \
+       ln -sf /usr/local/bin/node /usr/bin/node; \
+     fi \
  && rm -rf /var/cache/apk/* \
  && apk update \
  && ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \
@@ -86,6 +104,10 @@ COPY static/ /ql/static/
 COPY docker/verify-build.cjs docker/build-manifest.cjs /tmp/
 COPY --from=builder /tmp/build/pnpm-lock.yaml /tmp/dependency-lock.yaml
 RUN cd ${QL_DIR} && node /tmp/verify-build.cjs /tmp/dependency-lock.yaml
+RUN if [ "$TARGETARCH" = arm ] && [ "${TARGETVARIANT:-}" = v6 ]; then \
+      QEMU_CPU=arm1176 node --jitless ${QL_DIR}/shell/node-runtime-probe.cjs; \
+    else node ${QL_DIR}/shell/node-runtime-probe.cjs; fi
+

 ENV PNPM_HOME=${QL_DIR}/data/dep_cache/node \
  PYTHON_HOME=${QL_DIR}/data/dep_cache/python3 \
@@ -3,6 +3,7 @@
 FROM --platform=$BUILDPLATFORM node:18-alpine3.18 AS builder

 ARG TARGETARCH
+ARG TARGETVARIANT
 ENV NPM_CONFIG_PREFIX=/opt/node-global
 ENV PATH=/opt/node-global/bin:${PATH}

@@ -17,13 +18,25 @@ RUN set -x \
    ppc64le) NODE_ARCH=ppc64 ;; \
    *) NODE_ARCH="${TARGETARCH}" ;; \
  esac \
+  && case "${TARGETARCH}/${TARGETVARIANT:-}" in \
+    arm/v6) NODE_LIBC=musl-armv6 ;; \
+    arm/v7) NODE_LIBC=musl-armv7 ;; \
+    arm/*) echo "Unsupported ARM variant: ${TARGETVARIANT:-unknown}" >&2; exit 1 ;; \
+    *) NODE_LIBC=musl ;; \
+  esac \
  && npm_config_target_platform=linux \
    npm_config_target_arch="${NODE_ARCH}" \
-    npm_config_target_libc=musl \
-    pnpm install --prod --frozen-lockfile
+    npm_config_target_libc="${NODE_LIBC}" \
+    pnpm install --prod --frozen-lockfile --side-effects-cache=false
+
+# Pin amd64 to upstream's musl runtime after native URL parser crashes with APK Node.
+FROM --platform=linux/amd64 node:24.18.1-alpine3.24@sha256:f70403e87646dc51b45295f4b8b70cdad0b63d2297c4c9899119b03f7af7a6b3 AS node-runtime-amd64

 FROM python:3.10-alpine

+ARG TARGETARCH
+ARG TARGETVARIANT
+
 ARG QL_MAINTAINER="whyour"
 LABEL maintainer="${QL_MAINTAINER}"
 ARG QL_URL=https://github.com/${QL_MAINTAINER}/qinglong.git
@@ -44,7 +57,8 @@ EXPOSE 5700
 COPY --from=builder /opt/node-global/lib/node_modules/. /usr/local/lib/node_modules/
 COPY --from=builder /opt/node-global/bin/. /usr/local/bin/

-RUN set -x \
+RUN --mount=type=bind,from=node-runtime-amd64,source=/usr/local/bin/node,target=/tmp/node-runtime-amd64 \
+  set -x \
  && apk update -f \
  && apk upgrade \
  && apk --no-cache add -f bash \
@@ -62,6 +76,10 @@ RUN set -x \
  netcat-openbsd \
  unzip \
  npm \
+  && if [ "$TARGETARCH" = amd64 ]; then \
+       cp /tmp/node-runtime-amd64 /usr/local/bin/node; \
+       ln -sf /usr/local/bin/node /usr/bin/node; \
+     fi \
  && rm -rf /var/cache/apk/* \
  && apk update \
  && ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \
@@ -86,6 +104,10 @@ COPY static/ /ql/static/
 COPY docker/verify-build.cjs docker/build-manifest.cjs /tmp/
 COPY --from=builder /tmp/build/pnpm-lock.yaml /tmp/dependency-lock.yaml
 RUN cd ${QL_DIR} && node /tmp/verify-build.cjs /tmp/dependency-lock.yaml
+RUN if [ "$TARGETARCH" = arm ] && [ "${TARGETVARIANT:-}" = v6 ]; then \
+      QEMU_CPU=arm1176 node --jitless ${QL_DIR}/shell/node-runtime-probe.cjs; \
+    else node ${QL_DIR}/shell/node-runtime-probe.cjs; fi
+

 ENV PNPM_HOME=${QL_DIR}/data/dep_cache/node \
  PYTHON_HOME=${QL_DIR}/data/dep_cache/python3 \
@@ -6,18 +6,6 @@ ENV QL_BUNDLE_BASE_IMAGE=${BASE_IMAGE}
 ARG TARGETARCH
 ARG TARGETVARIANT
 USER root
-# The generic "arm" sqlite release is ARMv7. ARMv6 must compile its own addon.
-RUN ulimit -c 0; if [ "$TARGETARCH/$TARGETVARIANT" = arm/v6 ]; then \
-      apk add --no-cache --virtual .ql-bundle-build build-base binutils python3 nodejs-dev && \
-      cd "$(readlink -f /ql/node_modules/sqlite3)" && \
-      CFLAGS='-march=armv6 -mfpu=vfp -mfloat-abi=hard' \
-      CXXFLAGS='-march=armv6 -mfpu=vfp -mfloat-abi=hard' \
-      npm_config_nodedir=/usr npm_config_build_from_source=true QEMU_CPU=arm1176 \
-        node -e 'require("node:child_process").execFileSync(process.execPath,[require.resolve("@mapbox/node-pre-gyp/bin/node-pre-gyp"),"rebuild","--napi_build_version=6"],{stdio:"inherit"})' && \
-      readelf -A lib/binding/napi-v6-linux-arm/node_sqlite3.node | grep -E 'Tag_CPU_arch: v6($|K)' && \
-      rm -rf build && \
-      apk del .ql-bundle-build; \
-    fi
 RUN ulimit -c 0; if [ "$TARGETARCH/$TARGETVARIANT" = arm/v6 ]; then \
      export QEMU_CPU=arm1176; \
      node --jitless /ql/scripts/build-upgrade-bundle.cjs /ql /out && \
@@ -111,7 +111,7 @@
      }
    },
    "overrides": {
-      "sqlite3": "npm:@whyour/sqlite3@1.1.2",
+      "sqlite3": "npm:@whyour/sqlite3@1.1.3",
      "@codemirror/state": "6.5.4",
      "@codemirror/view": "6.39.16",
      "proxy-addr": "2.0.8",
@@ -159,7 +159,7 @@
    "request-ip": "3.3.0",
    "sequelize": "6.37.8",
    "sockjs": "^0.3.24",
-    "sqlite3": "npm:@whyour/sqlite3@1.1.2",
+    "sqlite3": "npm:@whyour/sqlite3@1.1.3",
    "toad-scheduler": "^3.0.1",
    "typedi": "^0.10.0",
    "undici": "^7.9.0",
@@ -1,7 +1,7 @@
 lockfileVersion: '6.0'

 overrides:
-  sqlite3: npm:@whyour/sqlite3@1.1.2
+  sqlite3: npm:@whyour/sqlite3@1.1.3
  '@codemirror/state': 6.5.4
  '@codemirror/view': 6.39.16
  proxy-addr: 2.0.8
@@ -120,13 +120,13 @@ dependencies:
    version: 3.3.0
  sequelize:
    specifier: 6.37.8
-    version: 6.37.8(@whyour/sqlite3@1.1.2)
+    version: 6.37.8(@whyour/sqlite3@1.1.3)
  sockjs:
    specifier: ^0.3.24
    version: 0.3.24
  sqlite3:
-    specifier: npm:@whyour/sqlite3@1.1.2
-    version: /@whyour/sqlite3@1.1.2
+    specifier: npm:@whyour/sqlite3@1.1.3
+    version: /@whyour/sqlite3@1.1.3
  tar:
    specifier: 7.5.20
    version: 7.5.20
@@ -3193,7 +3193,7 @@ packages:
    resolution: {integrity: sha512-Ngs9jhElXN7efS9WvvCC/p6rXMbihna8eNLVBc421Zf+VcFd+pR4DOcS6yA9V22EKtAy4DEj7LtvEEIm0bb80A==}
    engines: {node: '>= 18'}
    dependencies:
-      sqlite3: /@whyour/sqlite3@1.1.2
+      sqlite3: /@whyour/sqlite3@1.1.3
    transitivePeerDependencies:
      - encoding
      - supports-color
@@ -5611,14 +5611,15 @@ packages:
      - supports-color
    dev: true

-  /@whyour/sqlite3@1.1.2:
-    resolution: {integrity: sha512-OY24/OJMqLHIGolo4GCFW4lrJKAoOB+ZqERXb7u7DKZQz7QR3f0GALE99BZWQBSZEVVZ/StVeAb2fCkMfTtuDQ==}
+  /@whyour/sqlite3@1.1.3:
+    resolution: {integrity: sha512-VeiureU2gq11OMeSMWlpckNfbY5QF+V0KEpRi1Zqh/s5GEPgCazt06xIg528tPAwK0MS9KCUEyLb+dKDIIFoEg==}
    requiresBuild: true
    peerDependenciesMeta:
      node-gyp:
        optional: true
    dependencies:
      '@mapbox/node-pre-gyp': 1.0.11
+      detect-libc: 1.0.3
      node-addon-api: 4.3.0
      tar: 6.2.1
    optionalDependencies:
@@ -7601,7 +7602,6 @@ packages:
    resolution: {integrity: sha512-pGjwhsmsp4kL2RTz08wcOlGN83otlqHeD/Z5T8GXZB+/YcpQ/dgo+lbU8ZsGxV0HIvqqxo9l7mqYwyYMD9bKDg==}
    engines: {node: '>=0.10'}
    hasBin: true
-    dev: true

  /detect-libc@2.1.2:
    resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
@@ -13903,7 +13903,7 @@ packages:
    engines: {node: '>= 10.0.0'}
    dev: false

-  /sequelize@6.37.8(@whyour/sqlite3@1.1.2):
+  /sequelize@6.37.8(@whyour/sqlite3@1.1.3):
    resolution: {integrity: sha512-HJ0IQFqcTsTiqbEgiuioYFMSD00TP6Cz7zoTti+zVVBwVe9fEhev9cH6WnM3XU31+ABS356durAb99ZuOthnKw==}
    engines: {node: '>=10.0.0'}
    peerDependencies:
@@ -13948,7 +13948,7 @@ packages:
      retry-as-promised: 7.0.4
      semver: 7.7.4
      sequelize-pool: 7.1.0
-      sqlite3: /@whyour/sqlite3@1.1.2
+      sqlite3: /@whyour/sqlite3@1.1.3
      toposort-class: 1.0.1
      uuid: 8.3.2
      validator: 13.12.0
@@ -0,0 +1,44 @@
+"""Check serialized Docker layers, including files hidden by later deletions."""
+
+import hashlib
+import json
+import sys
+import tarfile
+
+archive, architecture = sys.argv[1:]
+assert architecture in {"amd64", "arm"}
+nodes = []
+with tarfile.open(archive) as image:
+    manifests = json.load(image.extractfile("manifest.json"))
+    assert len(manifests) == 1, "Expected one platform image"
+    manifest = manifests[0]
+    config = json.load(image.extractfile(manifest["Config"]))
+    assert config["architecture"] == architecture
+    for name in manifest["Layers"]:
+        with tarfile.open(fileobj=image.extractfile(name), mode="r|*") as layer:
+            for member in layer:
+                filename = member.name.removeprefix("./")
+                assert not (
+                    filename == "tmp/node-runtime-amd64" and member.size > 0
+                ), "Temporary amd64 Node remains in an immutable layer"
+                if filename not in {"usr/local/bin/node", "usr/bin/node"}:
+                    continue
+                if not member.isfile():
+                    continue
+                with layer.extractfile(member) as binary:
+                    header = binary.read(20)
+                    assert header[:4] == b"\x7fELF", "Expected a native Node binary"
+                    digest = hashlib.sha256(header)
+                    while chunk := binary.read(1024 * 1024):
+                        digest.update(chunk)
+                endian = "little" if header[5] == 1 else "big"
+                machine = int.from_bytes(header[18:20], endian)
+                assert machine == {"amd64": 62, "arm": 40}[architecture], (
+                    "Wrong Node architecture in an image layer"
+                )
+                nodes.append({"path": filename, "size": member.size, "sha256": digest.hexdigest()})
+assert len(nodes) == 1, "Expected exactly one retained Node binary across all layers"
+assert nodes[0]["path"] == (
+    "usr/local/bin/node" if architecture == "amd64" else "usr/bin/node"
+)
+print(json.dumps({"pass": True, "architecture": architecture, "layers": len(manifest["Layers"]), "nodes": nodes}))
@@ -23,7 +23,7 @@ const run = (program, args, options = {}) => execute(program, args, {
 const requiredFiles = [
  '.env.example', 'back/protos/api.proto', 'ecosystem.config.js', 'version.yaml',
  'shell/upgrade.cjs', 'shell/install-bundle.cjs', 'shell/install-package.cjs',
-  'shell/upgrade-lock.yaml', 'shell/start.sh', 'shell/start-simplify.sh',
+  'shell/upgrade-lock.yaml', 'shell/node-runtime-probe.cjs', 'shell/start.sh', 'shell/start-simplify.sh',
  'shell/task.sh', 'shell/preload/client.js', 'shell/preload/client.py',
  'shell/preload/sitecustomize.js', 'shell/preload/sitecustomize.py',
  'shell/preload/esm-loader.mjs', 'shell/preload/notificationAudit.js',
@@ -191,6 +191,12 @@ async function verifyPanel(input, output) {
    const globalRoot = (await run('npm', ['root', '--global', '--prefix', prefix], { cwd: temp, env })).stdout.trim();
    root = path.join(globalRoot, '@whyour/qinglong');
    env.QL_DIR = root;
+    const runtimeProbes = [];
+    const checkRuntime = async () => {
+      const result = await run(process.execPath, [path.join(root, 'shell/node-runtime-probe.cjs')], { cwd: temp, env, timeout: 540000 });
+      runtimeProbes.push(JSON.parse(result.stdout.trim()));
+    };
+    await checkRuntime();
    // Use a subprocess: cached candidate modules must not mask missing files
    // after old-package installation and the real npm overwrite below.
    await run(process.execPath, ['-e', `const root=process.argv[1],p=require('node:path');const m=require(root+'/package.json');for(const target of Object.values(m.bin))require('node:fs').accessSync(p.join(root,target));for(const name of ['platformBundle','upgradePrestart','panelUpgrade'])require(root+'/cli/src/internal/maintenance/'+name+'.cjs');require(root+'/shell/upgrade.cjs').verifyUpgrade(root,p.join(root,'static')).catch(e=>{console.error(e);process.exitCode=1});`, root], { env, cwd: temp });
@@ -287,6 +293,7 @@ async function verifyPanel(input, output) {
    const applying = await api('update/system', 'PUT');
    await job(applying.id, 'completed');
    const afterOnline = await healthy();
+    await checkRuntime();
    assert.notEqual(afterOnline.build.instanceId, original.build.instanceId);
    assert.equal(afterOnline.build.sourceCommit, fixture.sourceCommit);
    await fs.access(path.join(root, 'node_modules/.pnpm'));
@@ -302,6 +309,7 @@ async function verifyPanel(input, output) {
    assert.equal((await healthy()).build.instanceId, afterOnline.build.instanceId);
    await run(path.join(prefix, 'bin/ql'), ['reload', 'system'], { cwd: temp, env, timeout: 240000 });
    const afterOffline = await healthy();
+    await checkRuntime();
    assert.notEqual(afterOffline.build.instanceId, afterOnline.build.instanceId);
    assert.equal(afterOffline.build.sourceCommit, fixture.sourceCommit);
    await fs.access(path.join(root, 'node_modules/.pnpm'));
@@ -325,7 +333,7 @@ async function verifyPanel(input, output) {
      customRootEnvironmentPreservedAutomatically: true,
      officialPlatformBundle: { baseImage: fixture.baseImage, sourceCommit: fixture.sourceCommit, sha256: fixture.sha256 },
      migratedFromNpmToOfficialPnpmLayout: true,
-      existingNodePreserved: true,
+      existingNodePreserved: true, nativeUrlRuntimeProbes: runtimeProbes,
      frontendAndBackendStarted: true, checksumFailureKeptOldService: true,
      prestartBeforeReady: true, onlineActualRestart: true,
      offlinePreparationDidNotContactIndex: true, offlineBashActualRestart: true,
@@ -0,0 +1,62 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+// Run in new processes: a healthy parent can outlive a broken native runtime.
+function probeNodeRuntime(executable = process.execPath) {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'ql-node-url-'));
+  const source = `
+    const assert = require('node:assert/strict');
+    const { pathToFileURL, fileURLToPath } = require('node:url');
+    for (let i = 0; i < 1000; i++) {
+      assert.equal(new URL('/任务?q=' + i, 'https://example.com').hostname, 'example.com');
+      assert.equal(new URL('https://例子.测试').hostname, 'xn--fsqu00a.xn--0zwm56d');
+      assert.equal(new URL('http://[::1]:5700').port, '5700');
+      const filename = '/tmp/中文 path/' + i + '.cjs';
+      assert.equal(fileURLToPath(pathToFileURL(filename)), filename);
+    }
+    console.log('QINGLONG_NODE_URL_OK');
+  `;
+  const file = path.join(directory, 'probe.cjs');
+  fs.writeFileSync(file, source);
+  try {
+    for (let i = 0; i < 4; i++) {
+      const args = process.execArgv.includes('--jitless') ? ['--jitless'] : [];
+      args.push(...(i % 2 ? [file] : ['-e', source]));
+      const child = spawnSync(executable, args, {
+        encoding: 'utf8',
+        // Multi-architecture CI runs this same probe through QEMU.
+        timeout: 120000,
+        maxBuffer: 65536,
+        env: { ...process.env, NODE_OPTIONS: '' },
+      });
+      assert.equal(
+        child.status,
+        0,
+        `Node URL runtime probe failed (${i % 2 ? 'file' : 'eval'}): signal=${
+          child.signal
+        }; status=${child.status}; ${child.error?.message || child.stderr}`,
+      );
+      assert.match(child.stdout, /QINGLONG_NODE_URL_OK/);
+    }
+    return {
+      ok: true,
+      node: process.version,
+      architecture: process.arch,
+      ada: process.versions.ada,
+      processes: 4,
+      urlIterationsPerProcess: 1000,
+      nodeSha256: createHash('sha256')
+        .update(fs.readFileSync(executable))
+        .digest('hex'),
+    };
+  } finally {
+    fs.rmSync(directory, { recursive: true, force: true });
+  }
+}
+
+module.exports = { probeNodeRuntime };
+if (require.main === module) console.log(JSON.stringify(probeNodeRuntime()));
@@ -0,0 +1,47 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { probeNodeRuntime } = require('../../shell/node-runtime-probe.cjs');
+
+test('the retained Node handles URL, IDNA and file paths in fresh eval and file processes', () => {
+  const result = probeNodeRuntime();
+  assert.equal(result.ok, true);
+  assert.equal(result.processes, 4);
+  assert.match(result.nodeSha256, /^[0-9a-f]{64}$/);
+});
+
+test('a native child crash fails the runtime probe instead of accepting its healthy parent', (t) => {
+  if (process.platform === 'win32') return t.skip('POSIX crash fixture');
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'ql-node-crash-'));
+  t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+  const executable = path.join(directory, 'node');
+  fs.writeFileSync(executable, '#!/bin/sh\nkill -SEGV $$\n', { mode: 0o700 });
+  assert.throws(
+    () => probeNodeRuntime(executable),
+    /Node URL runtime probe failed.*SIGSEGV/,
+  );
+});
+
+test('emulated Node probes have a bounded two-minute budget and reject a timeout', (t) => {
+  const childProcess = require('node:child_process');
+  const modulePath = require.resolve('../../shell/node-runtime-probe.cjs');
+  let directory;
+  const makeDirectory = fs.mkdtempSync;
+  t.mock.method(fs, 'mkdtempSync', (...args) => {
+    directory = makeDirectory(...args);
+    return directory;
+  });
+  t.mock.method(childProcess, 'spawnSync', (_program, args, options) => {
+    assert.equal(options.timeout, 120000);
+    assert.equal(options.env.NODE_OPTIONS, '');
+    return { status: null, signal: 'SIGTERM', error: Object.assign(new Error('probe timed out'), { code: 'ETIMEDOUT' }) };
+  });
+  delete require.cache[modulePath];
+  t.after(() => { delete require.cache[modulePath]; });
+  const probe = require(modulePath).probeNodeRuntime;
+  assert.throws(() => probe(), /Node URL runtime probe failed.*SIGTERM.*probe timed out/);
+  assert.ok(directory);
+  assert.equal(fs.existsSync(directory), false, 'Timed-out probes must remove their temporary source files');
+});